Skip to content

SKILL_DESIGN.md

Latest commit

 

History

History
131 lines (89 loc) · 4.75 KB

SKILL_DESIGN.md

File metadata and controls

131 lines (89 loc) · 4.75 KB
Raw

Skill Design — When and How to Create Skills

Official skill format, naming conventions, the rigid-vs-flexible distinction, and the inline-to-skill migration pattern.

What a Skill Is

A skill is a SKILL.md file in .claude/skills/[skill-name]/. It loads on demand — invoked by name or by a matching trigger condition — and costs zero tokens until loaded. This is the fundamental difference from CLAUDE.md, which loads every turn regardless of whether it's needed.

Skills load on demand. CLAUDE.md loads every turn.

This single distinction drives the entire CLAUDE.md reduction strategy: anything that isn't needed every session belongs in a skill.

What Belongs in a Skill

Content type Goes in a skill if... Stays in CLAUDE.md if...
Multi-step procedure It's only needed in specific contexts It's a core safety rule applied every session
Phase template Only needed during that phase —
API reference Only consulted when using the API —
Session protocol Invoked by trigger phrase —
Hard ban Never — hard bans must always be visible Always
Project identity Never Always
Risk triage rules Never Always
Agent definitions .claude/agents/ instead —

Rule of thumb: If you find yourself reading a section of CLAUDE.md every session just in case you need it, that section is a skill candidate.

Official Skill Format

---
name: skill-name
description: When to load this skill — be specific about the trigger condition.
             Example: "Use when the user types /session-end or the phrase 'Session End'."
---

The description field is what Claude reads to decide when to load the skill. Write it as a trigger condition, not a topic description.

After the frontmatter: plain Markdown instructions, steps, templates, and code examples.

Rigid vs. Flexible Skills

Rigid skills (follow exactly — no adaptation): session protocols, quality checklists, deployment procedures. These exist because the cost of skipping a step is high. Write them as numbered checklists with "Do NOT skip steps" instructions.

Flexible skills (apply principles, adapt to context): design patterns, prompt templates, style guides. These provide a framework, not a script. Write them as guidelines with examples and rationale.

Label the type at the top of the skill so Claude knows how to apply it.

Skill Naming Conventions

.claude/skills/
├── session-end/SKILL.md        ← kebab-case, imperative verb
├── session-start/SKILL.md
├── api-verify/SKILL.md         ← verb-noun pattern
├── pipeline-run/SKILL.md
├── explore/SKILL.md            ← phase names (single verb)
├── implement/SKILL.md
└── learned/                    ← instinct files sub-directory
    ├── pattern-name.md
    └── ...
  • Name skills after the action, not the content: session-end not session-management
  • Use kebab-case
  • Keep names short enough to invoke comfortably: /session-end not /run-the-session-end-protocol

Skill Chaining

Skills can reference each other. A parent skill can instruct Claude to load a child skill for part of its work:

## Step 3 — Verify API calls
Load the `api-verify` skill and follow its protocol before proceeding.

Limit to two levels of chaining (parent → child). Three or more levels creates context confusion.

Converting a Hook + Skill

Anthropic draws a hard line between Claude.md (advisory) and hooks (deterministic). Convert critical protocols to hooks:

// .claude/settings.json
{
  "hooks": {
    "Stop": [
      {
        "command": "echo '⚠️  Run /session-end before closing. Docs will drift if you skip it.'",
        "description": "Remind to run session-end protocol"
      }
    ]
  }
}

The hook fires reliably on session end. The skill contains the protocol steps. The combination makes the workflow mechanically enforced rather than advisory.

Migration Pattern: Inline → Skill

  1. Create the skill file with the procedure content
  2. Test the skill by invoking it directly: confirm it contains the full procedure and Claude executes it correctly
  3. Replace the inline content in CLAUDE.md with a one-line pointer: "For implementation prompting patterns, invoke /implement."
  4. Verify the replacement session runs correctly with the pointer

Never remove the inline content before step 2 is confirmed. Never leave a capability gap.

Template

→ templates/skill-template.md — blank skill with YAML frontmatter, step structure, and verification section.

→ examples/example-skill.md — complete annotated session-end skill.