Writing Skills

When to use

• Creating a new skill
• Editing an existing skill
• Skill needs to resist rationalization under pressure

Skip when

• Writing pure reference skill (API docs) → no rules to test
• Skill has no compliance costs → no rationalization risk

Related

Complementary: ring:testing-skills-with-subagents

Writing skills IS TDD applied to process documentation.

Same Iron Law: No skill without failing test first. Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).

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

What is a Skill?

A reusable reference guide for proven techniques, patterns, or tools. Not a narrative about how you solved something once.

Create when: technique wasn't obvious, you'd reference it again, applies broadly. Skip when: one-off solution, project-specific convention (put in CLAUDE.md).

Skill Types

SKILL.md Structure

---
name: ring:skill-name-with-hyphens
description: Use when [triggers/symptoms] — [what it does, third person]
---
# Skill Name
## Overview (1-2 sentences)
## When to Use (symptoms + skip conditions)
## Core Pattern (before/after examples)
## Quick Reference (table for scanning)
## Implementation (inline or linked)
## Common Mistakes

Frontmatter rules: Only name and description. Max 1024 chars total. name: letters, numbers, hyphens only. description: third-person, starts "Use when...", <500 chars if possible.

Agent Search Optimization (ASO)

Agents read description to decide which skills to load. Make it answer: "Should I read this skill right now?"

• Use concrete triggers and symptoms (problem-focused, not language-specific)
• Use keywords agents would search: error messages, symptoms, tool names
• Active voice, verb-first names: creating-skills not skill-creation
• Reference skills by name only: ring:test-driven-development, no @ links (force-loads context)

Token Efficiency

RED-GREEN-REFACTOR for Skills

REQUIRED SUB-SKILL: Use ring:testing-skills-with-subagents for pressure scenarios and hole-plugging.

The Iron Law

NO SKILL WITHOUT A FAILING TEST FIRST

Applies to new skills AND edits. Delete untested skills and start over. No exceptions.

Bulletproofing Against Rationalization

For discipline-enforcing skills:

1. Forbid specific workarounds explicitly — don't just state the rule, list prohibited alternatives
2. Address "spirit vs letter" early: "Violating the letter is violating the spirit."
3. Build rationalization table from baseline testing — capture every excuse agents make
4. Create Red Flags list — make self-checking easy

## Red Flags — STOP
- [symptom 1]
- [symptom 2]
All of these mean: [required action].

Skill Creation Checklist

STOP after each skill — do NOT batch-create without testing each.

File Organization