WR

writing-skills

A TDD-based framework for authoring, testing, and documenting agent skills using a cycle of pressure scenarios and verification.

Install

mkdir -p .claude/skills/writing-skills && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/992" && unzip -o skill.zip -d .claude/skills/writing-skills && rm skill.zip

Installs to .claude/skills/writing-skills

Activation

This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.

Use when creating new skills, editing existing skills, or verifying skills work before deployment
97 chars✓ has a “when” trigger
Advanced

Key capabilities

  • →Apply red-green-refactor testing to documentation
  • →Define baseline behavioral failure scenarios
  • →Verify agent compliance with skill instructions
  • →Refine documentation to eliminate rationalization loopholes

How it works

It maps TDD principles to documentation by observing agent failures (red), applying docs (green), and refactoring documentation (refactor).

Inputs & outputs

You give it
Draft skill documentation and test scenarios
You get back
Validated skill compliant with agent behavioral testing

When to use writing-skills

  • →Creating new agent skills
  • →Refining existing skill documentation
  • →Testing agent behavior under pressure
  • →Verifying skills work before deployment

About this skill

Writing Skills

Overview

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

Personal skills live in your runtime's skills directory (~/.claude/skills/ on Claude Code) — see codex-tools.md or gemini-tools.md for the path on those runtimes. Codex, Copilot CLI, and Gemini CLI all also recognize ~/.agents/skills/ as a cross-runtime alias.

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 references/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 ConceptSkill Creation
Test casePressure scenario with subagent
Production codeSkill document (SKILL.md)
Test fails (RED)Agent violates rule without skill (baseline)
Test passes (GREEN)Agent complies with skill present
RefactorClose loopholes while maintaining compliance
Write test firstRun baseline scenario BEFORE writing skill
Watch it failDocument exact rationalizations agent uses
Minimal codeWrite skill addressing those specific violations
Watch it passVerify agent now complies
Refactor cycleFind 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 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 (office docs)

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:

  1. Heavy reference (100+ lines) - API docs, comprehensive syntax
  2. Reusable tools - Scripts, utilities, templates

Keep inline:

  • Principles and concepts
  • Code patterns (< 50 lines)
  • Everything else

Writing SKILL.md

A skill's description says only when to use it: triggering conditions and symptoms, starting with "Use when...". It never summarizes the skill's workflow, because an agent that reads a workflow summary follows it instead of reading the skill.

When you write or change a skill's frontmatter, name or description, or need to cut its size, read references/discovery.md: the SKILL.md template, description and keyword guidance, naming, token budgets, and cross-referencing other skills.

Flowcharts

When you add or change a flowchart in a skill, read references/flowcharts.md first: when a flowchart earns its place, the graphviz conventions, and how to render one.

Code Examples

One excellent example beats many mediocre ones

Choose most relevant language:

  • Testing techniques → TypeScript/JavaScript
  • System debugging → Shell/Python
  • Data processing → Python

Good example:

  • Complete and runnable
  • Well-commented explaining WHY
  • From real scenario
  • Shows pattern clearly
  • Ready to adapt (not generic template)

Don't:

  • Implement in 5+ languages
  • Create fill-in-the-blank templates
  • Write contrived examples

You're good at porting - one great example is enough.

File Organization

Self-Contained Skill

defense-in-depth/
  SKILL.md    # Everything inline

When: All content fits, no heavy reference needed

Skill with Reusable Tool

condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

When: Tool is reusable code, not just narrative

Skill with Heavy Reference

pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

When: Reference material too large for inline

Invoke bundled scripts through their interpreter in the prose (bash scripts/tool.sh, node scripts/tool.js), never by bare path: some harness plugin packagers strip executable bits, and a bare scripts/tool.sh fails there with Permission denied.

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 superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation.

Testing All Skill Types

Different skill types need different test approaches:

Discipline-Enforcing Skills (rules/requirements)

Examples: TDD, verification-before-completion, designing-before-coding

Test with:

  • Academic questions: Do they understand the rules?
  • Pressure scenarios: Do they comply under stress?
  • Multiple pressures combined: time + sunk cost + exhaustion
  • Identify rationalizations and add explicit counters

Success criteria: Agent follows rule under maximum pressure

Technique Skills (how-to guides)

Examples: condition-based-waiting, root-cause-tracing, defensive-programming

Test with:

  • Application scenarios: Can they apply the technique correctly?
  • Variation scenarios: Do they handle edge cases?
  • Missing information tests: Do instructions have gaps?

