Skill Authoring

About Skills

Skills are modular, self-contained packages that extend Claude's capabilities with specialized knowledge, workflows, and tools. They transform Claude from a general-purpose agent into a specialized agent equipped with procedural knowledge.

What Skills Provide

1. Specialized workflows - Multi-step procedures for specific domains
2. Tool integrations - Instructions for working with specific file formats or APIs
3. Domain expertise - Company-specific knowledge, schemas, business logic
4. Bundled resources - Scripts, references, and assets for complex tasks

When to use

• "Build me a new skill for X"
• "Create a skill that does Y"
• "Validate my skill structure"
• "Improve this existing skill"
• "What sections should a skill have?"

When NOT to use

• General coding tasks (use other skills or direct Claude)
• Questions about Claude Code itself (use claude-code-guide)
• Simple file operations that don't need a skill workflow

Core Principles

Concise is Key

The context window is a public good. Challenge each piece of information: "Does Claude really need this?" Prefer concise examples over verbose explanations.

Degrees of Freedom

Match specificity to task fragility:

Think of Claude exploring a path: a narrow bridge needs guardrails (low freedom), an open field allows many routes (high freedom).

Anatomy of a Skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name + description)
│   └── Markdown instructions
├── scripts/     - Executable code (Python/Bash)
├── references/  - Documentation loaded as needed
└── assets/      - Templates, binaries for output

SKILL.md Frontmatter

Only two required fields:

• name: The skill identifier (lowercase, hyphens)
• `description**: Triggers + purpose. Include "Use this when..." with specific conditions.

Do not add license or other fields.

When to Use Each Resource Type

• scripts/: Deterministic operations, repeatedly rewritten code
• references/: Long docs, schemas, APIs, patterns Claude references
• assets/: Templates, icons, boilerplate copied to output

Progressive Disclosure

Keep SKILL.md under 500 lines. Move details to references:

# Quick start
[essential workflow]

# Advanced
- Feature A: See [REFERENCES/A.md](REFERENCES/A.md)
- Feature B: See [REFERENCES/B.md](REFERENCES/B.md)

Skill Creation Workflow

Step 1 — Capture Requirements

See SKILLSPEC.md for the format.

Step 2 — Plan Resources

For each example, determine:

• Does it need a script? (deterministic, repeated)
• Does it need a reference? (long docs, schemas)
• Does it need assets? (templates, boilerplate)

Step 3 — Initialize

python "{baseDir}/scripts/init_skill.py" <skill-name> --path <output-dir>

Step 4 — Fill In

1. Replace generated SKILL.md with final version
2. Add scripts to scripts/
3. Add docs to references/
4. Add assets to assets/
5. Delete unused sample files

Step 5 — Gap Analysis

Verify all sections exist:

Use CHECKLIST.md for full validation.

Step 6 — Precision Analysis

Check trigger quality:

• Overlap: Do triggers match other common skills?
• Specificity: Are triggers specific enough?
• Differentiation: Document distinctions if overlap exists

Step 7 — Validate

python "{baseDir}/scripts/quick_validate.py" <skill-dir>

Updating Existing Skills

1. Run gap analysis against CHECKLIST.md
2. Run precision analysis on triggers
3. Apply fixes:
   • Improve description/triggers
   • Add missing failure handling
   • Add "When NOT to use"
   • Move long content to references/
   • Add scripts for repeated steps
4. Re-validate

Failure Modes

Examples

Creating a New Skill

User: "Build me a skill to rotate PDFs"

Assistant uses this workflow:

1. Captures requirements (rotate PDF, 3 triggers)
2. Plans resources (scripts/rotate_pdf.py)
3. Runs init_skill.py
4. Fills in SKILL.md with PDF-specific workflow
5. Adds rotate_pdf.py script
6. Validates

Updating an Existing Skill

User: "This skill is missing failure handling"

Assistant:

1. Runs gap analysis → finds missing "Failure handling"
2. Adds failure modes table
3. Re-validates

Acceptance Tests