creating-skills

Creating skills

Guide for creating Claude Code skills following Anthropic's official best practices.

Quick start

# 1. Create skill directory
mkdir -p ~/.claude/skills/<skill-name>

# 2. Create SKILL.md with frontmatter
cat > ~/.claude/skills/<skill-name>/SKILL.md << 'EOF'
---
name: <skill-name>
description: <What it does>. Use when <trigger phrases>. <Key capabilities>.
---

# <Skill title>

<Instructions for the skill workflow>
EOF

# 3. Add optional resources as needed
mkdir -p ~/.claude/skills/<skill-name>/{scripts,references,assets}

SKILL.md structure

Frontmatter (YAML between --- markers)

Field	Required	Description
name	No	Display name. Defaults to directory name. Lowercase, hyphens, max 64 chars.
description	Recommended	What + when + capabilities. Max 1024 chars. Determines when Claude activates the skill.
allowed-tools	No	Tools Claude can use without asking permission when skill is active.
argument-hint	No	Autocomplete hint for arguments. Example: [issue-number]
disable-model-invocation	No	true to prevent auto-invocation (manual /name only).
user-invocable	No	false to hide from / menu (background knowledge only).
model	No	Model override when skill is active.
context	No	fork to run in isolated subagent context.
agent	No	Subagent type when context: fork. Built-in: Explore, Plan, general-purpose.
hooks	No	Lifecycle hooks scoped to this skill.

Invocation control matrix

Configuration	User can invoke	Claude can invoke
(defaults)	Yes	Yes
disable-model-invocation: true	Yes	No
user-invocable: false	No	Yes

Description formula

<What it does>. Use when <trigger phrases>. <Key capabilities>.

Include action verbs ("create", "handle"), user intent ("wants to", "needs to"), and domain keywords users would say.

Directory structure

skill-name/
├── SKILL.md              # Required: instructions (keep under 500 lines)
├── scripts/              # Optional: executable code (deterministic, token-efficient)
├── references/           # Optional: docs loaded into context on demand
└── assets/               # Optional: files used in output, NOT loaded into context
                          #   (templates, images, fonts, boilerplate)

Progressive disclosure (3-level loading)

1. Metadata (name + description) - always in context (~100 tokens per skill)
2. SKILL.md body - loaded when skill triggers (keep under 5k words)
3. Bundled resources - loaded as needed by Claude

Reference 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.

Scripts vs references vs assets

Type	Purpose	Loaded into context?
scripts/	Deterministic operations, complex processing	No (executed via bash)
references/	Documentation Claude reads while working	Yes, on demand
assets/	Templates, images, fonts for output	No (copied/used in output)

Only create scripts when they add value: complex multi-step processing, repeated code generation, deterministic reliability. Not for single-command wrappers.

Dynamic features

Context injection

Inject shell command output into skill content before loading:

## Recent commits
!`git log --oneline -5 2>/dev/null`

The output replaces the directive when the skill loads.

String substitutions

Pass arguments to skills invoked via /skill-name arg1 arg2:

Variable	Value
$ARGUMENTS	Full argument string
$ARGUMENTS[0], $ARGUMENTS[1]	Individual arguments
$1, $2	Shorthand for $ARGUMENTS[N]

Subagent execution

Run a skill in isolated context with context: fork:

---
name: deep-research
description: Research a topic thoroughly.
context: fork
agent: Explore
---

Degrees of freedom

Match specificity to the task's fragility:

Level	When to use	Example
High (text instructions)	Multiple valid approaches, context-dependent	"Analyze the code and suggest improvements"
Medium (pseudocode/scripts with params)	Preferred pattern exists, some variation OK	Script with configurable parameters
Low (specific scripts, few params)	Fragile operations, consistency critical	Exact sequence of API calls

Naming conventions

• Lowercase, hyphens between words, max 64 chars
• Styles: gerund (processing-pdfs), noun phrase (github-pr-creation), prefixed group (github-pr-*)

Important rules

• ALWAYS write descriptions that include WHAT + WHEN triggers + capabilities
• ALWAYS keep SKILL.md under 500 lines, split to references when approaching
• ALWAYS reference bundled files from SKILL.md so Claude discovers them
• NEVER duplicate info between SKILL.md and reference files
• NEVER create wrapper scripts for single commands
• NEVER include extraneous files (README.md, CHANGELOG.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md)
• NEVER explain things Claude already knows (standard libraries, common tools, basic patterns)

References

• references/official_best_practices.md - Principles, anti-patterns, quality checklist, testing
• references/skill_examples.md - Concrete skill examples with new features