sp-writing-skills

name	sp-writing-skills
description	Use when creating new skills, editing existing skills, or verifying skills work before deployment. Apply TDD cycle: baseline test first, write skill second, refactor to close loopholes.
tags	["meta","skills","tdd","documentation","workflow"]
version	1.0.0
risk	guarded
triggers	["create a new skill","write a skill","edit a skill","deploy a skill","update a skill","add a skill","skill authoring","writing skills"]
requirements	{"cli":[],"env":[]}
upstream_ref	skills/writing-skills/SKILL.md
author	AlphaComposite
license	MIT
dependencies	["sp-test-driven-development"]

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.

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

What is a Skill?

A skill is a reference guide for proven techniques, patterns, or tools. Skills help future agent 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

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

When to Create a Skill

Create when:

• Technique wasn't intuitively obvious
• 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 project config)
• Mechanical constraints (if enforceable with validation, automate it — save documentation for judgment calls)

Skill Types

Technique

Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)

Pattern

Way of thinking about problems (flatten-with-flags, test-invariants)

Reference

API docs, syntax guides, tool documentation

SKILL.md Structure

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

Frontmatter (YAML): Include all required schema fields (name, description, tags, version, risk, triggers, requirements, upstream_ref). Keep description under 500 characters. Start with "Use when..." for triggering conditions only — never summarize the skill's workflow.

Body sections:

• Overview (core principle, 1-2 sentences)
• When to Use (conditions/symptoms, when NOT to use)
• Core Pattern (before/after comparison for techniques)
• Quick Reference (table or bullets)
• Implementation (inline code or link)
• Common Mistakes

Agent Optimization (AO)

Critical for discovery: Future agents need to FIND your skill via description matching.

Description Field Rules

CRITICAL: Description = When to Use, NOT What the Skill Does

The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow.

Why this matters: When a description summarizes the workflow, agents may follow the description summary instead of reading the full skill content — skipping the actual instructions.

# ❌ BAD: Summarizes workflow
description: Use when executing plans - dispatches subagent per task with code review between tasks

# ✅ GOOD: Triggering conditions only
description: Use when executing implementation plans with independent tasks in the current session

• Start with "Use when..."
• Use concrete triggers, symptoms, and situations
• Describe the problem, not language-specific symptoms
• Write in third person
• NEVER summarize the skill's process or workflow

Keyword Coverage

Use words agents would search for:

• Error messages and symptoms
• Synonyms for the problem
• Tool names and commands

Token Efficiency (Critical)

Frequently-referenced skills load into every conversation. Every token counts.

Target word counts:

• Getting-started/workflow skills: <150 words each
• Frequently-loaded skills: <200 words total
• Other skills: <500 words

Techniques:

• Move flag details to --help references, not inline docs
• Cross-reference other skills instead of repeating their content
• One excellent example beats many mediocre ones

The Iron Law (Same as TDD)

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills. No exceptions:

• Not for "simple additions"
• Not for "just adding a section"
• Not for "documentation updates"

Write skill before testing? Delete it. Start over.

RED-GREEN-REFACTOR for Skills

RED: Write Failing Test (Baseline)

Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:

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

GREEN: Write Minimal Skill

Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases. Run same scenarios WITH skill — agent should now comply.

REFACTOR: Close Loopholes

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

Testing by Skill Type

Type	Test Approach	Success Criteria
Discipline (rules/requirements)	Pressure scenarios + combined pressures	Follows rule under maximum pressure
Technique (how-to)	Application + variation + missing-info	Correctly applies to new scenario
Pattern (mental models)	Recognition + application + counter-examples	Identifies when/how to apply
Reference (API/docs)	Retrieval + application + gap testing	Finds and correctly applies info

Bulletproofing Against Rationalization

Close Every Loophole Explicitly

# ❌ BAD
Write code before test? Delete it.

# ✅ GOOD
Write code before test? Delete it. Start over.
No exceptions:
- Don't keep it as "reference"
- Don't "adapt" it while writing tests
- Delete means delete

Build Rationalization Table

Capture rationalizations from baseline testing:

Excuse	Reality
"Skill is obviously clear"	Clear to you ≠ clear to other agents. Test it.
"It's just a reference"	References can have gaps. Test retrieval.
"Testing is overkill"	Untested skills always have issues. 15 min testing saves hours.
"No time to test"	Deploying untested skill wastes more time fixing it later.

Create Red Flags List

## Red Flags — STOP and Start Over
- Wrote skill before running baseline
- "I'll test if problems emerge"
- "Academic review is enough"
All of these mean: Delete skill. Start over with RED phase.

Common Mistakes

• Narrative instead of reference: Don't write "In session X, we found..." — write reusable patterns
• Multi-language examples: One excellent example beats five mediocre translations
• Flowcharts for linear steps: Use numbered lists; flowcharts only for non-obvious decision points
• Generic labels: helper1, step3 have no semantic meaning — name things
• Batching without testing: Never create multiple skills without testing each one first

Skill Creation Checklist

RED Phase:

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

GREEN Phase:

• All required frontmatter fields present
• Description starts with "Use when..." — triggering conditions only
• Keywords throughout for search
• Addresses specific baseline failures identified in RED
• Run WITH skill — verify agents now comply

REFACTOR Phase:

• Identify new rationalizations from testing
• Add explicit counters for discipline skills
• Build rationalization table
• Re-test until bulletproof

Deployment:

• Commit to git and push

STOP: Before Moving to Next Skill

After writing ANY skill, 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"

Deploying untested skills = deploying untested code.