writing-skills

Overview

What the writing-skills skill does

The writing-skills skill is a meta-skill for people who author, refine, and test other skills for agents like Claude. It adapts classic Test-Driven Development (TDD) to process documentation, so your skills are:

• Grounded in real pressure scenarios
• Verified against actual agent failures
• Refined to close loopholes and resist rationalization

You use writing-skills to design skills that agents can discover, follow, and keep following even under time pressure, sunk-cost bias, or conflicting incentives.

Who writing-skills is for

Use the writing-skills skill if you are:

• A developer creating skills for Claude or similar agents
• A team lead standardizing workflows in ~/.claude/skills or ~/.agents/skills/
• A documentation owner responsible for skills that must be followed, not just read
• A tester validating that skills actually change agent behavior before rollout

It is not focused on generic writing style. It is specifically about authoring effective, testable agent skills.

Problems this skill helps you solve

writing-skills is designed for situations where:

• Agents ignore or partially follow your skills under pressure
• You are unsure whether a new skill meaningfully changes behavior
• You need a repeatable way to test skills with subagents before deployment
• You want to align with Anthropic skill authoring best practices without guessing
• You need to visualize and communicate complex skill workflows using Graphviz

If you have skills that act more like one-off stories or notes, writing-skills helps you reshape them into reusable, testable reference guides.

When writing-skills is and is not a good fit

Good fit:

• Skills that enforce discipline (TDD, verification, review checklists)
• Skills that have a real compliance cost (time, rework, delayed shipping)
• Skills that agents may try to bypass ("just this once")
• Skills where you want measurable improvement in compliance rates

Not a good fit:

• Pure reference skills (e.g., API syntax, basic language cheatsheets)
• Skills that intentionally have no rules to violate
• Lightweight notes where you do not need TDD-style testing or pressure scenarios

If you only need a quick, informal note for one conversation, you likely do not need writing-skills. If you want a skill that survives production pressure, you do.

How to Use

Installation and basic setup

To install the writing-skills skill into a skills-aware environment:

npx skills add https://github.com/obra/superpowers --skill writing-skills

This pulls the writing-skills skill from the obra/superpowers repository and registers it alongside your other skills.

Personal skills typically live in agent-specific directories, for example:

• ~/.claude/skills/ for Claude Code
• ~/.agents/skills/ for Codex or similar agents

Place or confirm the writing-skills directory under the relevant skills root so your agent can load SKILL.md and related files when needed.

Key files and folders in writing-skills

Once installed, open these files first to understand and apply the workflow:

• SKILL.md – Core skill definition and overview of writing-skills, including the TDD mapping for skills.
• anthropic-best-practices.md – Official-style guidance on writing concise, discoverable, and effective skills for Claude.
• testing-skills-with-subagents.md – Practical guide for building and running pressure scenarios and test campaigns.
• persuasion-principles.md – Evidence-based persuasion patterns to improve agent compliance with your skills.
• graphviz-conventions.dot – Conventions for representing skill workflows and processes as Graphviz diagrams.
• render-graphs.js – Helper script that extracts ```dot blocks from SKILL.md and renders them to SVG diagrams.
• examples/CLAUDE_MD_TESTING.md – A complete worked example of a test campaign for CLAUDE.md documentation variants.

These files combine to give you a full authoring + testing + visualization workflow for skills.

Core workflow: TDD for skills

writing-skills applies TDD concepts directly to skill authoring. The high-level loop is:

1. Write test cases (pressure scenarios)

   • Design realistic situations where an agent might rationalize skipping or bending your intended process.
   • Use subagents to run these scenarios and capture their behavior.

2. Run baseline tests and watch them fail

   • Execute scenarios without your new or updated skill loaded.
   • Capture where the agent fails: what they skip, rationalize, or misunderstand.

3. Write or refine the skill

   • Draft or update SKILL.md and any supporting files to address the specific failures you observed.
   • Use concise, imperative language that fits the context window constraints.

4. Run tests again with the skill loaded

   • Re-run the same scenarios, this time with your skill active.
   • Verify that the agent now discovers, announces, and follows the skill.

5. Refactor to close loopholes

   • Identify remaining rationalizations or partial compliance.
   • Apply persuasion principles (authority, commitment, etc.) to strengthen adherence.
   • Trim unnecessary tokens to keep the skill concise.

This loop mirrors RED → GREEN → REFACTOR in classic TDD, but applied to documentation and process enforcement instead of code.

Using anthropic-best-practices.md for better skills

The anthropic-best-practices.md file provides guidance specific to the Claude ecosystem, including:

• Why concise skills improve context usage and model performance
• How and when Claude loads SKILL.md and other files into the context window
• How to write skill sections that justify their token cost

You can use this file as a checklist when reviewing your own skills:

• Remove explanations Claude already knows
• Focus on actionable patterns, rules, and workflows
• Structure skills so the most important instructions appear early and clearly

Integrating these practices with the TDD loop from writing-skills helps ensure your skills are both discoverable and efficient.

Testing skills with subagents

The testing-skills-with-subagents.md file extends the TDD approach with a concrete testing method:

• Design scenarios that mimic real production pressure (time, sunk cost, speed vs quality).
• Run them with subagents that represent how your main agent would behave.
• Capture failures and rationalizations in structured formats.

This is particularly useful for skills that:

• Enforce time-consuming best practices (e.g., writing tests first)
• Compete with short-term goals (e.g., shipping faster vs. verifying thoroughly)
• Need to hold up when humans explicitly request shortcuts

By following the testing patterns in this file, you can verify skills under pressure before they reach end users.

Applying persuasion principles in skill design

persuasion-principles.md summarizes psychological principles that also affect LLM behavior, such as:

• Authority – Clear, non-negotiable language for safety-critical rules
• Commitment – Requiring agents to announce when they use a skill and stick to a chosen path
• Scarcity and others – Used carefully to prioritize critical practices

In practice, you can:

• Use more imperative wording for non-optional steps
• Ask the agent to explicitly state: "I am using [Skill Name] now" when a skill is in play
• Design checklists that force completion rather than passive reading

The goal is not manipulation; it is to make sure critical practices are followed consistently.

Visualizing skill flows with Graphviz

Complex skills often benefit from a visual representation. writing-skills includes:

• graphviz-conventions.dot – Suggested structure and style for diagrams
• render-graphs.js – A Node.js script that extracts ```dot blocks from SKILL.md and turns them into SVG files.

