build-a-skill

Build a Skill

Guide users through creating a well-crafted Claude Code skill — from raw idea to finished, marketplace-ready files.

What Is a Skill?

A skill is a reusable knowledge package. It has two parts:

• Frontmatter description — the activation trigger. Claude reads this to decide whether the skill is relevant to the current conversation.
• Markdown body — instructions for Claude: what to do, how to do it, step by step.

Good skills are specific (one domain, not a catch-all), lean (core in SKILL.md, details in references/), and triggerable (description contains exact phrases users say).

---

Phase 1 — Discovery

Run a focused conversation. Ask one question at a time — never ask several at once.

1. Domain

"What domain or task is this skill for? One sentence is enough."

Use the answer to draft a name: prefer verb-noun kebab-case (review-pr, write-commit, query-db). If verb-first doesn't fit, domain-action works too.

2. Concrete Examples

"What would you actually type to Claude to trigger this skill? Give me 2–3 real examples of prompts you'd send."

Extract the verb+noun patterns. "Help me rotate this PDF" → "rotate a PDF", "rotate this PDF", "flip a PDF page". These become trigger phrases in the description.

3. Meta-Cognition

These questions help users think clearly about when and why they'd reach for the skill. Ask them one at a time. If a user wants to skip, let them — but most find this valuable.

---

Thought pattern — does the skill support a specific way of thinking?

"Does this skill help with a particular cognitive move — like breaking a problem down, spotting errors, generating alternatives, or structuring information?"

Example signals: "second opinion on X" → error-detection pattern. "Generate options for Y" → divergent thinking. "Summarize Z for a decision" → synthesis pattern. Skills that map to a consistent thought pattern have highly reliable triggers because the user's mental state is the same each time.

---

Process — is there a fixed sequence of steps?

"Is there a repeatable procedure here — a checklist, a decision flow, or a series of steps that always run in the same order?"

Example signals: "Every time I deploy, I do A, B, C" → encode the checklist. "Before every PR I check X, Y, Z" → encode the review flow. Procedural skills are the most powerful kind: the skill body mirrors the real workflow step-by-step.

---

Repetition — how often does this come up?

"How often does this situation arise? Daily, occasionally, or only in specific circumstances?"

Why it matters: High-frequency + tedious → justify scripts or detailed references. Rare but high-stakes → focus on preventing mistakes. This shapes how much to invest in polishing the skill.

---

Similar skills — what already exists?

"Do you know of any similar skills or workflows? What would make this one more specific or different from what's already out there?"

Why it matters: If two skills have overlapping trigger phrases, Claude may pick the wrong one. Either merge the ideas, or sharpen this skill's description to be clearly distinct.

4. Reference Materials

Ask last — not everyone has materials ready:

"Any docs, APIs, schemas, or examples to include? Paste links or text — or say 'none'."

Reference materials go into references/ subdirectory, not into SKILL.md.

---

Phase 2 — Design Summary

Before writing any files, synthesize and confirm:

1. Name — kebab-case (verb-noun preferred)
2. Trigger phrases — 3–5 exact phrases from user examples + 2–3 inferred variants
3. Scope statement — one sentence: what this covers, and what it intentionally excludes
4. Resources — which of references/, examples/, scripts/ are needed

Present this as a short summary and ask: "Does this capture what you have in mind?" Only proceed to file generation once confirmed.

---

Phase 3 — Generate Files

Directory Layout

plugins/<skill-name>/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── <skill-name>/
│       ├── SKILL.md
│       └── references/          ← only if needed
│           └── <topic>.md
└── README.md

SKILL.md

Frontmatter — third-person description, 3+ trigger phrases, under 60 words:

---
name: skill-name
description: >
  This skill should be used when the user asks to "phrase 1", "phrase 2",
  or "phrase 3". [One sentence on purpose and scope.]
version: 1.0.0
---

Body — 1,500–2,000 words, imperative form throughout:

Section	Content
Overview	2–3 sentences: what problem this solves, when it applies
Core workflow	Numbered steps Claude should follow
Quick reference	Optional table for lookup-heavy domains
Additional Resources	Pointers to references/ files if they exist

Writing style — three rules, in priority order:

1. Extremely concise. Sacrifice grammar for brevity. Drop articles, subjects, filler.
2. Imperative. Verb-first. Never "you should", "you need to", "Claude should".
3. Third-person description only. Body is imperative; frontmatter description is third-person.

❌ Verbose	✓ Concise
"You should make sure to validate the input before proceeding."	"Validate input."
"It would be helpful to check the schema first."	"Check schema."
"Claude should use grep to find the patterns."	"Use grep. Extract verb+noun patterns."
"One sentence on purpose and scope."	"One sentence: purpose + scope."

plugin.json

{
  "name": "<skill-name>",
  "version": "1.0.0",
  "description": "<one-line description for /plugin list>",
  "author": { "name": "<author name>" }
}

marketplace.json entry

Add to .claude-plugin/marketplace.json → "plugins" array:

{
  "name": "<skill-name>",
  "description": "<description>",
  "author": { "name": "<author name>" },
  "category": "<category>",
  "source": "./plugins/<skill-name>"
}

Valid categories: productivity, development, security, testing, documentation, design.

---

Phase 4 — Validate

Frontmatter:

• Third-person description ("This skill should be used when…")
• 3+ specific trigger phrases sourced from real user examples
• Scope is concrete — not generic ("helps with coding" is too vague)

Body:

• Imperative throughout — no "you should" or "you need to"
• Under 2,000 words
• Detailed content is in references/, not inline in SKILL.md
• Every referenced file exists on disk

Plugin:

• plugin.json with name, version, description, author
• Entry added to .claude-plugin/marketplace.json
• README.md written with install command

---

Common Mistakes

Weak trigger description:

# ❌ Vague, no trigger phrases
description: Helps with code review.

# ✓ Specific, triggerable
description: This skill should be used when the user asks to "review this PR",
  "check my code for bugs", "look for issues in this diff", or "give feedback
  on my changes". Provides a structured code review workflow.

Everything in SKILL.md: Move anything that pushes the body past 2,000 words to references/<topic>.md. SKILL.md is the entry point, not the encyclopedia. Claude loads references/ only when needed.

Unreferenced resources: If references/patterns.md exists but SKILL.md doesn't mention it, Claude won't know to load it. Always close SKILL.md with an "Additional Resources" section listing every file.

---

Additional Resources

• references/skill-anatomy.md — complete frontmatter field reference, progressive disclosure system, category list, and writing style examples with before/after comparisons