Writing Skills

Overview

~/.claude/skills

~/.agents/skills/

What is a Skill?

TDD Mapped to Skills

When to Create a Skill

• The technique isn't intuitively obvious to you
• You'll reference it repeatedly across different projects
• The pattern has broad applicability (not project-specific)
• Others will also benefit

• One-off solutions
• Standard practices already well-documented elsewhere
• Project-specific conventions (put in CLAUDE.md)
• Mechanical constraints (automate if you can enforce with regex/validation — documentation is for scenarios requiring judgment)

Skill Types

Technical

Pattern

Reference

Directory Structure

skills/
  skill-name/
    SKILL.md              # Primary reference document (required)
    supporting-file.*     # Only if needed

1. Large reference content (100+ lines) - API docs, comprehensive syntax explanations
2. Reusable tools - Scripts, utilities, templates

• Principles and concepts
• Code patterns (< 50 lines)
• Everything else

SKILL.md Structure

• Two required fields:

  name

  and

  description

  (see agentskills.io/specification for full supported fields)
• Maximum 1024 characters total

• name

  : Use only letters, numbers, and hyphens (no brackets, special characters)

• description

  : Third person, describes only when to use (not what it does)
  • Start with "Use when...", focus on trigger conditions
  • Include specific symptoms, scenarios, and context
  • Never summarize the skill's process or workflow (see CSO section for why)
  • Try to keep under 500 characters

---
name: Skill-Name-With-Hyphens
description: Use when [specific trigger conditions and symptoms]
---

# Skill Name

## Overview
What is it? Explain core principles in 1-2 sentences.

