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>

3. Add optional resources as needed

mkdir -p ~/.claude/skills//{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

. Use when . .

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:

```markdown
## 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