create-skill

name	create-skill
description	Interactive guide for creating new Claude skills with proper structure, frontmatter, and trigger conditions. Use when building a new skill, scaffolding a SKILL.md, or need guidance on skill best practices.
allowed-tools	Read, Write, Edit, Glob, Grep

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:

Field	Rules
name	kebab-case, must match folder name
description	MUST include WHAT + WHEN (trigger phrases). Under 1024 chars. No XML tags (< or >).

Optional fields:

Field	Rules
allowed-tools	Comma-separated list of tools the skill can use. Restricts access for security.
license	For open-source skills (e.g., MIT, Apache-2.0)
compatibility	1-500 chars, environment requirements
metadata	Custom key-value pairs (author, version, mcp-server)

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:

Category	Use for	Example
Document & Asset Creation	Consistent, high-quality output (docs, code, designs)	ui-patterns, ux-ui-designer
Workflow Automation	Multi-step processes with consistent methodology	commit, create-pr, start-working-on-issue
Scaffolding	Creating new code/config following project patterns	background-job, event
Reference/Guide	Domain knowledge and best practices	testing-guide, better-auth-best-practices
MCP Enhancement	Workflow guidance on top of MCP tool access	linear-issue-implement, linear-task-create

---

Progressive Disclosure (3-Level System)

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

Level	What	When Loaded
Level 1	YAML frontmatter (name, description)	Always in system prompt
Level 2	SKILL.md body (full instructions)	When Claude thinks the skill is relevant
Level 3	Linked files (references/, scripts/, assets/)	Only when Claude navigates to them

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

Problem	Cause	Solution
Skill never triggers	Description too vague or missing trigger phrases	Add specific "Use when" conditions and user phrases
Skill triggers too often	Description too broad	Add scope limits, be more specific, add negative triggers
Instructions not followed	Too verbose or ambiguous	Use numbered steps, specific tool calls, exact file paths
Upload fails	Wrong file name or YAML format	Must be exactly SKILL.md, check --- delimiters

---

File References

File	Purpose
.claude/skills/*/SKILL.md	All existing skills for reference
CLAUDE.md	Project instructions — update skill count after creating