How to Create a Skill File

Directory Structure

.claude/skills/<skill-name>/
├── SKILL.md                     # Required. Frontmatter + core frameworks.
├── references/                  # Optional. Detailed examples, case studies, full docs.
│   └── <reference-file>.md
├── scripts/                     # Optional. Executable code the skill calls (Python, Bash).
│   └── validate.py
└── assets/                      # Optional. Templates, fonts, icons used in output.
    └── template.md

• Project skill: .claude/skills/<skill-name>/ (this project only)
• Global skill: ~/.claude/skills/<skill-name>/ (all projects)

Naming Rules

• Lowercase, numbers, and hyphens only. Max 64 characters.
• No leading/trailing hyphens, no double hyphens
• Name reflects function: campaign-ideation, not playbook-1
• Must match directory name exactly

Frontmatter

Two required fields:

---
name: <skill-name>
description: <max 1024 chars>
---

`description` is the most important field. Claude uses it to decide whether to activate the skill. A good description answers: What does the skill do? and When should Claude use it? Front-load keywords and include "Use this skill when..." triggers. If a skill isn't firing when you expect, add more keywords that match how you actually phrase your requests.

Example — weak vs strong description:

• ❌ Weak: description: Helps you create skills. — no domain keywords, no triggers. Claude can't tell what it does or when to fire it, so it mostly won't.
• ✅ Strong: description: How to create Claude Code skill files. Use this skill when the user asks to convert learnings, playbooks, or frameworks into a skill, or says "make this a skill" / "create a skill for this". — names the artifact, front-loads keywords (skill file, frameworks), and lists the literal phrases that should trigger it.

The strong version wins because activation is keyword/intent matching: spell out the exact words and phrasings you'd actually use. (Note: trigger phrases only auto-fire the skill if disable-model-invocation is not set — otherwise the skill is manual-/name-only and the phrases are just documentation.)

Negative triggers (only if a skill over-fires). If a skill keeps loading for the wrong requests — usually because it shares keywords with a sibling skill — add a "do NOT use" carve-out naming the wrong case and where to go instead — e.g. Do NOT use for diagnosing why a campaign underperforms (use campaign-debugging). or, generically, Do NOT use for simple data exploration (use data-viz instead). Add these reactively, when you observe mis-firing — not preemptively, since every word here is always-loaded.

Constraints: no XML angle brackets (< >) anywhere in frontmatter (security); name can't start with claude/anthropic (reserved); the file must be named exactly SKILL.md (case-sensitive); no README.md inside the skill folder.

Optional fields:

• disable-model-invocation: true — manual /skill-name only, no auto-trigger
• user-invocable: false — hidden from menu, only Claude sees it
• allowed-tools — restricts which tools Claude can use (e.g., Read Grep Bash)
• model — model override (e.g., opus)
• argument-hint — shown in autocomplete (e.g., [topic])
• effort — low, medium, high, max
• context: fork — run in isolated subagent context

Progressive Disclosure — how content loads

A skill loads in three levels, each only when needed. This is why the split exists:

1. `description:` — always in the system prompt of every conversation. Keep it lean; it's permanent rent.
2. SKILL.md body — loads only when Claude judges the skill relevant.
3. `references/`, `scripts/`, `assets/` — load only when Claude opens that specific file mid-task. Zero cost until then.

The split rule: does Claude need this every time the skill fires, or only sometimes? Every-time → body. Sometimes → a reference file. Don't cram a big benchmark table into SKILL.md "to be handy" — it bloats level 2 on every trigger. Link it instead.

How to Split Content

SKILL.md (under 500 lines): Core frameworks, rules, principles — what Claude needs every time. Link to references: See [full-playbook.md](references/full-playbook.md) for details.

references/ folder: Detailed examples, case studies, extended breakdowns, data tables — depth needed only occasionally.

Step-by-Step Process

1. ASK BEFORE WRITING — never assume. Always ask the user where the skill should live: global (~/.claude/skills/, all projects) or project (.claude/skills/, this repo only)? Confirm the scope and the trigger phrases with the user before generating the file — use AskUserQuestion if available.
2. Identify the knowledge — what frameworks, rules, or processes need to be captured.
3. Write SKILL.md — distill to core frameworks. Cut examples to one per concept. Keep under 500 lines.
4. Move extras to references/ and link them from SKILL.md.

Best authoring order — task-first, not memory-first. Don't write the skill abstractly from memory. Work one real, hard instance of the task in a normal conversation, correcting Claude until the output is good — then extract the winning path into SKILL.md. The corrections you had to make are the skill: they mark exactly where Claude's default was wrong. Same loop for maintenance: when an existing skill produces a bad result, bring that failure back and patch it.

Test That It Fires

Activation is just Claude reading the description and matching it to the request — so test that directly. In a fresh conversation, ask: "When would you use the `<skill-name>` skill?" Claude paraphrases the description back. Compare to how you actually phrase requests: missing a phrasing you use often → add that keyword; firing on cases you'd never want → tighten it or add a negative trigger. To test a boundary between two overlapping skills, pose a borderline request and ask which fires and why; if it picks wrong, sharpen the verbs.

Getting Instructions Followed

A skill can load correctly and still be ignored. Three fixes:

• Critical rules go at the top, marked. Use a ## IMPORTANT / ## CRITICAL header for must-not-violate rules — don't bury them in paragraph 9.
• Replace vague language with specifics. "Validate the data" → list the exact checks ("0 empty emails; flag generic inboxes >15%; no duplicate IDs").
• For exact, checkable rules, use a script — not prose. Code is deterministic; language interpretation isn't. Bundle scripts/validate.py and say "run it; do not proceed if it exits non-zero" rather than describing the check in English.

What Makes a Good Skill

• Be explicit and keyword-rich — "help with docs" tells Claude nothing. Spell out what to do and when to trigger.
• SKILL.md is scannable — headers, short paragraphs, lists
• Core frameworks are actionable, not just informational
• References exist for depth but SKILL.md works standalone
• No fluff — every line earns its place