writing-skills

name	writing-skills
description	Use when creating new skills, editing existing skills, or verifying skills work before deployment

Writing Skills

Overview

Writing skills IS Test-Driven Development applied to process documentation.

Personal skills live in your runtime's skills directory

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

Core principle: If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

REQUIRED BACKGROUND: You MUST understand wukong-code:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.

Official guidance: For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future agents find and apply effective approaches.

Skills are: Reusable techniques, patterns, tools, reference guides

Skills are NOT: Narratives about how you solved a problem once

TDD Mapping for Skills

TDD Concept	Skill Creation
Test case	Pressure scenario with subagent
Production code	Skill document (SKILL.md)
Test fails (RED)	Agent violates rule without skill (baseline)
Test passes (GREEN)	Agent complies with skill present
Refactor	Close loopholes while maintaining compliance
Write test first	Run baseline scenario BEFORE writing skill
Watch it fail	Document exact rationalizations agent uses
Minimal code	Write skill addressing those specific violations
Watch it pass	Verify agent now complies
Refactor cycle	Find new rationalizations → plug → re-verify

The entire skill creation process follows RED-GREEN-REFACTOR.

When to Create a Skill

Create when:

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

Don't create for:

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

Skill Types

• Technique — Concrete method with steps (condition-based-waiting, root-cause-tracing)
• Pattern — Way of thinking (flatten-with-flags, test-invariants)
• Reference — API docs, syntax guides, tool documentation

Directory Structure

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

Flat namespace — all skills in one searchable namespace.

Separate files for: heavy reference (100+ lines); reusable tools/scripts.

Keep inline: principles, small code patterns (< 50 lines), everything else essential.

SKILL.md Structure

Frontmatter (YAML):

• Two required fields: name and description (see agentskills.io/specification for all supported fields)
• Max 1024 characters total
• name: letters, numbers, hyphens only
• description: Third-person, ONLY when to use (NOT what it does). Start with "Use when...". NEVER summarize the skill's process or workflow (agents may follow the description and skip the body).

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

# Skill Name

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

## When to Use
[Small inline flowchart IF decision non-obvious]

Bullet list with SYMPTOMS and use cases
When NOT to use

## 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 or reusable tools

## Common Mistakes
What goes wrong + fixes

## Real-World Impact (optional)
Concrete results

Skill Discovery Optimization (SDO)

Critical: description = when to use, NOT workflow summary. A description that summarizes process becomes a shortcut agents take instead of reading the skill.

On-demand (rich description examples, keywords, naming, token efficiency, cross-refs): skills/writing-skills/references/skill-discovery-optimization.md

Authoring Patterns

Flowcharts, code examples, file organization shapes: skills/writing-skills/references/authoring-patterns.md

Graphviz style: graphviz-conventions.dot. Render: ./render-graphs.js ../some-skill.

The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills.

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

REQUIRED BACKGROUND: The wukong-code:test-driven-development skill explains why this matters. Same principles apply to documentation.

Testing and Bulletproofing

Discipline skills need pressure scenarios + rationalization counters. Technique/pattern/reference skills need application/retrieval tests.

Match form to failure: rule-skip → prohibition + rationalization table; wrong shape → positive recipe; omitted field → REQUIRED slot; conditional → observable predicate.

Full tables, bulletproofing toolkit, RED-GREEN-REFACTOR detail, micro-tests: skills/writing-skills/references/testing-and-bulletproofing.md

Testing methodology (pressure scenarios): testing-skills-with-subagents.md

Persuasion research: persuasion-principles.md

Anti-patterns (narrative examples, multi-language dilution, etc.): skills/writing-skills/references/anti-patterns.md

STOP: Before Moving to Next Skill

After writing ANY skill, you MUST STOP and complete the deployment process.

Do NOT:

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

The deployment checklist below is MANDATORY for EACH skill.

Deploying untested skills = deploying untested code. It's a violation of quality standards.

Skill Creation Checklist (TDD Adapted)

IMPORTANT: Create a todo for EACH checklist item below.

RED Phase - Write Failing Test:

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

GREEN Phase - Write Minimal Skill:

• Name uses only letters, numbers, hyphens (no parentheses/special chars)
• YAML frontmatter with required name and description fields (max 1024 chars; see spec)
• Description starts with "Use when..." and includes specific triggers/symptoms
• Description written in third person
• Keywords throughout for search (errors, symptoms, tools)
• Clear overview with core principle
• Address specific baseline failures identified in RED
• Guidance form matches the failure type (see testing-and-bulletproofing.md — Match the Form)
• For behavior-shaping guidance: wording micro-tested against a no-guidance control (5+ reps, every flagged match read manually) — N/A for pure reference skills
• Code inline OR link to separate file
• One excellent example (not multi-language)
• Run scenarios WITH skill - verify agents now comply

REFACTOR Phase - Close Loopholes:

• 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

Quality Checks:

• Small flowchart only if decision non-obvious
• Quick reference table
• Common mistakes section
• No narrative storytelling
• Supporting files only for tools or heavy reference

Deployment:

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

Discovery Workflow

How future agents find your skill — searchable terms early: skills/writing-skills/references/discovery-workflow.md

The Bottom Line

Creating skills IS TDD for process documentation.

Same Iron Law: No skill without failing test first. Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes). Same benefits: Better quality, fewer surprises, bulletproof results.

If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.