Skill Author
Create skills that Claude can discover and use reliably. Based on Anthropic's official Agent Skills best practices (April 2026).
Core Philosophy
- Claude is already smart — only add context it doesn't have
- Context window is a shared resource — every token competes with conversation, other skills, and system prompt
- Test with real usage, not assumptions — iterate based on observed agent behavior
Skill Creation Workflow
- Identify the pattern: Complete a task manually with Claude. Note what context you repeatedly provided (schemas, rules, conventions, sequences).
- Draft SKILL.md: Write frontmatter + body following the structure below.
- Apply conciseness pass: For every paragraph, ask "Does Claude need this?" Remove what it already knows.
- Set degrees of freedom: Match specificity to task fragility (see Freedom Levels below).
- Bundle resources: Move detailed references and scripts to separate files. Keep SKILL.md as the table of contents.
- Test with fresh context: Use the skill on a real task in a new session. Observe what Claude misses, over-reads, or ignores.
- Iterate: Refine based on observed behavior, not assumptions.
- Validate: Run
skill-check to catch structural issues.
SKILL.md Structure
---
name: lowercase-hyphenated # 3-64 chars, no reserved words
description: "Action verb + what it does + 'Use when...' trigger. Max 1024 chars."
requiredApps: [app-slug] # Optional: connected accounts needed
---
Body sections (not all required, pick what fits):
| Section |
Purpose |
When to include |
| Quick start |
Fastest path to using the skill |
Always |
| Steps / Workflow |
Sequential procedure with checklist |
Multi-step tasks |
| Rules / Constraints |
Hard requirements |
When consistency matters |
| Output |
Concrete output example |
When skill produces artifacts |
| References |
Links to bundled files |
When >500 lines needed |
| Errors / Limitations |
Known failure modes |
When edge cases exist |
Freedom Levels
Match specificity to how fragile the operation is:
| Level |
When |
Instruction style |
| High |
Multiple valid approaches, context-dependent |
Text guidance, heuristics |
| Medium |
Preferred pattern exists, some variation OK |
Pseudocode or parameterized scripts |
| Low |
Fragile operations, exact sequence required |
Specific scripts, minimal parameters |
Analogy: narrow bridge with cliffs (low freedom) vs open field (high freedom).
Progressive Disclosure
SKILL.md = table of contents. Detailed content lives in separate files.
my-skill/
├── SKILL.md # Overview + workflow (<500 lines)
├── references/
│ ├── api-reference.md # Loaded when Claude needs API details
│ └── schemas.md # Loaded when Claude needs data shapes
├── scripts/
│ └── validate.py # Executed (not read into context)
└── cache/
└── user-ids.json # Discovered data, reused across runs
Rules:
- Keep references ONE level deep from SKILL.md (no nested chains)
- Reference files >100 lines should have a table of contents
- Scripts are executed via bash, not loaded into context (only output consumes tokens)
- Make execution intent clear: "Run
validate.py" (execute) vs "See validate.py" (read)
Description Writing
The description is how Claude selects this skill from 100+ options. It must work as a standalone trigger.
- Third person: "Processes Excel files..." not "I can help you..."
- Action verb first: "Extract, Generate, Validate, Transform..."
- Include trigger: "Use when..." clause
- Include negative trigger: "Do NOT use for..." when confusion is likely
- Be specific: Include key terms Claude would match against
Feedback Loops
For quality-critical tasks, always include a validation cycle:
Produce output → Validate (script or checklist) → Fix errors → Repeat
For batch/destructive operations, use plan-validate-execute:
- Analyze input → create plan file (e.g.,
changes.json)
- Validate plan with script → catch errors before execution
- Execute only after validation passes
Common Anti-Patterns
| Anti-pattern |
Fix |
| Explaining what Claude already knows |
Delete it |
| Hardcoded dates or versions |
Use "old patterns" section or omit |
| Inconsistent terminology (mix "field"/"box"/"element") |
Pick one term, use consistently |
| Multiple approaches offered when one is best |
Pick the best, commit to it |
| Magic numbers without justification |
Document the reasoning |
| Deeply nested file references |
Flatten to one level from SKILL.md |
| Assuming packages are installed |
Check availability, document deps |
Quality Checklist
Before shipping a skill:
1---2name: skill-author3description: "Create and refine high-quality Agent Skills (SKILL.md + bundled resources). Use when the user wants to create a new skill, improve an existing one, or turn a workflow into a reusable skill package. Covers structure, progressive disclosure, conciseness, feedback loops, and the quality checklist. Do NOT use for skill validation (use skill-check) or for prompt engineering (use prompt-craft)."4requiredApps: []5metadata:6 source: https://skillmd.com/skills/aibot88/skill-author7---89# Skill Author1011Create skills that Claude can discover and use reliably. Based on Anthropic's official Agent Skills best practices (April 2026).1213## Core Philosophy14151. **Claude is already smart** — only add context it doesn't have162. **Context window is a shared resource** — every token competes with conversation, other skills, and system prompt173. **Test with real usage, not assumptions** — iterate based on observed agent behavior1819## Skill Creation Workflow20211. **Identify the pattern**: Complete a task manually with Claude. Note what context you repeatedly provided (schemas, rules, conventions, sequences).222. **Draft SKILL.md**: Write frontmatter + body following the structure below.233. **Apply conciseness pass**: For every paragraph, ask "Does Claude need this?" Remove what it already knows.244. **Set degrees of freedom**: Match specificity to task fragility (see Freedom Levels below).255. **Bundle resources**: Move detailed references and scripts to separate files. Keep SKILL.md as the table of contents.266. **Test with fresh context**: Use the skill on a real task in a new session. Observe what Claude misses, over-reads, or ignores.277. **Iterate**: Refine based on observed behavior, not assumptions.288. **Validate**: Run `skill-check` to catch structural issues.2930## SKILL.md Structure3132```yaml33---34name: lowercase-hyphenated # 3-64 chars, no reserved words35description: "Action verb + what it does + 'Use when...' trigger. Max 1024 chars."36requiredApps: [app-slug] # Optional: connected accounts needed37---38```3940**Body sections** (not all required, pick what fits):4142| Section | Purpose | When to include |43|---------|---------|-----------------|44| Quick start | Fastest path to using the skill | Always |45| Steps / Workflow | Sequential procedure with checklist | Multi-step tasks |46| Rules / Constraints | Hard requirements | When consistency matters |47| Output | Concrete output example | When skill produces artifacts |48| References | Links to bundled files | When >500 lines needed |49| Errors / Limitations | Known failure modes | When edge cases exist |5051## Freedom Levels5253Match specificity to how fragile the operation is:5455| Level | When | Instruction style |56|-------|------|-------------------|57| **High** | Multiple valid approaches, context-dependent | Text guidance, heuristics |58| **Medium** | Preferred pattern exists, some variation OK | Pseudocode or parameterized scripts |59| **Low** | Fragile operations, exact sequence required | Specific scripts, minimal parameters |6061Analogy: narrow bridge with cliffs (low freedom) vs open field (high freedom).6263## Progressive Disclosure6465SKILL.md = table of contents. Detailed content lives in separate files.6667```68my-skill/69├── SKILL.md # Overview + workflow (<500 lines)70├── references/71│ ├── api-reference.md # Loaded when Claude needs API details72│ └── schemas.md # Loaded when Claude needs data shapes73├── scripts/74│ └── validate.py # Executed (not read into context)75└── cache/76 └── user-ids.json # Discovered data, reused across runs77```7879**Rules**:80- Keep references ONE level deep from SKILL.md (no nested chains)81- Reference files >100 lines should have a table of contents82- Scripts are executed via bash, not loaded into context (only output consumes tokens)83- Make execution intent clear: "Run `validate.py`" (execute) vs "See `validate.py`" (read)8485## Description Writing8687The description is how Claude selects this skill from 100+ options. It must work as a standalone trigger.8889- **Third person**: "Processes Excel files..." not "I can help you..."90- **Action verb first**: "Extract, Generate, Validate, Transform..."91- **Include trigger**: "Use when..." clause92- **Include negative trigger**: "Do NOT use for..." when confusion is likely93- **Be specific**: Include key terms Claude would match against9495## Feedback Loops9697For quality-critical tasks, always include a validation cycle:9899```100Produce output → Validate (script or checklist) → Fix errors → Repeat101```102103For batch/destructive operations, use **plan-validate-execute**:1041. Analyze input → create plan file (e.g., `changes.json`)1052. Validate plan with script → catch errors before execution1063. Execute only after validation passes107108## Common Anti-Patterns109110| Anti-pattern | Fix |111|---|---|112| Explaining what Claude already knows | Delete it |113| Hardcoded dates or versions | Use "old patterns" section or omit |114| Inconsistent terminology (mix "field"/"box"/"element") | Pick one term, use consistently |115| Multiple approaches offered when one is best | Pick the best, commit to it |116| Magic numbers without justification | Document the reasoning |117| Deeply nested file references | Flatten to one level from SKILL.md |118| Assuming packages are installed | Check availability, document deps |119120## Quality Checklist121122Before shipping a skill:123124- [ ] Description: action verb + what + "Use when..." + "Do NOT use for..."125- [ ] SKILL.md body: under 500 lines126- [ ] Each paragraph earns its token cost127- [ ] Freedom level matches task fragility128- [ ] References are one level deep129- [ ] Scripts handle errors explicitly (no punting to Claude)130- [ ] No time-sensitive information131- [ ] Consistent terminology throughout132- [ ] Tested with real usage in fresh context133- [ ] Feedback loop included for quality-critical outputs134- [ ] `skill-check` validation passed