Index of every page on this site: llms.txt
All skills
obra avatar

/writing-skills

@22f0b46 official
by Jesse Vincentobra/superpowers312k stars
27,751
Run it yourself

Use when creating new skills, editing existing skills, or verifying skills work before deployment

Use this Skill: https://skilld.dev/gh/obra/superpowers/writing-skills

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesbulletproofing.md

≈645 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Bulletproofing Skills Against Rationalization

Part of superpowers:writing-skills. Use it when the baseline failure is a discipline failure: the agent knows the rule and skips it under pressure.

Bulletproofing Skills Against Rationalization

Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.

Scope: this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead.

Psychology note: Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md in this directory for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.

Close Every Loophole Explicitly

Don't just state the rule - forbid specific workarounds:

<Bad> ```markdown Write code before test? Delete it. ``` </Bad><Good> ```markdown Write code before test? Delete it. Start over.

No exceptions:

  • Don't keep it as "reference"
  • Don't "adapt" it while writing tests
  • Don't look at it
  • Delete means delete
</Good>

### Address "Spirit vs Letter" Arguments

Add foundational principle early:

```markdown
**Violating the letter of the rules is violating the spirit of the rules.**

This cuts off entire class of "I'm following the spirit" rationalizations.

Build Rationalization Table

Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:

| Excuse | Reality |
|--------|---------|
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
| "I'll test after" | Tests passing immediately prove nothing. |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |

Create Red Flags List

Make it easy for agents to self-check when rationalizing:

## Red Flags - STOP and Start Over

- Code before test
- "I already manually tested it"
- "Tests after achieve the same purpose"
- "It's about spirit not ritual"
- "This is different because..."

**All of these mean: Delete code. Start over with TDD.**

Update SDO for Violation Symptoms

Add to description: symptoms of when you're ABOUT to violate the rule:

description: use when implementing any feature or bugfix, before writing implementation code

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning17d5 checks · Risk MEDIUM
  • Gen Agent Trust Hub17d

    This skill provides a comprehensive framework for creating and testing AI agent skills using a Test-Driven Development (TDD) approach. It includes utilities for rendering Graphviz diagrams and methodologies for ensuring agent compliance through the use of psychological persuasion principles. Security considerations include the dynamic execution of external commands and the use of instructional patterns designed to override agent reasoning processes.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer8mo

    1/7 files flagged

  • ZeroLeaks6mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 22f0b46. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 5 days ago.

Activeupdated 3 weeks ago
  • Documentation
  • skills
  • tdd
  • test-driven-development
  • writing
  • agents
  • claude
  • patterns
  • reference
  • methodology

README badge

README badge for obra/superpowers/writing-skills

Guides skill authors through test-driven development applied to documentation: write baseline tests showing agents fail without the skill, write the skill to make tests pass, then refactor to close loopholes. Covers skill structure, discovery optimization, and token efficiency for frequently-loaded skills.

Generated from the current SKILL.md.

What's the difference between this skill and standard documentation best practices?
This skill applies test-driven development to skill authoring—you write pressure test scenarios with subagents first, watch agents fail without the skill (baseline), then write the skill to make tests pass. It's documentation built on proven compliance, not best guesses.
Do I need to read superpowers:test-driven-development before using this skill?
Yes. This skill adapts the RED-GREEN-REFACTOR cycle to documentation, so you must understand the TDD fundamentals first.
Should I create a skill for every technique or pattern I discover?
No. Create skills only when a technique wasn't intuitively obvious to you, you'd reference it across projects, and others would benefit. Don't create skills for one-off solutions, standard practices already well-documented, or project-specific conventions (use CLAUDE.md instead).
Why does the description field matter so much?
The description tells Claude whether to load the skill for a task. If you summarize the skill's workflow in the description, Claude may follow that short summary instead of reading the full skill content. Keep descriptions focused only on triggering conditions.
How long should a skill be?
Getting-started workflows should be under 150 words; frequently-loaded skills under 200 words total; other skills under 500 words. Use cross-references and tool help flags to avoid repeating details that load into every conversation.

Generated from the current SKILL.md. These answers refresh after source changes.