writing-skills

name	writing-skills
version	1.0.0
description	Use when creating new skills, editing existing skills, or verifying skills work before deployment
dependencies	{"@skill-module-example/test-driven-development":"^1.0.0"}

Writing Skills

Overview

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

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.

What is a Skill?

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

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

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

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 AGENTS.md)

Skill Types

• Technique: Concrete method with steps to follow
• Pattern: Way of thinking about problems
• Reference: API docs, syntax guides, tool documentation

Directory Structure

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

SKILL.md Structure

Frontmatter (YAML):

• name: Use letters, numbers, and hyphens only
• version: Semantic version
• description: Third-person, starts with "Use when..." — describes ONLY when to use, NOT what it does
• dependencies: Map of dependent skills with version ranges

Body sections:

• Overview with core principle
• When to Use (with symptoms and use cases)
• Core Pattern (for techniques/patterns)
• Quick Reference (table or bullets)
• Common Mistakes (what goes wrong + fixes)

The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills.

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test (Baseline)

Run pressure scenario WITHOUT the skill. Document exact behavior.

GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Run same scenarios WITH skill.

REFACTOR: Close Loopholes

Agent found new rationalization? Add explicit counter. Re-test until bulletproof.

Common Rationalizations for Skipping Testing

Excuse	Reality
"Skill is obviously clear"	Clear to you ≠ clear to other agents
"It's just a reference"	References can have gaps
"Testing is overkill"	Untested skills have issues. Always.
"I'll test if problems emerge"	Problems = agents can't use skill
"Too tedious to test"	Testing < debugging bad skill in production

Skill Creation Checklist

RED Phase:

• Create pressure scenarios
• Run scenarios WITHOUT skill - document baseline
• Identify patterns in rationalizations/failures

GREEN Phase:

• YAML frontmatter with required fields
• Description starts with "Use when..."
• Clear overview with core principle
• Address specific baseline failures
• Run scenarios WITH skill - verify compliance

REFACTOR Phase:

• Identify NEW rationalizations from testing
• Add explicit counters
• Build rationalization table
• Re-test until bulletproof

Deployment:

• Commit skill to git
• Consider contributing back via PR