create-a-skill

Create-A-Skill Tutorial

A guided workflow for building any Claude Code skill from scratch — covering planning, structure, writing, and packaging.

When This Skill Applies

• "I want to create a skill for X"
• "Help me build a skill for our team's Y workflow"
• "Create a new skill that handles Z"
• "How do I write a SKILL.md?"
• "What should my skill folder look like?"

---

Step 1 — Understand What the Skill Does

Before writing any files, answer these 3 questions:

1. What domain / task does this skill cover?

   • Be specific. Not "frontend" but "React hooks and state management"
   • Not "docs" but "team API documentation lookup"

2. What would a user say to trigger it?

   • List 3–5 concrete trigger phrases
   • Example: "Build a React component", "optimize my hook", "add state management"

3. What reusable resources would help Claude every time?

   • Scripts that get rewritten repeatedly → scripts/
   • Documentation Claude needs to reference → references/
   • Templates / assets used in output → assets/

See references/structure-patterns.md for help choosing what to include.

---

Step 2 — Choose a Structure Pattern

Three patterns cover most skills:

Pattern A — Simple (single domain)

my-skill/
├── SKILL.md
├── references/
│   └── topic.md
└── examples/
    └── example.md

Use for: focused single-topic skills (testing, TypeScript, git workflows)

Pattern B — Complex (multi-domain routing hub)

my-skill/
├── SKILL.md              ← routing only
├── references/
│   ├── topic-a.md
│   ├── topic-b.md
│   └── topic-c.md
└── scripts/
    └── helper.py

Use for: broad domains needing sub-topic routing (Next.js fullstack, senior-backend)

Pattern C — Reference + Automation

my-skill/
├── SKILL.md
├── references/           ← documentation
├── scripts/              ← executable tools
└── assets/               ← templates / files for output

Use for: skills that produce artifacts or run code (skill-creator, pdf-editor, code-formatter)