Creating a Skill

Benchmarked against: Anthropic — Skills Quickstart Location: .claude/skills/your-skill-name/prompt.md Format: Markdown prompt file

This guide walks through creating a new skill from scratch.

---

Step 1: Create the directory

mkdir -p .claude/skills/your-skill-name

---

Step 2: Write the prompt

Create .claude/skills/your-skill-name/prompt.md:

# Skill Name — Short Description

> Version: 1.0
> Trigger: When to use this skill
> Scope: What this skill covers

## Purpose

What this skill helps the agent do.

## Prerequisites

What the agent needs before starting.

## Steps

### Step 1: First action

Detailed instructions for step 1.

### Step 2: Second action

Detailed instructions for step 2.

## Output format

What the agent should produce.

## Examples

### Example 1: [Scenario name]

[Worked example]

---

Step 3: Register in CLAUDE.md (optional)

Skills auto-discovered from .claude/skills/ don't need explicit registration. But if you want the skill to appear in the skills list with metadata:

The skill's directory name becomes the command: /your-skill-name.

---

Prompt writing guidelines

Be specific

Vague	Specific
"Review the plan"	"Apply Six Hats analysis: White (facts), Red (feelings), Black (risks), Yellow (benefits), Green (alternatives), Blue (process)"
"Check the code"	"Run npm test, check for TypeScript errors with tsc --noEmit, verify no security vulnerabilities in dependencies"

Include format templates

Agents follow formatting better when given templates:

## Output format

| Hat | Findings |
|-----|----------|
| White (Facts) | [factual observations] |
| Red (Feelings) | [gut reactions] |
| Black (Risks) | [potential problems] |

Set clear boundaries

## Scope
- This skill DOES: [list]
- This skill does NOT: [list]
- If the task is outside scope: [what to do instead]

---

Skill sizing

Size	Tokens	When
Small (500 tokens)	Simple procedures	Single-purpose, few steps
Medium (1,000 tokens)	Standard SOPs	Multi-step with templates
Large (2,000 tokens)	Complex procedures	Many steps, examples, decision trees

Rule of thumb: If a skill exceeds 2,000 tokens, consider splitting it into two skills.

---

Testing a skill

1. Invoke the skill: /your-skill-name
2. Verify the agent follows the SOP steps
3. Check output matches expected format
4. Test edge cases (missing info, ambiguous input)
5. Measure token consumption

---

Related pages

Page	Relationship
Skills Overview	What skills are
Design Patterns	Best practices
Skills in CLAUDE.md	Integration