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)

Invocation control matrix

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

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:

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:

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

Official best practices for skills

Source: Claude Code skills docs, Agent Skills overview, Anthropic skills repo

---

Core principle: Claude is already smart

"Default assumption: Claude is already very smart. Only add context Claude doesn't already have."

Challenge each piece of information:

• Does Claude really need this explanation?
• Can I assume Claude knows this?
• Does this paragraph justify its token cost?

What NOT to include: basic programming concepts, common tool usage (git, npm), standard library docs, well-known patterns.

What TO include: project-specific conventions, custom workflows, non-obvious requirements, domain knowledge Claude wouldn't have.

Progressive disclosure

Skills use a three-level loading system:

1. Metadata (name + description) - always in context (~100 words per skill) 2. SKILL.md body - when skill triggers (<5k words recommended) 3. Bundled resources - as needed (scripts execute without loading; references load on demand)

Context budget

Skill descriptions share a budget that scales at 2% of the context window, with a fallback of 16,000 characters. Override with SLASH_COMMAND_TOOL_CHAR_BUDGET env var.

Splitting patterns

When SKILL.md approaches 500 lines, split content into separate files:

• Pattern 1: High-level guide with references - Keep workflow in SKILL.md, move detailed docs to references/
• Pattern 2: Domain-specific organization - One reference per domain area (e.g., references/api_docs.md, references/schemas.md)
• Pattern 3: Conditional details - Keep decision logic in SKILL.md, move variant-specific details to references/

Guidelines:

• Avoid deeply nested references - keep one level deep from SKILL.md
• For files over 100 lines, include a table of contents at the top
• For very large references (>10k words), include grep search patterns in SKILL.md
• Information should live in either SKILL.md OR references, not both

Frontmatter validation rules

Skills and commands unification

Custom slash commands (.claude/commands/*.md) and skills (.claude/skills/*/SKILL.md) are now unified. Both create /name invocations and support the same frontmatter. Existing commands files continue to work. If a skill and a command share the same name, the skill takes precedence.

Discovery hierarchy

Skills are discovered from multiple locations (higher priority wins):

1. Enterprise (managed settings) 2. Personal (~/.claude/skills/) 3. Project (.claude/skills/) 4. Plugin (namespaced as plugin-name:skill-name)

Additional directories via --add-dir are also supported with live change detection.

User confirmation patterns

ALWAYS confirm before:

• Modifying user files
• Running destructive commands
• Creating external resources (PRs, issues, deployments)
• Irreversible operations

Don't over-confirm:

• Read-only operations
• Reversible actions
• Intermediate steps in an approved workflow

Anti-patterns

Quality checklist

Before finalizing a skill:

• [ ] Frontmatter: description present, clear, under 1024 chars
• [ ] Description: includes WHAT + WHEN triggers + capabilities
• [ ] Naming: lowercase, hyphens, max 64 chars
• [ ] Body: under 500 lines, no duplication with references
• [ ] Resources: referenced from SKILL.md, one level deep
• [ ] Scripts: only value-add, not wrappers
• [ ] Rules: critical constraints marked with ALWAYS/NEVER
• [ ] Test: skill triggers on expected phrases

Testing

Trigger testing

Verify skill activates on expected user phrases. Test with multiple phrasings.

Model testing

Test with all models you plan to support (Haiku, Sonnet, Opus have different capabilities). Build evaluations before writing extensive documentation.

Edge cases

• Missing prerequisites
• Invalid input
• Partial completion

What NOT to include in a skill

A skill should only contain files that directly support its functionality:

• No README.md, INSTALLATION_GUIDE.md, QUICK_REFERENCE.md, CHANGELOG.md
• No user-facing documentation (the skill IS the documentation for Claude)
• No setup/testing procedures
• No auxiliary context about the creation process

Skill examples

Concrete examples demonstrating skill patterns and new features.

---

Example 1: minimal skill

The simplest possible skill:

---
description: Formats code following project conventions. Use when user wants to format, lint, or clean up code.
---

# Code formatter

Run the project formatter on changed files.

## Workflow

1. Detect project type and formatter
2. Run formatter on staged/changed files
3. Report results

## Important rules

- **ALWAYS** check for project-specific formatter config before using defaults
- **NEVER** format files outside the current change set

Note: name is omitted (defaults to directory name). Only description is provided.

---

Example 2: dynamic context injection

A skill that adapts to the current project:

---
name: git-commit
description: Creates commits following project conventions. Use when user wants to commit changes.
---

# Git commit

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

## Current branch
!`git rev-parse --abbrev-ref HEAD 2>/dev/null`

Match the style of recent commits above when creating new ones.

The !command`` directives run at load time and inject their output, so Claude sees actual commit history instead of placeholder text.

---

Example 3: invocation control

Manual-only skill (no auto-invocation)

---
name: deploy
description: Deploy the application to production.
disable-model-invocation: true
argument-hint: [environment]
---

Claude will never auto-invoke this skill. Users must type /deploy staging explicitly.

Background knowledge (no user invocation)

---
name: project-conventions
description: Project coding conventions and architectural decisions.
user-invocable: false
---

Claude auto-loads this as context when relevant, but it doesn't appear in the / menu.

---

Example 4: subagent execution

A skill that runs in isolated context:

---
name: codebase-analysis
description: Analyze codebase architecture and patterns. Use when user wants to understand code structure.
context: fork
agent: Explore
---

# Codebase analysis

Explore the codebase and report:
1. Project structure and framework
2. Key architectural patterns
3. Entry points and data flow
4. Test coverage approach

Return a structured summary.

With context: fork, this runs in a separate subagent without consuming the main conversation's context.

---

Example 5: skill with arguments

---
name: fix-issue
description: Fix a GitHub issue. Use when user wants to fix, resolve, or address an issue.
argument-hint: [issue-number]
---

# Fix issue

## Issue details
!`gh issue view $1 --json title,body,labels 2>/dev/null`

Fix the issue described above. Follow project conventions.

$1 is replaced with the first argument when the user types /fix-issue 42.

---

Example 6: skill with allowed tools

---
name: database-migration
description: Create and run database migrations. Use when user wants to migrate, create migration, or update schema.
allowed-tools: ["Bash", "Read", "Write", "Edit"]
---

Tools listed in allowed-tools won't prompt for permission when this skill is active.

---

Description: good vs bad

Good - concise, specific triggers, clear capabilities:

Handles PR review comments with severity classification. Use when user
wants to resolve PR comments, handle review feedback, or fix review
comments. Fetches via GitHub CLI, classifies by severity, proposes fixes.

Bad - verbose, filler words, redundant:

Comprehensive GitHub Pull Request management system for feature
development workflow. Use this skill when the user wants to create, verify,
or manage Pull Requests on GitHub repositories. This skill handles the
complete workflow - validates task completion against project documentation,
runs tests, generates PR title and description following Conventional Commits,
suggests appropriate labels, and creates the PR using GitHub CLI.

Problems: "Comprehensive", "complete workflow" are filler. Redundant explanations. Too verbose for a description field.

---

Resource organization examples

Scripts that add value

Scripts to avoid