techdufus/writing-skills

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.