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.

markdown

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

Field	Required	Description
`name`	No	Display name. Lowercase letters, numbers, hyphens (max 64 chars). Defaults to directory name.
`description`	Recommended	What it does AND when to use it. Claude uses this for auto-discovery. Max 1024 chars.
`argument-hint`	No	Hint shown during autocomplete. Example: `[issue-number]`
`disable-model-invocation`	No	Set `true` to prevent Claude auto-loading. Use for manual workflows like `/deploy` , `/commit` . Default: `false` .
`user-invocable`	No	Set `false` to hide from `/` menu. Use for background knowledge. Default: `true` .
`allowed-tools`	No	Tools Claude can use without permission prompts. Example: `Read, Bash(git *)`
`model`	No	Model to use. Options: `haiku` , `sonnet` , `opus` .
`context`	No	Set `fork` to run in isolated subagent context.
`agent`	No	Subagent type when `context: fork` . Options: `Explore` , `Plan` , `general-purpose` , or custom agent name.

Invocation Control

Frontmatter	User can invoke	Claude can invoke	When loaded
(default)	Yes	Yes	Description always in context, full content loads when invoked
`disable-model-invocation: true`	Yes	No	Description not in context, loads only when user invokes
`user-invocable: false`	No	Yes	Description always in context, loads when relevant

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.

yaml

---
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:

yaml

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

yaml

---
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:

yaml

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:

yaml

description: Helps with documents

What Would You Like To Do?

Create new skill - Build from scratch
Create new command - Build a slash command
Audit existing skill - Check against best practices
Add component - Add workflow/reference/example
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:

markdown

---
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:

markdown

---
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:

markdown

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

Step 4: Test With Real Usage

Test with actual tasks, not test scenarios
Invoke directly with
```
/skill-name
```
to verify
Check auto-triggering by asking something that matches the description
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

create-agent-skills

NPX Install

Tags

SKILL.md Content

Creating Skills & Commands

Commands and Skills Are Now The Same Thing

When To Create What

Standard Markdown Format

Frontmatter Reference

Invocation Control

Dynamic Features

Arguments

Dynamic Context Injection

Running in a Subagent

Progressive Disclosure

Effective Descriptions

What Would You Like To Do?

Creating a New Skill or Command

Step 1: Choose Type

Step 2: Create the File

Step 3: Add Reference Files (If Needed)

Step 4: Test With Real Usage

Audit Checklist

Anti-Patterns to Avoid

Reference Files

Sources