Skill Authoring — Official Best Practices

File Structure

skill-name/
├── SKILL.md              # Main instructions (< 500 lines)
├── reference.md          # Detailed docs (loaded on demand)
├── examples.md           # Usage examples (loaded on demand)
└── scripts/
    └── helper.py         # Utility scripts (executed, not loaded)

YAML Frontmatter

---
name: my-skill                      # max 64 chars, lowercase + hyphens only
description: |                      # max 1024 chars, THIRD PERSON, no XML tags
  Processes PDF files and extracts text. Use when working with
  PDF files or when the user mentions document extraction.
disable-model-invocation: false     # true = only user can invoke via /name
user-invocable: true                # false = hidden from / menu, Claude-only
allowed-tools: Read, Grep, Glob     # restrict tools when skill is active
model: sonnet                       # model override (sonnet, opus, haiku)
context: fork                       # run in isolated subagent context
agent: Explore                      # agent type when context: fork
---

Required: only description is recommended. name defaults to directory name.

Description — The Most Critical Field

Claude uses the description to decide which skill to load from 100+ available.

Rules:

• Write in third person ("Processes files", NOT "I can help" or "You can use")
• Include what it does AND when to use it
• Be "pushy" — mention specific trigger contexts
• Include key terms users would naturally say

Good:

description: Generates commit messages by analyzing git diffs. Use when
  the user asks for help writing commit messages or reviewing staged changes.

Bad:

description: Helps with git stuff

Core Content Principles

Claude is already smart — only add what it doesn't know

Challenge every line: "Does Claude need this explanation?" Remove basics.

Good (~50 tokens):

## Extract PDF text
Use pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Bad (~150 tokens): explaining what PDFs are, what libraries are, how pip works.

One recommended approach, not many alternatives

Provide a default tool/library. Only mention alternatives when the choice is context-dependent.

Consistent terminology

Pick one term and use it throughout. Don't mix "endpoint", "URL", "route", "path".

No time-sensitive information

Don't write "as of 2025" or "before August, use the old API".

Progressive Disclosure

SKILL.md is a table of contents. Detailed content goes in separate files.

Pattern 1: References

## Quick start
[essential code here]

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

Pattern 2: Domain-specific

bigquery-skill/
├── SKILL.md (overview + navigation)
└── reference/
    ├── finance.md
    ├── sales.md
    └── product.md

Rules:

• Keep references one level deep from SKILL.md (no nested chains)
• Reference files > 100 lines need a table of contents at top
• Claude loads referenced files only when needed — no context penalty

String Substitutions

Variable	Description
$ARGUMENTS	All arguments passed to skill
$ARGUMENTS[N] or $N	Specific argument by index
${CLAUDE_SESSION_ID}	Current session ID
${CLAUDE_SKILL_DIR}	Directory containing SKILL.md

Dynamic injection: !`shell command` runs before Claude sees the content.

Invocation Control

Config	User invokes	Claude invokes
Default	Yes	Yes
disable-model-invocation: true	Yes	No
user-invocable: false	No	Yes

Workflows & Feedback Loops

For complex tasks, provide a checklist Claude can track:

## Deploy workflow
- [ ] Step 1: Run tests
- [ ] Step 2: Build artifacts
- [ ] Step 3: Deploy to staging
- [ ] Step 4: Verify deployment
- [ ] Step 5: Deploy to production

Implement validation loops: Run validator → fix → re-validate → proceed only when passing.

Anti-Patterns to Avoid

Anti-Pattern	Fix
Body > 500 lines	Split into SKILL.md + reference files
Deeply nested references (A→B→C)	Keep all refs one level from SKILL.md
Too many options	Provide one default, mention alternative only when needed
First/second person description	Always third person
Vague description	Include what + when + trigger keywords
Windows-style paths (\)	Always use forward slashes
Explaining basics Claude knows	Remove — Claude is already smart

Checklist Before Shipping

• Description is specific, third person, includes trigger terms
• SKILL.md body < 500 lines
• Additional details in separate reference files
• No time-sensitive info
• Consistent terminology throughout
• Concrete examples, not abstract
• References one level deep
• Tested with at least 3 real scenarios

Reference

• Progressive disclosure patterns
• Writing effective descriptions