# Writing Skills > Use when creating new skills, editing existing skills, or verifying skills work before deployment - Skill: `tomevault-io/writing-skills-5` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/writing-skills-5` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/writing-skills-5/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/writing-skills-5 --- # Writing Skills ## Overview **Writing skills IS Test-Driven Development applied to process documentation.** **Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.agents/skills/` for Codex)** 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 superpowers: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. ## Quick Start 1. **RED:** Run baseline scenario WITHOUT skill - watch agent fail 2. **GREEN:** Write minimal skill addressing specific failures 3. **REFACTOR:** Close loopholes, re-test until bulletproof **The Iron Law:** `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. ## Core Concepts ### What is a Skill? A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude 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 | ### Skill Types | Type | Description | Example | | ------------- | ------------------------------ | ------------------------------------------- | | **Technique** | Concrete method with steps | condition-based-waiting, root-cause-tracing | | **Pattern** | Way of thinking about problems | flatten-with-flags, test-invariants | | **Reference** | API docs, syntax guides | office docs, library documentation | ### 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 CLAUDE.md) - Mechanical constraints (automate enforceable rules with regex/validation) ## 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? This is "watch the test fail" - you must see what agents naturally do before writing the skill. ### 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 methodology:** See @testing-skills-with-subagents.md for the complete testing methodology: - How to write pressure scenarios - Pressure types (time, sunk cost, authority, exhaustion) - Plugging holes systematically - Meta-testing techniques ## Detailed Guides ### [Prompt Engineering & CSO](references/guides/prompt-engineering.md) Claude Search Optimization, description writing, keyword coverage, naming conventions, token efficiency ### [Documentation Standards](references/guides/documentation-standards.md) SKILL.md structure, flowcharts, code examples, file organization, anti-patterns ### [Skill Templates](references/examples/skill-templates.md) SKILL.md templates, TDD mapping, skill types, discovery workflow ### [Skill Review Checklist](references/checklists/skill-review.md) RED/GREEN/REFACTOR phases, quality checks, bulletproofing against rationalization, testing by skill type ## 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 in [references/checklists/skill-review.md](references/checklists/skill-review.md) is MANDATORY for EACH skill.** Deploying untested skills = deploying untested code. It's a violation of quality standards. ## Discovery Workflow How future Claude finds your skill: 1. **Encounters problem** ("tests are flaky") 2. **Finds SKILL** (description matches) 3. **Scans overview** (is this relevant?) 4. **Reads patterns** (quick reference table) 5. **Loads example** (only when implementing) **Optimize for this flow** - put searchable terms early and often. ## 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. --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/ollieb89) — claim your Tome and manage your conversions.