Writing Skills

Overview

~/.claude/skills

~/.agents/skills/

What is a Skill?

TDD Mapping for Skills

When to Create a Skill

• Technique wasn't intuitively obvious to you
• You'd reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

• One-off solutions
• Standard practices well-documented elsewhere
• Project-specific conventions (put in CLAUDE.md)
• Mechanical constraints (if it's enforceable with regex/validation, automate it—save documentation for judgment calls)

Skill Types

Technique

Pattern

Reference

Authoring Standard

• NAME-01

  and

  FRONTMATTER-01

  for skill naming and frontmatter

• TRIGGER-01

  ,

  TRIGGER-02

  , and

  SEARCH-01

  for descriptions and discoverability

• STRUCTURE-01

  and

  STRUCTURE-02

  for what belongs in

  SKILL.md

• DISCLOSURE-01

  ,

  TOPOLOGY-01

  , and

  TOPOLOGY-02

  for supporting files

• EXAMPLE-01

  ,

  METADATA-01

  , and

  RUNTIME-01

  for examples and runtime parity

Optional Authoring Patterns

• Use small flowcharts only for non-obvious decisions or loops where agents commonly stop too early.
• Prefer one excellent example over multi-language dilution.
• Use

  graphviz-conventions.dot

  in this directory for diagram styling when you truly need a flowchart.
• Use

  render-graphs.js

  to render diagrams for human review when needed.

The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

• Not for "simple additions"
• Not for "just adding a section"
• Not for "documentation updates"
• Don't keep untested changes as "reference"
• Don't "adapt" while running tests
• Delete means delete

Testing All Skill Types

Discipline-Enforcing Skills (rules/requirements)

• Academic questions: Do they understand the rules?
• Pressure scenarios: Do they comply under stress?
• Multiple pressures combined: time + sunk cost + exhaustion
• Identify rationalizations and add explicit counters

Technique Skills (how-to guides)

• Application scenarios: Can they apply the technique correctly?
• Variation scenarios: Do they handle edge cases?
• Missing information tests: Do instructions have gaps?

Pattern Skills (mental models)

• Recognition scenarios: Do they recognize when pattern applies?
• Application scenarios: Can they use the mental model?
• Counter-examples: Do they know when NOT to apply?

Reference Skills (documentation/APIs)

• Retrieval scenarios: Can they find the right information?
• Application scenarios: Can they use what they found correctly?
• Gap testing: Are common use cases covered?

Common Rationalizations for Skipping Testing

Bulletproofing Skills Against Rationalization

Close Every Loophole Explicitly

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

</Good>

### Address "Spirit vs Letter" Arguments

Add foundational principle early:

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

Build Rationalization Table

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

Create Red Flags List

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

Update CSO for Violation Symptoms

TRIGGER-01

TRIGGER-02

description: use when implementing any feature or bugfix, before writing implementation code

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test (Baseline)

• What choices did they make?
• What rationalizations did they use (verbatim)?
• Which pressures triggered violations?

GREEN: Write Minimal Skill

REFACTOR: Close Loopholes

• How to write pressure scenarios
• Pressure types (time, sunk cost, authority, exhaustion)
• Plugging holes systematically
• Meta-testing techniques

Anti-Patterns

❌ Narrative Example

❌ Multi-Language Dilution

❌ Code in Flowcharts

step1 [label="import fs"];
step2 [label="read file"];

❌ Generic Labels

STOP: Before Moving to Next Skill

• Create multiple skills in batch without testing each
• Move to next skill before current one is verified
• Skip testing because "batching is more efficient"

Skill Creation Checklist (TDD Adapted)

• Create pressure scenarios (3+ combined pressures for discipline skills)
• Run scenarios WITHOUT skill - document baseline behavior verbatim
• Identify patterns in rationalizations/failures

• Apply

  NAME-01

  and

  FRONTMATTER-01

• Apply

  TRIGGER-01

  ,

  TRIGGER-02

  , and

  SEARCH-01

• Clear overview with core principle
• Address specific baseline failures identified in RED
• Apply

  STRUCTURE-01

  ,

  STRUCTURE-02

  , and

  DISCLOSURE-01

• Apply

  EXAMPLE-01

  and

  METADATA-01

  where relevant
• Run scenarios WITH skill - verify agents now comply

• Identify NEW rationalizations from testing
• Add explicit counters (if discipline skill)
• Build rationalization table from all test iterations
• Create red flags list
• Re-test until bulletproof

• Shared-standard rules are satisfied without duplicating policy prose locally
• Quick reference table or equivalent scan-friendly structure
• Common mistakes or failure modes are easy to find
• No narrative storytelling
• Supporting files satisfy

  TOPOLOGY-01

  and

  TOPOLOGY-02

• Commit skill to git and push to your fork (if configured)
• Consider contributing back via PR (if broadly useful)

The Bottom Line