Skill Authoring Guide Skill

Skill Authoring Guide

How to write skills that Claude can discover, understand, and apply effectively.

Core Principles

1. Context is a Shared Resource

MUST: Challenge every token—"Does Claude need this?"
MUST: Keep SKILL.md body under 500 lines
NEVER: Explain what Claude already knows (PDFs, libraries, common patterns)
SHOULD: Move heavy reference (100+ lines) to separate files

2. Description Enables Discovery

MUST: Write in third person (injected into system prompt)
MUST: Include both WHAT it does and WHEN to use it
MUST: Include specific triggers/symptoms/contexts
NEVER: Summarize the workflow in description (Claude may follow description instead of reading skill)
SHOULD: Start with action verb or "Use when..."

# WRONG: Summarizes workflow - Claude may skip reading the skill
description: Code review with two passes - first for spec compliance, then for quality

# WRONG: Too vague
description: Helps with testing

# CORRECT: Triggers only, no workflow
description: Use when executing implementation plans with independent tasks

# CORRECT: Specific with triggers
description: Extract text and tables from PDF files. Use when working with PDFs, forms, or document extraction.

3. Match Freedom to Fragility

| Freedom Level | When to Use | Example | |---------------|-------------|---------| | High (heuristics) | Multiple valid approaches | Code review guidelines | | Medium (templates) | Preferred pattern exists | Report generation | | Low (exact scripts) | Fragile, error-prone | Database migrations |

Skill Types & Formats

Reference Skills (CLI tools, APIs)

Best format: Command reference + Best practices

## Quick Start
[5-line example showing core workflow]

## Command Reference
[Organized by category with examples]

## Best Practices
[MUST/SHOULD/NEVER rules]

## Examples
[Real workflows]

Example: agent-browser, git commands

Technique Skills (how-to)

Best format: Pattern + Examples + Common mistakes

## Overview
[Core principle in 1-2 sentences]

## When to Use
[Symptoms and triggers]

## Core Pattern
[Before/after comparison]

## Implementation
[Steps or code]

## Common Mistakes
[What goes wrong + fixes]

Example: condition-based-waiting, root-cause-tracing

Discipline Skills (rules/requirements)

Best format: Iron Law + Phases + Rationalization prevention

## The Iron Law
[One rule that cannot be violated]

## Phases/Process
[Clear steps with gates]

