Writing Skills

Writing Skills

Invariant Principles

1. No Skill Without Failing Test: Run scenario WITHOUT skill first. Document baseline failures verbatim. Same as code TDD.
2. Description Triggers, Not Summarizes: Description = when to load, never workflow summary. Workflow in description causes agents to skip body.
3. One Excellent Example Beats Many: Single complete, runnable example in relevant language. You port well.
4. Keywords Enable Discovery: Error messages, symptoms, synonyms throughout. Future Claude must FIND this.
5. Close Every Loophole Explicitly: Agents rationalize under pressure. Each excuse needs explicit counter.

Inputs

Outputs

Skill Types

SKILL.md Schema

skills/<name>/
  SKILL.md              # Required. Main content inline
  supporting-file.*     # Only for heavy reference (100+ lines) or reusable tools

Frontmatter (YAML only):

---
name: skill-name-with-hyphens   # letters, numbers, hyphens only
description: Use when [triggering conditions and symptoms only, NEVER workflow]
---

Required sections:

# Skill Name

## Overview
What is this? Core principle in 1-2 sentences.

## When to Use
- Bullet list with SYMPTOMS and use cases
- When NOT to use
[Small inline flowchart IF decision non-obvious]

## Core Pattern (for techniques/patterns)
Before/after code comparison

## Quick Reference
Table or bullets for scanning common operations

## Implementation
Inline code for simple patterns
Link to file for heavy reference

## Common Mistakes
What goes wrong + fixes

Naming Conventions

Principles:

• Name by what you DO or core insight, not generic category
• root-cause-tracing > debugging-techniques
• using-skills not skill-usage

Claude Search Optimization (CSO)

# BAD: Workflow summary - agents skip body
description: Use when executing plans - dispatches subagent per task with code review

# GOOD: Triggers only - forces reading body
description: Use when executing implementation plans with independent tasks

Keyword coverage:

• Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
• Symptoms: "flaky", "hanging", "zombie", "pollution"
• Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
• Tools: Actual commands, library names, file types

Writing Effective Skill Descriptions

The description field in SKILL.md frontmatter is the primary mechanism for matching user requests to skills. The LLM reads all descriptions and selects the best match. A poorly written description means the skill never fires when it should, or fires when it shouldn't.

Description Anatomy

A good description has four parts:

1. Situation (1 sentence): When this skill applies
2. Trigger phrases (3-10 phrases): Natural language that users actually say
3. Anti-triggers (optional): When NOT to use this skill, to disambiguate from overlapping skills
4. Invocation note (optional): If primarily invoked by other skills, say so

The Golden Rule: User Phrasings, Not Abstract Situations

BAD: "Use when debugging bugs or unexpected behavior" GOOD: "Use when debugging bugs, test failures, or unexpected behavior. Triggers: 'why isn't this working', 'this is broken', 'getting an error', 'stopped working', 'regression', 'crash', 'flaky test', or when user pastes a stack trace."

The BAD version describes the situation abstractly. The GOOD version includes the actual words users type when they need debugging help. Users say "this is broken" far more often than "I need to debug."

Checklist for Every Description

• Contains 3-10 trigger phrases in quotes that match how users actually talk
• Leads with user intent, not implementation details or internal workflow jargon
• Disambiguates from overlapping skills with "NOT for" or "For X instead, use Y"
• Notes invocation path if primarily called by other skills ("Also invoked by X")
• Avoids being too broad ("Use when writing code" matches everything) or too narrow ("Use only during Phase 2.1 of the Forged workflow")
• No internal jargon that only spellbook developers would know

Model Descriptions (from the library)

Best: verifying-hunches -- Comprehensive trigger list drawn from natural speech:

"Use when about to claim discovery during debugging. Triggers: 'I found', 'this is the issue',
'root cause', 'smoking gun', 'aha', 'got it', 'the fix is', 'should fix', 'this will fix'.
Also invoked by debugging before any root cause claim."

Why it works: 20+ trigger phrases covering both excited discovery ("aha!", "got it") and confident claims ("root cause", "the fix is"). Notes auto-invocation path. Narrow enough to avoid false positives.

Best: implementing-features -- Clear scope with anti-triggers:

"Use when building, creating, or adding functionality. Triggers: 'implement X', 'build Y',
'add feature Z', 'Would be great to...', 'I want to...', 'We need...'.
NOT for: bug fixes, pure research, or questions about existing code."

Why it works: Covers both direct commands ("implement X") and wish-phrasing ("Would be great to..."). The "NOT for" section prevents false matches on debugging or research requests.

Best: isolated-testing -- Behavioral triggers beyond just words:

"Use when testing theories during debugging, or when chaos is detected.
Triggers: 'let me try', 'maybe if I', 'quick test', rapid context switching,
multiple changes without isolation."

Why it works: Includes behavioral patterns (rapid context switching, multiple changes without isolation) that the LLM can detect in its own actions, not just user text.

Common Description Anti-Patterns

System-Triggered vs. User-Triggered Skills

Some skills are invoked by system events or other skills, not by users:

• System-only (e.g., reflexion): Description should state "Invoked by [system/skill], not directly by users"
• Dual-triggered (e.g., tarot-mode): Description should cover both the system trigger AND user-facing triggers
• User-only (e.g., debugging): Description should focus entirely on user phrasings

The Overlap Problem

When multiple skills cover similar territory (e.g., 4 review skills), each description MUST include:

1. What makes THIS skill the right choice
2. When to use a DIFFERENT skill instead

Example for a review skill family:

• code-review: "For focused single-pass review. NOT for: heavy multi-phase analysis (use advanced-code-review) or PR triage (use distilling-prs)."
• advanced-code-review: "For thorough 5-phase analysis with historical context. NOT for: quick review (use code-review) or PR categorization (use distilling-prs)."
• distilling-prs: "For triaging and categorizing PR changes. NOT for: deep code analysis (use advanced-code-review)."

Iron Law

NO SKILL WITHOUT FAILING TEST FIRST

Write skill before testing? Delete it. Start over. Edit skill without testing? Same violation.

No exceptions:

• 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

RED-GREEN-REFACTOR

The full RED-GREEN-REFACTOR implementation (pressure scenarios, baseline testing, skill writing, loophole closure, rationalization tables, red flags, and creation checklist) is in the write-skill-test command. Dispatch a subagent to execute it.

Phase summary:

1. RED - Run pressure scenarios WITHOUT skill. Document baseline failures and rationalizations verbatim.
2. GREEN - Write minimal skill addressing specific baseline failures. Verify compliance with same scenarios.
3. REFACTOR - Close new loopholes. Build rationalization table. Re-test until bulletproof.

Dispatch template:

Task(
  description: "RED-GREEN-REFACTOR skill testing",
  prompt: """
First, invoke the write-skill-test command using the Skill tool.
Then follow its complete workflow.

## Context

Skill purpose: [what the skill should do]
Skill type: [discipline/technique/pattern/reference]
Target location: skills/<name>/SKILL.md
Pressure scenarios to test: [describe scenarios]
"""
)

Token Efficiency

Targets:

• Getting-started skills: <150 words
• Frequently-loaded skills: <200 words
• Other skills: <500 words

Techniques:

• Reference --help instead of documenting all flags
• Cross-reference other skills: **REQUIRED BACKGROUND:** test-driven-development
• One excellent example, not multi-language
• No @ links (force-loads files, burns context)

File Organization

Code Examples

One excellent example beats many mediocre ones.

Choose most relevant language:

• Testing techniques: TypeScript/JavaScript
• System debugging: Shell/Python
• Data processing: Python

Good example: Complete, runnable, well-commented explaining WHY, from real scenario, ready to adapt.

Don't: Implement in 5+ languages, create fill-in-the-blank templates, write contrived examples.

Flowchart Usage

Use ONLY for:

• Non-obvious decision points
• Process loops where you might stop too early
• "When to use A vs B" decisions

Never use for: Reference material (use tables), Code examples (use markdown), Linear instructions (use numbered lists).

Anti-Patterns

Discovery Workflow

How future Claude finds your skill:

1. Encounters problem ("tests are flaky")
2. Finds SKILL (description matches)
3. Scans overview (is this relevant?)
4. Reads patterns (quick reference table)
5. Loads example (only when implementing)

Optimize for this flow - searchable terms early and often.

Multi-Phase Skill Architecture

Skills with multiple phases face a structural decision: what belongs in the orchestrator SKILL.md versus phase commands invoked by subagents?

When this applies:

The Core Rule: The orchestrator dispatches subagents (Task tool). Subagents invoke phase commands (Skill tool). The orchestrator NEVER invokes phase commands directly into its own context.

Content Split:

Data structure placement: If referenced by 2+ phases, define in orchestrator. If referenced by 1 phase only, define in that phase's command.

Soft target: ~300 lines for orchestrator SKILL.md. The hard rule is about content types: orchestrators contain coordination logic, never implementation logic.

Exceptions:

• Config/setup phases requiring direct user interaction MAY run in orchestrator context
• Error recovery MAY load phase context temporarily to diagnose failures

Canonical example: implementing-features uses 5 commands across 6+ phases. The orchestrator defines phase sequence, dispatch templates, and shared data structures. Each phase command (discover, design, execute-plan, etc.) contains its own implementation logic.

Anti-Patterns:

Assessment Framework Integration

For skills that produce evaluative output (verdicts, findings, scores, pass/fail):

1. Run /design-assessment with the target type being evaluated
2. Copy relevant sections from the generated framework into the skill:
   • Dimensions table for evaluation criteria
   • Severity levels for finding classification
   • Finding schema for output structure
   • Verdict logic for decision rules
3. Reference the vocabulary consistently throughout the skill

Benefits:

• Consistent vocabulary across evaluative skills (CRITICAL/HIGH/MEDIUM/LOW/NIT)
• Standardized finding schemas enable cross-skill comparison
• Clear verdict logic prevents ambiguous outcomes

Example skills with evaluative output: code-review, auditing-green-mirage, fact-checking, reviewing-design-docs

Self-Check

Before completing:

• RED phase documented: baseline agent behavior captured verbatim
• GREEN phase verified: skill changes behavior in re-run
• Description starts "Use when..." and contains only triggers
• YAML frontmatter has name and description
• Schema elements present: Overview, When to Use, Quick Reference, Common Mistakes
• Token budget met: <500 words core instructions
• Multi-phase architecture: 3+ phase skills separate orchestrator from phase commands
• No workflow summary in description
• Rationalization table built (for discipline skills)

If ANY unchecked: STOP and fix before declaring complete.

REQUIRED BACKGROUND: Understand test-driven-development skill before using this skill.