## When to Use
[Use small inline flowcharts if decisions aren't obvious]

Bullet list of symptoms and use cases
Scenarios where it doesn't apply

## Core Pattern (Technical/Pattern Types)
Before-and-after code comparison

## Quick Reference
Table or bullet points for quick browsing of common operations

## Implementation
Simple patterns inline code
Large reference or reusable tools link to files

## Common Mistakes
Common issues + fixes

## Practical Outcomes (Optional)
Specific results

Claude Search Optimization (CSO)

1. Rich Description Field

# Bad: Summarizes workflow - Claude may follow description instead of skill
description: Use when executing plans - dispatches subagent per task with code review between tasks

# Bad: Too many process details
description: Use for TDD - write test first, watch it fail, write minimal code, refactor

# Good: Only trigger conditions, no workflow summary
description: Use when executing implementation plans with independent tasks in the current session

# Good: Only trigger conditions
description: Use when implementing any feature or bugfix, before writing implementation code

• Use specific trigger conditions, symptoms, and scenarios to indicate when this skill applies
• Describe problems (race conditions, inconsistent behavior) not language-specific symptoms (setTimeout, sleep)
• Keep trigger conditions technology-agnostic unless the skill itself is technology-specific
• If the skill is technology-specific, clearly state that in the trigger conditions
• Write in third person (injected into system prompts)
• Never summarize the skill's process or workflow

# Bad: Too abstract, vague, no when-to-use
description: For async testing

# Bad: First person
description: I can help you with async tests when they're flaky

# Bad: Mentions technology but skill isn't specific to it
description: Use when tests use setTimeout/sleep and are flaky

# Good: Starts with "Use when", describes problem, no workflow
description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently

# Good: Technology-specific skill with clear trigger conditions
description: Use when using React Router and handling authentication redirects

2. 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

3. Descriptive Naming

• ✅

  creating-skills

  instead of

  skill-creation

• ✅

  condition-based-waiting

  instead of

  async-test-helpers

4. Token Efficiency (Critical)

• getting-started workflows: <150 words each
• Frequently loaded skills: <200 words total
• Other skills: <500 words (still be concise)

# Bad: List all parameters in SKILL.md
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N

# Good: Reference --help
search-conversations supports multiple modes and filters. Run --help for details.

# Bad: Repeat workflow details
When searching, dispatch subagent with template...
[20 lines of repeated instructions]

# Good: Reference other skills
Always use subagents (saves 50-100x context). Required: Use [other-skill-name] workflow.

# Bad: Verbose example (42 words)
Your partner: "How did we handle authentication errors in React Router before?"
You: I'll search past conversations for React Router authentication patterns.
[Dispatch subagent with search query: "React Router authentication error handling 401"]

# Good: Streamlined example (20 words)
Partner: "How did we handle authentication errors in React Router before?"
You: Searching...
[Dispatch subagent → integrate]

• Don't repeat content already in cross-referenced skills
• Don't explain things obvious from commands
• Don't provide multiple examples for the same pattern

wc -w skills/path/SKILL.md
# getting-started workflows: target <150 each
# Other frequently loaded: target <200 total

• ✅

  condition-based-waiting

  >

  async-test-helpers

• ✅

  using-skills

  instead of

  skill-usage

• ✅

  flatten-with-flags

  >

  data-structure-refactoring

• ✅

  root-cause-tracing

  >

  debugging-techniques

• creating-skills

  ,

  testing-skills

  ,

  debugging-with-logs

• Active, describes what you're doing

4. Cross-Reference Other Skills

• ✅ Good:

  **Required Subskill:** Use superpowers:test-driven-development

• ✅ Good:

  **Required Background:** You must understand superpowers:systematic-debugging

• ❌ Bad:

  See skills/testing/test-driven-development

  (unclear if required)
• ❌ Bad:

  @skills/testing/test-driven-development/SKILL.md

  (forces immediate loading, wastes context)

@

Flowchart Usage

digraph when_flowchart {
    "Need to show information?" [shape=diamond];
    "Might I make a mistake in decision?" [shape=diamond];
    "Use markdown" [shape=box];
    "Small inline flowchart" [shape=box];

    "Need to show information?" -> "Might I make a mistake in decision?" [label="Yes"];
    "Might I make a mistake in decision?" -> "Small inline flowchart" [label="Yes"];
    "Might I make a mistake in decision?" -> "Use markdown" [label="No"];
}

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

• Reference material → tables, lists
• Code examples → Markdown code blocks
• Linear instructions → numbered lists
• Labels with no semantic meaning (step1, helper2)

render-graphs.js

./render-graphs.js ../some-skill           # Render each chart separately
./render-graphs.js ../some-skill --combine # Combine all charts into one SVG

Code Examples

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

• Fully runnable
• Well-commented, explains why
• From real scenarios
• Clearly demonstrates the pattern
• Can be adapted directly (not generic templates)

• Implement in more than 5 languages
• Create fill-in-the-blank templates
• Write artificially constructed examples

File Organization

Self-Contained Skill

defense-in-depth/
  SKILL.md    # All content inline

Skill with Reusable Tools

condition-based-waiting/
  SKILL.md    # Overview + pattern
  example.ts  # Adaptable working code

Skill with Large Reference

pptx/
  SKILL.md       # Overview + workflow
  pptxgenjs.md   # 600-line API reference
  ooxml.md       # 500-line XML structure
  scripts/       # Executable tools

Iron Rule (Same as TDD)

Don't write a skill without a failing test

• Doesn't apply to "simple additions"
• Doesn't apply to "just adding a section"
• Doesn't apply to "documentation updates"
• Don't keep untested changes as "reference"
• Don't "adjust" while running tests
• Delete means delete

Testing All Skill Types

Discipline-Enforcing Skills (Rules/Requirements)

• Academic questions: Do they understand the rules?
• Stress scenarios: Do they follow them under pressure?
• Multiple stress combinations: Time + sunk cost + fatigue
• Identify rationalizations and add explicit rebuttals

Technical Skills (How-To Guides)

• Application scenarios: Can they apply the technique correctly?
• Variant scenarios: Can they handle edge cases?
• Missing information tests: Do they indicate when something is missing?

Pattern Skills (Mental Models)

• Recognition scenarios: Can they identify when the pattern applies?
• Application scenarios: Can they use the mental model?
• Counterexamples: Do they know when not to apply it?

Reference Skills (Documentation/API)

• Retrieval scenarios: Can they find the correct information?
• Application scenarios: Can they use the found content correctly?
• Coverage tests: Are common use cases all covered?

Common Rationalizations for Skipping Tests

Making Skills Resist Rationalization

Explicitly Plug Each Loophole

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

</Good>

### Address "Spirit vs Letter" Debates

Add foundational principle upfront:

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

Build a Rationalization Table

| Rationalization | Reality |
|------|------|
| "Too simple to test" | Simple code still breaks. Testing takes 30 seconds. |
| "I'll test later" | Tests passing immediately proves nothing. |
| "Testing after works just as well" | Testing after = "What does this do?" Testing before = "What should this do?" |

Create a Red Line List

## Red Lines - Stop and Start Over

- Wrote code before tests
- "I've manually tested this"
- "Testing after works just as well"
- "The spirit matters more than the ritual"
- "This case is different because..."

**All of the above mean: Delete code. Restart with TDD.**

Update CSO to Include Violation Symptoms

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 exact rationalizations did they use?
• Which stresses triggered violations?

Green: Write Minimal Skill

Refactor: Plug Loopholes

• How to write stress scenarios
• Types of stress (time, sunk cost, authority, fatigue)
• Systematically plugging loopholes
• Meta-testing techniques

Anti-Patterns

Narrative Examples

Multi-Language Dilution

Code in Flowcharts

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

Generic Labels

Stop: Before Moving to Next Skill

• Batch-create multiple skills without testing each one
• Move to the next skill before validating the current one
• Skip testing because "batch processing is more efficient"

Skill Creation Checklist (TDD-Adapted)

• Create stress scenarios (3+ combined stresses for discipline skills)
• Run scenarios without skill - record baseline behavior verbatim
• Identify patterns in rationalizations

• Name uses only letters, numbers, hyphens (no brackets/special characters)
• YAML frontmatter includes required

  name

  and

  description

  fields (max 1024 characters; see spec)
• Description starts with "Use when..." and includes specific trigger conditions/symptoms
• Description uses third person
• Full text includes search keywords (errors, symptoms, tools)
• Clear overview with core principles
• Addresses specific baseline failures identified in Red Phase
• Code inline or linked to separate files
• One excellent example (not multi-language)
• Run scenarios with skill - verify agents now comply

• Identify new rationalizations from testing
• Add explicit rebuttals (discipline skills)
• Build rationalization table from all test iterations
• Create red line list
• Retest until unbreakable

• Only use small flowcharts when decisions aren't obvious
• Quick reference table
• Common mistakes section
• No narrative stories
• Supporting files only for tools or large reference

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

Discovery Workflow

1. Encounter problem ("Tests are flaky")
2. Find skill (description matches)
3. Scan overview (Is this relevant?)
4. Read pattern (Quick reference table)
5. Load example (Only when implementing)

Summary