## Red Flags - STOP
[Signs you're about to violate]

## Rationalization Prevention
[Table: Excuse | Reality]

Example: systematic-debugging, verification-before-completion, tdd-workflow

Pattern Skills (mental models)

Best format: Concept + Recognition + Application

## Overview
[What is this pattern?]

## When to Recognize
[Symptoms indicating pattern applies]

## How to Apply
[Steps or guidelines]

## When NOT to Apply
[Counter-examples]

The MUST/SHOULD/NEVER Format

When to Use

Reference documentation (commands, APIs)
Best practices and guidelines
Checklists and quality gates
Any skill where quick scanning matters

Structure

## Section Name

- MUST: Non-negotiable requirements
- SHOULD: Strong recommendations with valid exceptions
- NEVER: Absolute prohibitions
- MAY: Optional enhancements

Writing Effective Rules

# WRONG: Vague
- MUST: Handle errors properly

# WRONG: Too long
- MUST: When an error occurs, you should catch it and then log it with the full stack trace and context

# CORRECT: Specific and scannable
- MUST: Catch errors at boundaries; log with stack trace
- NEVER: Swallow errors silently

Combine with Context

## Forms

- MUST: Use `fill` (clears first) for inputs, not `type`
- MUST: `autocomplete` + meaningful `name`; correct `type` and `inputmode`
- SHOULD: Placeholders end with `…` and show example pattern
- NEVER: Block paste in `<input>`/`<textarea>`

Discipline Skills: Rationalization Prevention

For skills that enforce rules (TDD, verification, debugging), Claude will rationalize under pressure.

The Iron Law Pattern

State one unbreakable rule:

## The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you haven't completed Phase 1, you cannot propose fixes.

Red Flags List

Make it easy to self-check:

## Red Flags - STOP

If you catch yourself thinking:
- "Quick fix for now, investigate later"
- "Just try changing X and see"
- "I don't fully understand but this might work"

ALL of these mean: STOP. Return to Phase 1.

Rationalization Table

Capture excuses with counters:

| Excuse | Reality |
|--------|---------|
| "Too simple to need process" | Simple issues have root causes too |
| "Emergency, no time" | Systematic is faster than thrashing |
| "I'm confident" | Confidence ≠ evidence |
| "Just this once" | No exceptions |

Close Loopholes Explicitly

# WRONG: Just states rule
Write code before test? Delete it.

# CORRECT: Closes loopholes
Write code before test? Delete it. Start over.

**No exceptions:**
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Delete means delete

Progressive Disclosure

SKILL.md as Table of Contents

# PDF Processing

## Quick start
[Inline example]

## Core operations
[Inline patterns]

## Advanced features
**Form filling**: See [FORMS.md](FORMS.md)
**API reference**: See [REFERENCE.md](REFERENCE.md)

Claude loads referenced files only when needed.

When to Split Files

| Content Type | Where | |--------------|-------| | Patterns, concepts, quick ref | Inline in SKILL.md | | Heavy reference (100+ lines) | Separate file | | Reusable scripts | Separate file | | Domain-specific schemas | Separate files by domain |

Keep References One Level Deep

# WRONG: Nested references
SKILL.md → advanced.md → details.md → actual info

# CORRECT: Flat references
SKILL.md → advanced.md (complete info)
SKILL.md → reference.md (complete info)

Testing Skills

Test Before Deploying

MUST: Test skill with real scenarios before deploying
MUST: Test with the model(s) you'll use (Haiku needs more guidance than Opus)
SHOULD: Create 3+ evaluation scenarios
NEVER: Deploy untested skills

For Discipline Skills: Pressure Testing

Run scenario WITHOUT skill—document baseline behavior
Note rationalizations Claude uses
Write skill addressing those specific violations
Run scenario WITH skill—verify compliance
Find new rationalizations → add counters → re-test

Evaluation Structure

{
  "skills": ["pdf-processing"],
  "query": "Extract all text from this PDF file",
  "files": ["test-files/document.pdf"],
  "expected_behavior": [
    "Uses appropriate PDF library",
    "Extracts from all pages",
    "Saves to output file"
  ]
}

YAML Frontmatter

Required Fields

---
name: skill-name-with-hyphens
description: "Third-person description with triggers. Use when [specific conditions]."
version: 1.0.0
---

Constraints

| Field | Constraint | |-------|------------| | name | Max 64 chars, lowercase, letters/numbers/hyphens only | | description | Max 1024 chars, non-empty, no XML tags | | Reserved words | Cannot use "anthropic", "claude" in name |

Optional Fields

libraries: ["react", "zod"]  # If skill requires specific libraries

Common Patterns

Template Pattern

## Report Structure

Use this template:

# [Title]

## Summary
[One paragraph]

## Findings
- Finding 1
- Finding 2

## Recommendations
1. Action 1
2. Action 2

Examples Pattern

## Commit Messages

**Example 1:**
Input: Added user authentication
Output: `feat(auth): implement JWT authentication`

**Example 2:**
Input: Fixed date display bug
Output: `fix(reports): correct timezone in date formatting`

Conditional Workflow

## Workflow

1. Determine type:
   **Creating new?** → Follow Creation workflow
   **Editing existing?** → Follow Editing workflow

2. Creation workflow:
   - Step A
   - Step B

3. Editing workflow:
   - Step X
   - Step Y

Anti-Patterns

Content Anti-Patterns

| Anti-Pattern | Problem | Fix | |--------------|---------|-----| | Explaining basics | Wastes tokens | Assume Claude knows | | Time-sensitive info | Becomes stale | Use "old patterns" section | | Inconsistent terminology | Confuses | Pick one term, use throughout | | Multiple languages | Dilutes quality | One excellent example | | Narrative stories | Not reusable | Extract pattern |

Structure Anti-Patterns

| Anti-Pattern | Problem | Fix | |--------------|---------|-----| | Nested references | Partial reads | Keep one level deep | | Vague descriptions | Poor discovery | Specific triggers | | Workflow in description | Claude skips skill | Triggers only | | No table of contents | Hard to navigate | Add for 100+ lines | | Windows paths | Cross-platform issues | Use forward slashes |

Checklist

Before Publishing

Frontmatter:

[ ] Name: lowercase, hyphens, no reserved words
[ ] Description: third-person, triggers, no workflow summary
[ ] Version: semantic versioning

Content:

[ ] Under 500 lines (or progressive disclosure)
[ ] Consistent terminology
[ ] No time-sensitive information
[ ] Keywords for search (errors, symptoms, tools)

Format matches type:

[ ] Reference: commands + best practices
[ ] Technique: pattern + examples + mistakes
[ ] Discipline: iron law + red flags + rationalization table

Testing:

[ ] 3+ evaluation scenarios
[ ] Tested with target model(s)
[ ] Discipline skills: pressure tested

Integration

| Skill | Relationship | |-------|--------------| | testing-strategy | Testing approaches | | documentation-standards | Writing style | | design-principles | Structure decisions |

Agent Skills: Skill Authoring Guide

Install this agent skill to your local

Skill Files