Create Agent Skills

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

Use disable-model-invocation: true for workflows with side effects: /deploy, /commit, /triage-prs, /send-slack-message. You don't want Claude deciding to deploy because your code looks ready.

Use user-invocable: false for background knowledge that isn't a meaningful user action: coding conventions, domain context, legacy system docs.

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 !`command` syntax runs shell commands before content is sent to Claude:

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

## Context
- PR diff: !`gh pr diff`
- Changed files: !`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.

Effective Descriptions

The description enables skill discovery. Include both what it does and when to use it.

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

What Would You Like To Do?

1. Create new skill - Build from scratch
2. Create new command - Build a slash command
3. Audit existing skill - Check against best practices
4. Add component - Add workflow/reference/example
5. Get guidance - Understand skill design

Creating a New Skill or Command

Step 1: Choose Type

Ask: Is this a manual workflow (deploy, commit, triage) or background knowledge (conventions, patterns)?

• Manual workflow → command with disable-model-invocation: true
• Background knowledge → skill without disable-model-invocation
• Complex with supporting files → skill directory

Step 2: Create the File

Command:

---
name: my-command
description: What this command does
argument-hint: [expected arguments]
disable-model-invocation: true
allowed-tools: Bash(gh *), Read
---

# Command Title

## Workflow

### Step 1: Gather Context
...

### Step 2: Execute
...

## Success Criteria
- [ ] Expected outcome 1
- [ ] Expected outcome 2

Skill:

---
name: my-skill
description: What it does. Use when [trigger conditions].
---

# Skill Title

## Quick Start
[Immediate actionable example]

## Instructions
[Core guidance]

## Examples
[Concrete input/output pairs]

Step 3: Add Reference Files (If Needed)

Link from SKILL.md to detailed content:

For API reference, see [reference.md](reference.md).
For form filling guide, see [forms.md](forms.md).

Step 4: Test With Real Usage

1. Test with actual tasks, not test scenarios
2. Invoke directly with /skill-name to verify
3. Check auto-triggering by asking something that matches the description
4. Refine based on real behavior

Audit Checklist

• Valid YAML frontmatter (name + description)
• Description includes trigger keywords and is specific
• Uses standard markdown headings (not XML tags)
• SKILL.md under 500 lines
• disable-model-invocation: true if it has side effects
• allowed-tools set if specific tools needed
• References one level deep, properly linked
• Examples are concrete, not abstract
• Tested with real usage

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
• Missing invocation control - Side-effect workflows need disable-model-invocation: true
• 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

Sources

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