Creating Skills & Commands

This skill teaches how to create effective Claude Code skills following the official specification from code.claude.com/docs/en/skills.

Commands and Skills Are Now The Same Thing

Custom slash commands have been merged into skills. A file at .claude/commands/review.md and a skill at .claude/skills/review/SKILL.md both create /review and work the same way. Existing .claude/commands/ files keep working. Skills add optional features: a directory for supporting files, frontmatter to control invocation, and automatic context loading.

If a skill and a command share the same name, the skill takes precedence.

When To Create What

Use a command file (commands/name.md) when:

• Simple, single-file workflow
• No supporting files needed
• Task-oriented action (deploy, commit, triage)

Use a skill directory (skills/name/SKILL.md) when:

• Need supporting reference files, scripts, or templates
• Background knowledge Claude should auto-load
• Complex enough to benefit from progressive disclosure

Both use identical YAML frontmatter and markdown content format.

Standard Markdown Format

Use YAML frontmatter + markdown body with standard markdown headings. Keep it clean and direct.

---
name: my-skill-name
description: What it does and when to use it
---

# My Skill Name

## Quick Start
Immediate actionable guidance...

## Instructions
Step-by-step procedures...

## Examples
Concrete usage examples...

Frontmatter Reference

All fields are optional. Only description is recommended.

Invocation Control

The key insight: disable-model-invocation: true is the only way to keep a skill out of the 2% context budget. It removes the description from context entirely, making the skill a pure slash command -- zero context cost, invisible to Claude, only fires when you type /name.

Decision framework -- what belongs in the 2% budget?

Only skills you want Claude to auto-discover should consume context budget. Everything else should be a slash command (disable-model-invocation: true) with zero context cost.

• Default (both flags false): Use for skills Claude should discover AND users might invoke. Description counts toward 2% budget.
• user-invocable: false: Use for knowledge bank skills -- background reference Claude should auto-detect but users never type. Description counts toward 2% budget.
• disable-model-invocation: true: Use for everything else -- workflows, commands, actions you'll invoke by typing /name. Zero context cost. This is the old-school slash command pattern.

Dynamic Features

Arguments

Use $ARGUMENTS placeholder for user input. If not present in content, arguments are appended automatically.

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Fix GitHub issue $ARGUMENTS following our coding standards.

Access individual args: $ARGUMENTS[0] or shorthand $0, $1, $2.

Dynamic Context Injection

The ! + backtick-wrapped command syntax runs shell commands before content is sent to Claude. For example, writing ! followed by a command in backticks (like gh pr diff) will execute that command and inject the output.

Example skill using dynamic context:

The PR diff and changed files lines below would use the bang-backtick syntax to call gh pr diff and gh pr diff --name-only respectively, injecting the output before Claude sees the content.

---
name: pr-summary
description: Summarize changes in a pull request
context: fork
agent: Explore
---

## Context
- PR diff: (use bang-backtick with: gh pr diff)
- Changed files: (use bang-backtick with: gh pr diff --name-only)

Summarize this pull request...

Running in a Subagent

Add context: fork to run in isolation. The skill content becomes the subagent's prompt. It won't have conversation history.

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

Research $ARGUMENTS thoroughly:
1. Find relevant files
2. Analyze the code
3. Summarize findings

Progressive Disclosure

Keep SKILL.md under 500 lines. Split detailed content into reference files:

my-skill/
├── SKILL.md           # Entry point (required, overview + navigation)
├── reference.md       # Detailed docs (loaded when needed)
├── examples.md        # Usage examples (loaded when needed)
└── scripts/
    └── helper.py      # Utility script (executed, not loaded)

Link from SKILL.md: For API details, see [reference.md](reference.md).

Keep references one level deep from SKILL.md. Avoid nested chains.

Naming & Descriptions

Choosing a Name

Each component type has a natural part of speech. Consistency within a type creates a predictable mental model.

The Five Rules of Naming

1. Never repeat the plugin name in component names -- the namespace handles scope
2. Match skill names to command counterparts -- if /research delegates to a skill, name the skill research
3. Use the description for AI routing, not the name -- name is for humans, description is for Claude
4. Maintain part-of-speech consistency within a type -- commands are verbs, agents are role-nouns, knowledge skills are nouns
5. Treat published names as API contracts -- renaming is a semver-major change

Invocation control changes strategy:

• User-invoked skills/commands: optimize for human recall (verb-noun, memorable, typable)
• Auto-triggered skills: description matters more than name
• Keep name matching directory name for predictability

Name Anti-Patterns

For advanced naming topics (agent naming, namespace strategy, budget constraints), invoke the naming-conventions skill.

Writing Effective Descriptions

The description enables skill discovery. Follow the WHAT + WHEN + WHEN NOT pattern. Always write in third person -- descriptions are injected into the system prompt.

Good:

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Bad:

description: Helps with documents

Tips:

• Front-load capabilities, include file extensions (.pdf, .xlsx), user synonyms ("deck" for presentations), and action verbs
• Max 1024 characters, but match length to competition -- unique skills need less, contested domains need more
• Use "pushy" language: "Make sure to use this skill whenever..." outperforms passive phrasing

For the full description-writing guide (activation rates, length strategy, pushy pattern, WHEN NOT clauses), see description-writing.md.

Argument Hints

Use POSIX bracket conventions: <required>, [optional], {a|b} for choices. Keep under 30 characters.

argument-hint: <topic>
argument-hint: <issue-number>
argument-hint: <file> [format]

For detailed conventions, see argument-hints.md.

What Would You Like To Do?

1. Create new skill - Build a skill or command from scratch
2. Audit existing skill - Check against best practices with scored report
3. Add component - Add to an existing skill:
   • a. Reference - Conditional context file
   • b. Workflow - Step-by-step procedure
   • c. Template - Reusable boilerplate
   • d. Script - Executable hook or helper
4. Get guidance - Understand whether/how to build something

Routing keywords: create -> 1, audit -> 2, add reference -> 3a, add workflow -> 3b, add template -> 3c, add script -> 3d, guidance -> 4

If arguments match a keyword or menu item, read the corresponding workflow and begin. Otherwise, reply with a number or describe what you need.

$ARGUMENTS

Anti-Patterns to Avoid

• XML tags in body - Use standard markdown headings
• Vague descriptions - Be specific with trigger keywords
• Deep nesting - Keep references one level from SKILL.md
• Wasting context budget - Only skills Claude should auto-discover belong in the 2% budget; use disable-model-invocation: true for everything else
• Too many options - Provide a default with escape hatch
• Punting to Claude - Scripts should handle errors explicitly

Reference Files

For detailed guidance, see:

• official-spec.md - Official skill specification
• best-practices.md - Skill authoring best practices
• description-writing.md - WHAT+WHEN+WHEN NOT pattern, activation rates, length strategy
• argument-hints.md - POSIX conventions and examples
• For advanced topics (budget strategy, activation rate data, agent naming), invoke the naming-conventions skill

Sources

• Extend Claude with skills - Official Docs
• GitHub - anthropics/skills