Writing Skills Skill

TDD applied to process documentation.

Core Principle

Writing skills IS TDD applied to process documentation. If you can't test it breaks without the skill, the skill isn't needed.

When to Apply

• Creating new skills

• Editing existing skills

• Reviewing skill quality

• Authoring plugin components

TDD Mapping

TDD Concept Skill Equivalent

Test case Pressure scenario (situation where agent fails without skill)

Production code SKILL.md content

Failing test Agent demonstrably fails the scenario

Passing test Agent handles scenario correctly with skill loaded

Refactor Trim to minimum effective content

RED-GREEN-REFACTOR for Skills

RED: Identify Failure Scenarios

Identify 3+ pressure scenarios where the agent fails without this skill. Document the failure mode. This is your test suite. If you can't find 3 scenarios, the skill probably isn't needed.

GREEN: Write Minimum Effective Content

Write SKILL.md that addresses every identified failure. Minimum content to pass -- no extras, no nice-to-haves, no "comprehensive guides." Every section must map to at least one pressure scenario.

REFACTOR: Trim Aggressively

Remove anything that doesn't directly address a pressure scenario. Target ~120 lines. If removing a line doesn't weaken any pressure scenario, remove it.

SKILL.md Structure Template

name: {short-name} description: "{Role sentence}. Use when {triggers}. Triggers on: {keywords}."

{Name} Skill

{Tagline}

When to Apply

Core Pattern / Framework

Anti-Rationalization Table (if methodology skill)

Common Mistakes

The Bottom Line

Claude Search Optimization (CSO)

The description field determines when Claude loads your skill. Get it wrong and the skill never fires.

• Description = "Use when..." triggers ONLY

• NEVER summarize the workflow in the description

• Include trigger keywords that match how users/agents naturally phrase the need

Good: "Use when receiving review comments from code-reviewer agent, PR reviews, or external feedback. Triggers on: 'review feedback', 'address review', 'fix review comments'."

Bad: "A comprehensive guide to handling code review feedback through a structured process"

The bad example describes what the skill contains. The good example describes when to load it.

Skill Types

Type Purpose Example Line Target

Technique How to do X debugger ~120 lines

Pattern When to use X receiving-code-review ~120 lines

Methodology Discipline for X tdd, verification ~130 lines

Meta How to create X writing-skills ~140 lines

Anti-Rationalization for Skipping Tests

Excuse Counter

"The skill is obviously clear" If it's obvious, you can write 3 failure scenarios in 2 minutes

"It's just a reference doc" Reference docs that don't address failures are shelf-ware

"Testing documentation is overkill" Testing docs IS identifying what problems they solve

"I'll test it in practice" Without defined scenarios, you won't notice when it fails

When NOT to Create a Skill

Not everything deserves a skill:

• Information easily found in docs (link to docs instead)

• One-time procedures (just do them)

• Tool-specific configuration (use CLAUDE.md)

• Content under 30 lines (too simple -- put it in CLAUDE.md)

Token Efficiency

Every line must earn its place:

• Technique/pattern skills: ~120 lines

• Methodology skills: ~130 lines

• Meta skills: ~140 lines

The test: "If removing this line doesn't weaken any pressure scenario, remove it."

Avoid:

• Repetitive examples that demonstrate the same point

• "Nice to know" sections that don't prevent failures

• Long prose when a table communicates faster

• Headers with only 1-2 lines of content (merge them)

Frontmatter Rules

Skills use ONLY name and description in frontmatter:

name: my-skill description: "What it does. Use when X. Triggers on: 'keyword1', 'keyword2'."

No model , tools , or permissionMode . These are not agent definitions.

Common Mistakes

Mistake Why It's Wrong Do This Instead

Writing without pressure scenarios No way to verify the skill works RED phase first -- always

Summarizing workflow in description Claude can't match it to triggers Use "Use when..." pattern

Including everything you know Bloats context, dilutes signal Only what prevents identified failures

Skipping refactor phase Skills grow stale and verbose Trim after every edit

Copying another skill's structure Different types need different shapes Match structure to skill type

The Bottom Line

A skill without tested pressure scenarios is documentation. Documentation without a problem to solve is noise.