Success criteria: Agent successfully applies technique to new scenario

Pattern Skills (mental models)

Examples: reducing-complexity, information-hiding concepts

Test with:

  • Recognition scenarios: Do they recognize when pattern applies?
  • Application scenarios: Can they use the mental model?
  • Counter-examples: Do they know when NOT to apply?

Success criteria: Agent correctly identifies when/how to apply pattern

Reference Skills (documentation/APIs)

Examples: API documentation, command references, library guides

Test with:

  • Retrieval scenarios: Can they find the right information?
  • Application scenarios: Can they use what they found correctly?
  • Gap testing: Are common use cases covered?

Success criteria: Agent finds and correctly applies reference information

Common Rationalizations for Skipping Testing

ExcuseReality
"Skill is obviously clear"Clear to you ≠ clear to other agents. Test it.
"It's just a reference"References can have gaps, unclear sections. Test retrieval.
"Testing is overkill"Untested skills have issues. Always. 15 min testing saves hours.
"I'll test if problems emerge"Problems = agents can't use skill. Test BEFORE deploying.
"Too tedious to test"Testing is less tedious than debugging bad skill in production.
"I'm confident it's good"Overconfidence guarantees issues. Test anyway.
"Academic review is enough"Reading ≠ using. Test application scenarios.
"No time to test"Deploying untested skill wastes more time fixing it later.

All of these mean: Test before deploying. No exceptions.

Match the Form to the Failure

Before writing guidance, classify the baseline failure. The form that bulletproofs one failure type measurably backfires on another.

Baseline failureRight formWrong form
Skips/violates a rule under pressure (knows better, does it anyway)Prohibition + rationalization table + red flags (see references/bulletproofing.md)Soft guidance ("prefer...", "consider...")
Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec)Positive recipe or contract: state what the output IS — its parts, in orderProhibition list ("don't restate", "never narrate")
Omits a required element from something they already produceStructural: REQUIRED field or slot in the template they fill inProse reminders near the template
Behavior should depend on a conditionConditional keyed to an observable predicate ("if the brief exists, reference it")Unconditional rule + exemption clauses

Why prohibitions backfire on shaping problems: under a competing incentive ("make the prompt self-contained"), agents negotiate with "don't X". In head-to-head wording tests on dispatch-prompt guidance, the prohibition arm produced clearly more of the unwante


Content truncated.

When not to use it

  • →Direct coding tasks not involving skill authoring
  • →Verifying logic that has not been documented

Prerequisites

superpowers:test-driven-development

Limitations

  • →High overhead compared to traditional documentation writing
  • →Requires proficiency in TDD methodology

How it compares

This treats process documentation as software code requiring unit testing and verification.

Compared to similar skills

writing-skills side by side with the closest alternatives in the catalog.

SkillInstallsUpdatedSafetyDifficulty
writing-skills (this skill)48moReviewAdvanced
criteria-generator08moNo flagsIntermediate
skill-creator1287moReviewAdvanced
skill-development171yReviewIntermediate

Try saying

Example prompts that trigger this skill in your AI assistant.

You might also like

criteria-generator

openzigs

Converts ingested requirements into structured Given/When/Then acceptance criteria using RAG-powered LLM generation. Auto-tags criteria, assigns confidence scores, and maintains traceability links.

00

skill-creator

anthropics

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

128200

skill-development

anthropics

This skill should be used when the user wants to "create a skill", "add a skill to plugin", "write a new skill", "improve skill description", "organize skill content", or needs guidance on skill structure, progressive disclosure, or skill development best practices for Claude Code plugins.

17145

svelte-expert

Raudbjorn

Expert Svelte/SvelteKit development assistant for building components, utilities, and applications. Use when creating Svelte components, SvelteKit applications, implementing reactive patterns, handling state management, working with stores, transitions, animations, or any Svelte/SvelteKit development task. Includes comprehensive documentation access, code validation with svelte-autofixer, and playground link generation.

11107

home-assistant-integration-knowledge

home-assistant

Everything you need to know to build, test and review Home Assistant Integrations. If you're looking at an integration, you must use this as your primary reference.

863

agentic-eval

github

Patterns and techniques for evaluating and improving AI agent outputs. Use this skill when: - Implementing self-critique and reflection loops - Building evaluator-optimizer pipelines for quality-critical generation - Creating test-driven code refinement workflows - Designing rubric-based or LLM-as-judge evaluation systems - Adding iterative improvement to agent outputs (code, reports, analysis) - Measuring and improving agent response quality

642

Search skills

Search the agent skills registry