Skill Making

This skill helps you create high-quality Claude agent skills that follow established best practices and conventions.

CRITICAL: All skill files MUST use Unix line endings (LF, \n) only. Never use Windows line endings (CRLF, \r\n).

When to Create a Skill

Create a skill when:

You've refined an approach through repeated use and want consistent application
Quality requires specific materials (templates, examples, domain knowledge)
Task involves complex multi-piece setups requiring coordinated requirements
You want to package expertise for automatic activation

Don't create a skill for:

One-off exploratory tasks
Simple tasks better handled by regular prompting
General preferences (use Custom Instructions instead)
Accumulated context over time (use Projects instead)

Skill Discovery Context

Important: Skills stored in ~/.claude/skills/ may be symlinked from other locations (e.g., files/claude-skills in version-controlled repos). When using tools like find to discover skills:

Use find -L to follow symbolic links
Or search in the actual source directory
Standard find won't follow symlinks by default

File Structure

skill-name/
├── SKILL.md           (required: main instructions)
├── REFERENCE.md       (optional: domain knowledge)
├── EXAMPLES.md        (optional: input/output examples)
└── scripts/           (optional: utility scripts)
    └── validator.py

SKILL.md Format

Every SKILL.md requires YAML frontmatter plus markdown body:

---
name: skill-name
description: What this skill does and when to use it (max 1024 chars)
---

# Skill Name

[Instructions for Claude in markdown]

YAML Frontmatter Requirements

name (required):

Maximum 64 characters
Lowercase letters, numbers, hyphens only
Use gerund form (verb + "-ing"): processing-pdfs, analyzing-spreadsheets
Avoid: helper, utils, reserved words containing "anthropic" or "claude"
No XML tags

description (required):

Maximum 1024 characters
Write in third person
Be specific about functionality AND usage triggers
Include key terms that match user intent
Good: "Extracts text and tables from PDFs, fills forms, merges documents. Use when working with PDF files."
Bad: "Helps with documents" (too vague)
No XML tags

Content Best Practices

Conciseness

"The context window is a public good." Only include information Claude doesn't already know. Challenge every element: does it justify its token cost?

Progressive Disclosure

Keep SKILL.md under 500 lines
Move advanced content to separate files (REFERENCE.md, EXAMPLES.md)
Reference files load only when Claude needs them
Keep references one level deep from SKILL.md

File Organization Patterns

High-level guide with references:

For detailed procedures, see FORMS.md.
For API specifications, see REFERENCE.md.
For examples, see EXAMPLES.md.

Domain-specific organization:

reference/finance.md
reference/sales.md
reference/legal.md

Conditional details:

For advanced error handling, see [advanced-errors.md](advanced-errors.md).

Reference File Guidelines

Use forward slashes in paths (not backslashes)
Include table of contents for files over 100 lines
Keep one level deep from SKILL.md

Terminology Consistency

Choose one term and use it consistently:

Don't mix: "field/box/element" or "extract/pull/get"
Consistent terminology helps Claude understand

Freedom Levels

Match specificity to task requirements:

High freedom (flexible approaches):

Text-based instructions
Multiple valid approaches
Creative or analytical work

Medium freedom (preferred patterns):

Pseudocode
Structured workflows
Some flexibility needed

Low freedom (precise execution):

Specific scripts
Fragile operations
Consistency critical

Workflows for Complex Tasks

Structure multi-step operations with explicit checklists:

## Review Process

Copy this checklist and mark items as you complete them:

- [ ] Run validator on input
- [ ] Fix any validation errors
- [ ] Generate output
- [ ] Validate output format
- [ ] Confirm all requirements met

Feedback Loop Pattern

1. Run validator script
2. Review errors
3. Fix issues
4. Repeat until validation passes

Scripts and Code

Utility Scripts

Provide pre-made scripts for:

Reliability (complex operations)
Efficiency (repeated tasks)
Consistency (fragile operations)

Clearly distinguish:

Execution: "Run analyze_form.py with input file"
Reference: "See analyze_form.py for the algorithm"

Error Handling

"Handle error conditions rather than punting to Claude."

try:
    result = process_data(input)
except ValidationError as e:
    # Provide meaningful alternative
    result = handle_validation_error(e)
except Exception as e:
    # Log and provide fallback
    log_error(e)
    result = safe_fallback()

