writing-skills

Create and test agent skills using a TDD-based RED-GREEN-REFACTOR documentation workflow.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/kxnzee/multi-repo-specs --skill writing-skills-kxnzee
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/kxnzee/multi-repo-specs/tree/main/extensions/superpowers/skills/writing-skills
Command: npx skills add https://github.com/kxnzee/multi-repo-specs --skill writing-skills-kxnzee

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing skill documentation for AI agents without testing it first leads to skills that agents ignore, misinterpret, or rationalize away under pressure. This Skill applies Test-Driven Development to skill authoring so every skill is verified against real agent behavior before deployment. ## Core Features & Use Cases - TDD-based skill authoring: Run baseline pressure scenarios with subagents (RED), write the skill addressing observed failures (GREEN), then close rationalization loopholes (REFACTOR). - Discovery optimization: Guidance on writing description frontmatter with triggering conditions only, keyword coverage, token efficiency, and naming conventions so agents actually find the skill. - Testing methodology: Pressure scenario design (time, sunk cost, authority, exhaustion), rationalization tables, red flag lists, and micro-testing of wording against no-guidance controls. - Use Case: Before publishing a new discipline-enforcing skill like a mandatory code-review rule, run combined-pressure scenarios without the skill, document the agent's verbatim excuses, then write counters for each one and re-test until the agent complies. ## Quick Start Ask the agent to create a new skill following the writing-skills TDD process, starting with a baseline pressure scenario before writing any SKILL.md content.

Frequently Asked Questions about writing-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a SKILL.md file that agents will actually follow?▼

Test it first with pressure scenarios run without the skill, document the agent's exact rationalizations, then write the skill addressing those specific failures. Re-test with the skill present and close any new loopholes until the agent complies under maximum pressure.

What should go in a skill description frontmatter field?▼

Write only triggering conditions starting with "Use when...", in third person, with concrete symptoms and keywords. Never summarize the skill's workflow, because agents may follow the description shortcut instead of reading the full skill body.

How do I test a skill before deploying it?▼

Run realistic scenarios combining three or more pressures such as time limits, sunk cost, and authority, first without the skill to capture baseline failures, then with the skill to verify compliance. Micro-test wording variants with 5+ fresh-context samples against a no-guidance control.

When should I not create a new skill?▼

Skip skill creation for one-off solutions, project-specific conventions that belong in an instructions file, well-documented standard practices, and mechanical constraints that can be enforced with validation or automation instead of documentation.

Why do agents ignore or bypass skill rules under pressure?▼

Agents rationalize violations with excuses like sunk cost or spirit-versus-letter arguments. Counter this with explicit loophole closures, rationalization tables, red flag lists, and foundational principles stated early in the skill.