Basic usage for the renderer:

./render-graphs.js path/to/your/skill
# or
./render-graphs.js path/to/your/skill --combine

This helps you:

• Communicate a skill’s flow to human collaborators
• Spot gaps or loops in your process design
• Keep documentation and visuals in sync by embedding diagrams as ```dot code blocks in SKILL.md.

Adapting writing-skills to your environment

The repository describes patterns that you should adapt, not copy blindly. When integrating writing-skills into your own workflow:

• Keep the TDD loop, but adjust scenario formats to your tools
• Use your own directory structure if needed, while preserving clear skill boundaries
• Integrate test campaigns into your existing CI, review, or release processes

The goal is a repeatable, test-driven authoring workflow that fits your team and infrastructure.

FAQ

When should I load the writing-skills skill?

Use writing-skills whenever you are:

• Creating a new skill that will live under ~/.claude/skills or similar directories
• Editing an existing skill that has started to drift or be ignored
• Preparing a skill for deployment to teammates or production use
• Designing or running a test campaign for skills with subagents

If you are just experimenting in a single ephemeral session, you may not need the full writing-skills workflow.

Do I need to understand TDD before using writing-skills?

Yes. The skill explicitly requires familiarity with superpowers:test-driven-development. writing-skills assumes you already know the RED → GREEN → REFACTOR cycle and then applies it to documentation:

• RED: Run scenarios without the skill, capture failures
• GREEN: Add or refine the skill to make those scenarios pass
• REFACTOR: Improve clarity, close loopholes, and reduce token cost

If TDD is new to you, load and study the TDD-related skill first.

How does writing-skills help with Claude-specific behavior?

writing-skills is designed for environments like Claude, and the repository includes anthropic-best-practices.md with guidance aligned to Anthropic’s documentation. Together, they help you:

• Write skills that Claude can discover reliably
• Respect the context window and token budget
• Structure SKILL files so Claude loads and uses them effectively

This makes writing-skills especially useful if you are building out a Claude skill library.

Can I use writing-skills for non-technical or non-code skills?

Yes, as long as the skill describes a repeatable process that can be tested via scenarios. Examples include:

• Incident response checklists
• Code review workflows
• Documentation review or approval processes

The key is that the process has:

• Clear rules agents can follow or violate
• Real consequences when steps are skipped
• Scenarios where you can meaningfully test compliance

Purely descriptive or narrative content is not a good match.

What is the examples/CLAUDE_MD_TESTING.md file for?

examples/CLAUDE_MD_TESTING.md is a full worked example that shows how to:

• Design realistic scenarios (time pressure, sunk cost, authority vs speed)
• Run them against different CLAUDE.md documentation variants
• Compare how well each variant leads to skill discovery and usage

Use it as a template when designing your own skill test campaigns.

How is a skill different from a story or case study?

In the writing-skills model:

• A skill is a reusable reference guide that encodes proven patterns, tools, or workflows.
• A story or case study describes how you solved one specific problem once.

writing-skills helps you move from one-off stories to generalized, testable skills that future agents can find and apply in new situations.

What if my skill is long—does that matter?

Length matters because of the context window. anthropic-best-practices.md explains why concise skills perform better:

• Only the metadata is loaded up front, but once SKILL.md is read, every token competes with conversation history.
• You should constantly ask whether each section earns its place.

writing-skills encourages you to:

• Trim redundant explanations
• Move examples to supporting files if needed
• Focus SKILL.md on the core process and rules that make tests pass

How do I know writing-skills is working?

You will see impact when:

• Skills that used to be ignored under pressure are now followed
• New skills come with explicit scenarios and tests, not just text
• You can point to before/after behavior for agents across specific scenarios

If you cannot show a difference between behavior with and without a skill, revisit the TDD loop and the persuasion and testing guides provided by writing-skills.