Self-Documenting Code

Justify all configuration values:

# Good: explains the why
MAX_RETRIES = 3  # Balance between reliability and performance

# Bad: unexplained "voodoo constant"
MAX_RETRIES = 3

Verifiable Outputs

For complex operations, create intermediate verifiable files:

# Generate changes first
changes = analyze_input(data)
save_json(changes, "changes.json")

# User can review changes.json before applying
if validate_changes("changes.json"):
    apply_changes(changes)

Templates and Examples

Output Format Templates

Adjust strictness based on requirements:

Mandatory (for APIs):

## Output Format (Required)

```json
{
  "field": "value",
  "items": []
}


**Flexible** (for analysis):
```markdown
## Output Format (Suggested)

Present findings in these sections:
- Summary
- Key insights
- Recommendations

Example Patterns

Include input/output pairs demonstrating:

Desired style
Appropriate detail level
Expected structure

## Example

Input:

[concrete example input]


Output:

[expected output showing style and detail]

Avoiding Time-Sensitive Information

Don't use date-based conditions:

<!-- Bad -->
As of 2024, use method A. Before 2024, use method B.

<!-- Good -->
Use method A (current approach).

<details>
<summary>Legacy patterns</summary>
Method B was used in older versions...
</details>

Anti-Patterns to Avoid

❌ Offering excessive options: "Use pypdf, pdfplumber, PyMuPDF, or..." ✅ Provide default with escape hatch: "Use pypdf. For special cases requiring X, consider Y."

❌ Windows-style paths: scripts\validator.py ✅ Unix-style paths: scripts/validator.py (works everywhere)

❌ Abstract examples: "For a document like X, do Y" ✅ Concrete examples: Actual input/output pairs

❌ Vague descriptions: "Helps with documents" ✅ Specific descriptions: "Extracts text and tables from PDFs, fills forms"

❌ Inconsistent terminology: field/box/element mixed ✅ Consistent terminology: Use "field" throughout

Development Workflow

1. Design Phase

Use one Claude instance to design and refine the skill:

Discuss requirements
Draft SKILL.md structure
Create examples and scripts
Iterate on content

2. Testing Phase

Test with a separate Claude instance:

Start fresh chat (no design context)
Use real tasks that should trigger the skill
Observe: Does it activate? Does it work correctly?

3. Observation Points

Monitor for:

Unexpected navigation paths
Missed connections between sections
Overreliance on specific sections
Ignored content

4. Refinement

Return to design instance:

Report observations
Adjust content based on behavior
Clarify unclear sections
Add missing connections

5. Evaluation

Build test scenarios:

Establish baseline (no skill)
Measure with skill
Document improvements
Create at least 3 evaluations

Cross-Model Testing

Test skills across all Claude models:

Haiku: Fast, efficient, good for straightforward tasks
Sonnet: Balanced capability and speed
Opus: Maximum capability for complex tasks

Effectiveness varies by model capability. Ensure skills work acceptably across all three.

Final Verification Checklist

Before considering a skill complete:

[ ] Description is specific with key terms and usage triggers
[ ] No time-sensitive information (no dates, no "current" references)
[ ] Consistent terminology throughout
[ ] Concrete examples with input/output pairs
[ ] File references are one level deep
[ ] Forward slashes in all paths
[ ] Scripts handle errors explicitly
[ ] All required packages listed and available
[ ] At least 3 test scenarios created
[ ] Tested across Haiku, Sonnet, and Opus
[ ] SKILL.md under 500 lines
[ ] All files use Unix line endings (LF only)

Skill Locations by Platform

Claude.ai: Upload via Settings > Features as zip files

Claude API: Upload through Skills API (/v1/skills)

Requires beta headers: code-execution-2025-08-25, skills-2025-10-02, files-api-2025-04-14
No network access
No runtime package installation

Claude Code: Filesystem-based

Project or personal directories
Full network access
Avoid global package installation

Agent SDK: .claude/skills/ configuration directories

Activation Mechanism

Skills use progressive disclosure with three tiers:

Metadata always loads: YAML frontmatter (~100 tokens per skill)
Instructions load when triggered: Full SKILL.md when description matches user intent
Resources load as needed: Referenced files only when Claude accesses them

Only relevant content occupies context window at any time.