Creating Skills

1---
2name: creating-skills
3description: Guide for creating Claude Code skills following Anthropic's official best practices. Use when user wants to create a new skill, build a skill, write SKILL.md, update an existing skill, or needs skill creation guidelines. Provides structure, frontmatter fields, naming conventions, and new features like dynamic context injection and subagent execution.
4---
5 
6# Creating skills
7 
8Guide for creating Claude Code skills following Anthropic's official best practices.
9 
10## Quick start
11 
12```bash
13# 1. Create skill directory
14mkdir -p ~/.claude/skills/<skill-name>
15 
16# 2. Create SKILL.md with frontmatter
17cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'
18---
19name: <skill-name>
20description: <What it does>. Use when <trigger phrases>. <Key capabilities>.
21---
22 
23# <Skill title>
24 
25<Instructions for the skill workflow>
26EOF
27 
28# 3. Add optional resources as needed
29mkdir -p ~/.claude/skills/<skill-name>/{scripts,references,assets}
30```
31 
32## SKILL.md structure
33 
34### Frontmatter (YAML between `---` markers)
35 
36| Field | Required | Description |
37|-------|----------|-------------|
38| `name` | No | Display name. Defaults to directory name. Lowercase, hyphens, max 64 chars. |
39| `description` | Recommended | What + when + capabilities. Max 1024 chars. Determines when Claude activates the skill. |
40| `allowed-tools` | No | Tools Claude can use without asking permission when skill is active. |
41| `argument-hint` | No | Autocomplete hint for arguments. Example: `[issue-number]` |
42| `disable-model-invocation` | No | `true` to prevent auto-invocation (manual `/name` only). |
43| `user-invocable` | No | `false` to hide from `/` menu (background knowledge only). |
44| `model` | No | Model override when skill is active. |
45| `context` | No | `fork` to run in isolated subagent context. |
46| `agent` | No | Subagent type when `context: fork`. Built-in: `Explore`, `Plan`, `general-purpose`. |
47| `hooks` | No | Lifecycle hooks scoped to this skill. |
48 
49### Invocation control matrix
50 
51| Configuration | User can invoke | Claude can invoke |
52|---------------|-----------------|-------------------|
53| (defaults) | Yes | Yes |
54| `disable-model-invocation: true` | Yes | No |
55| `user-invocable: false` | No | Yes |
56 
57### Description formula
58 
59```
60<What it does>. Use when <trigger phrases>. <Key capabilities>.
61```
62 
63Include action verbs ("create", "handle"), user intent ("wants to", "needs to"), and domain keywords users would say.
64 
65## Directory structure
66 
67```
68skill-name/
69├── SKILL.md              # Required: instructions (keep under 500 lines)
70├── scripts/              # Optional: executable code (deterministic, token-efficient)
71├── references/           # Optional: docs loaded into context on demand
72└── assets/               # Optional: files used in output, NOT loaded into context
73                          #   (templates, images, fonts, boilerplate)
74```
75 
76### Progressive disclosure (3-level loading)
77 
781. **Metadata** (name + description) - always in context (~100 tokens per skill)
792. **SKILL.md body** - loaded when skill triggers (keep under 5k words)
803. **Bundled resources** - loaded as needed by Claude
81 
82Reference supporting files from SKILL.md so Claude knows they exist. Keep references one level deep. For files over 100 lines, include a table of contents.
83 
84### Scripts vs references vs assets
85 
86| Type | Purpose | Loaded into context? |
87|------|---------|---------------------|
88| `scripts/` | Deterministic operations, complex processing | No (executed via bash) |
89| `references/` | Documentation Claude reads while working | Yes, on demand |
90| `assets/` | Templates, images, fonts for output | No (copied/used in output) |
91 
92Only create scripts when they add value: complex multi-step processing, repeated code generation, deterministic reliability. Not for single-command wrappers.
93 
94## Dynamic features
95 
96### Context injection
97 
98Inject shell command output into skill content before loading:
99 
100```markdown
101## Recent commits
102!`git log --oneline -5 2>/dev/null`
103```
104 
105The output replaces the directive when the skill loads.
106 
107### String substitutions
108 
109Pass arguments to skills invoked via `/skill-name arg1 arg2`:
110 
111| Variable | Value |
112|----------|-------|
113| `$ARGUMENTS` | Full argument string |
114| `$ARGUMENTS[0]`, `$ARGUMENTS[1]` | Individual arguments |
115| `$1`, `$2` | Shorthand for `$ARGUMENTS[N]` |
116 
117### Subagent execution
118 
119Run a skill in isolated context with `context: fork`:
120 
121```yaml
122---
123name: deep-research
124description: Research a topic thoroughly.
125context: fork
126agent: Explore
127---
128```
129 
130## Degrees of freedom
131 
132Match specificity to the task's fragility:
133 
134| Level | When to use | Example |
135|-------|-------------|---------|
136| **High** (text instructions) | Multiple valid approaches, context-dependent | "Analyze the code and suggest improvements" |
137| **Medium** (pseudocode/scripts with params) | Preferred pattern exists, some variation OK | Script with configurable parameters |
138| **Low** (specific scripts, few params) | Fragile operations, consistency critical | Exact sequence of API calls |
139 
140## Naming conventions
141 
142- Lowercase, hyphens between words, max 64 chars
143- Styles: gerund (`processing-pdfs`), noun phrase (`github-pr-creation`), prefixed group (`github-pr-*`)
144 
145## Important rules
146 
147- **ALWAYS** write descriptions that include WHAT + WHEN triggers + capabilities
148- **ALWAYS** keep SKILL.md under 500 lines, split to references when approaching
149- **ALWAYS** reference bundled files from SKILL.md so Claude discovers them
150- **NEVER** duplicate info between SKILL.md and reference files
151- **NEVER** create wrapper scripts for single commands
152- **NEVER** include extraneous files (README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md)
153- **NEVER** explain things Claude already knows (standard libraries, common tools, basic patterns)
154 
155## References
156 
157- `references/official_best_practices.md` - Principles, anti-patterns, quality checklist, testing
158- `references/skill_examples.md` - Concrete skill examples with new features
159