Create Skill

Interactive guide for creating new Claude skills following Anthropic's official skill specification. Walks you through use case definition, frontmatter generation, instruction writing, and validation.

Workflow

Step 1: Gather Context

Ask the user for:

1. Skill name — kebab-case, describes the domain/concept (not the action). The description already explains what the skill does, so avoid verb prefixes like add-, new-, get-, run-
2. What it does — one sentence describing the skill's purpose
3. When to use it — trigger conditions (what the user says/does that should activate it)
4. Tools needed — which tools the skill requires (Read, Write, Edit, Glob, Grep, Bash, MCP tools, etc.)
5. Workflow steps — the sequence of actions the skill should perform

If the user is unsure, suggest 2-3 concrete use cases and trigger phrases.

Step 2: Validate the Name

The skill name MUST:

• Be kebab-case: my-cool-skill
• Match the folder name exactly
• Describe the domain or concept, not the action — the description already explains what the skill does
• NOT have redundant verb prefixes (add-, new-, get-, run-, do-)
• NOT contain "claude" or "anthropic" (reserved)
• NOT have spaces, underscores, or capitals

Good names: background-job, event, gh-issue, commit, testing-guide, ui-patterns Bad names: add-background-job, new-gh-issue, run-tests, get-user-data

Step 3: Write the YAML Frontmatter

Generate the frontmatter with these fields:

---
name: skill-name
description: What it does. Use when [trigger conditions].
allowed-tools: Tool1, Tool2, Tool3
---

Required fields:

Optional fields:

Description Formula

[What it does] + Use when [trigger conditions with specific phrases users might say].

Good examples:

# Specific and actionable
description: Scaffold a new background job type with handler, type definition, and registration. Use when adding async processing, scheduled tasks, or retry-based workflows.

# Includes trigger phrases
description: Create git commits from current changes using Conventional Commits format. Use when ready to commit staged or unstaged changes.

# Clear scope
description: Expert agent for UI/UX design decisions, component implementations, and design system compliance. Use when building UI components, choosing layouts, or need design system guidance.

Bad examples:

# Too vague
description: Helps with projects.

# Missing triggers
description: Creates sophisticated multi-page documentation systems.

# Too technical, no user triggers
description: Implements the Project entity model with hierarchical relationships.

Step 4: Write the Body Instructions

Use this structure adapted to the skill's needs:

# Skill Name

Brief description of what the skill does and its value.

---

## Workflow

### Step 1: [First Major Step]

Clear explanation with specific tool calls.

1. `Read("path/to/file")` - Why
2. `Glob("pattern")` - Why

### Step 2: [Next Step]

Continue with clear, actionable instructions.

(Add more steps as needed)

### Step N: Present to User

Show all modified/created files for review before committing.

---

## Key Design Decisions

- **Decision 1**: Explanation
- **Decision 2**: Explanation

---

## File References

| File | Purpose |
|------|---------|
| `path/to/file` | What it contains |

Body Best Practices

• Be specific and actionable — include exact tool calls, file paths, expected outputs
• Use progressive disclosure — keep SKILL.md focused on core instructions, move detailed docs to references/
• Include error handling — document common issues and solutions
• Add examples — show concrete inputs/outputs for common scenarios
• Keep it under 5,000 words — move reference material to separate files
• Put critical instructions at the top — Claude processes top content first
• Use numbered lists for sequential steps — bullets for non-ordered items
• Reference bundled resources clearly — link to references/ files when available

Step 5: Review the Existing Skills

Before creating, scan for overlap with existing skills:

Glob(".claude/skills/*/SKILL.md")

If there's overlap, suggest extending the existing skill instead.

Step 6: Create the Skill

1. Create the folder: .claude/skills/{skill-name}/
2. Write SKILL.md with frontmatter + body
3. Optionally create scripts/, references/, or assets/ subdirectories if needed

Critical rules:

• File MUST be named exactly SKILL.md (case-sensitive)
• Do NOT create a README.md inside the skill folder
• Folder name MUST match the name field in frontmatter

Step 7: Validate with Checklist

Run through this checklist before presenting to the user:

• Folder named in kebab-case
• SKILL.md file exists (exact casing)
• YAML frontmatter has --- delimiters
• name field: kebab-case, no spaces, no capitals
• name describes domain/concept, no verb prefixes (add-, new-, get-, run-)
• name matches folder name
• description includes WHAT and WHEN (has "Use when")
• description under 1024 characters
• No XML tags (< >) in frontmatter
• No "claude" or "anthropic" in the name
• allowed-tools field present
• Instructions are clear and actionable
• Error handling included (if applicable)
• File references table present

Step 8: Update CLAUDE.md

After creating the skill, update the skills count and list in CLAUDE.md under the "Skills-First Approach" section. Add the new skill name to the list in alphabetical order and increment the count.

Step 9: Present to User

Show the complete skill for review:

1. Display the full SKILL.md content
2. Highlight the trigger conditions
3. Suggest 3 test queries to verify triggering:
   • One obvious trigger
   • One paraphrased trigger
   • One that should NOT trigger

Skill Categories

Most skills fall into one of these categories:

Progressive Disclosure (3-Level System)

Skills use a three-level loading system to minimize token usage:

Design your skill with this in mind — keep the description informative enough for Level 1 decisions, the body complete for Level 2 execution, and move detailed reference material to Level 3.

Common Pitfalls

File References