writing-skills

Create and test agent skills using test-driven development with subagent pressure scenarios.

Updated Dec 19, 2024
One-click install
npx skills add https://github.com/DNepovim/yadm --skill writing-skills-dnepovim
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/DNepovim/yadm/tree/main/.claude/plugins/cache/claude-plugins-official/superpowers/5.0.6/skills/writing-skills
Command: npx skills add https://github.com/DNepovim/yadm --skill writing-skills-dnepovim

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Writing effective agent skills is hard because untested documentation often fails under real-world pressure—agents rationalize away rules, skip steps, or misinterpret guidance. This Skill applies test-driven development to skill authoring so you can verify skills actually change agent behavior before deployment. ## Core Features & Use Cases - TDD-Based Skill Authoring: Follows the RED-GREEN-REFACTOR cycle—run baseline pressure scenarios without the skill, document agent failures verbatim, then write minimal skills addressing those specific rationalizations. - Discovery Optimization (CSO): Provides concrete rules for writing descriptions, naming conventions, keyword coverage, and token efficiency so future agents can find your skill. - Bulletproofing Against Rationalization: Includes techniques like rationalization tables, red flags lists, and persuasion principles to close loopholes agents exploit under pressure. - Use Case: You want to create a new skill enforcing code review before commits. Run pressure scenarios (time pressure + sunk cost + authority) with a subagent lacking the skill, capture its excuses, write the skill countering those exact rationalizations, and re-test until the agent complies. ## Quick Start Ask the agent to help you create a new skill by first running a baseline pressure scenario with a subagent, then drafting the SKILL.md based on the observed failures.

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 for Claude agents?▼

Create a directory containing SKILL.md with YAML frontmatter defining name and description fields, followed by markdown sections for overview, when to use, core patterns, and common mistakes. Keep the description under 500 characters, start it with "Use when...", and never summarize the workflow in it.

How to test an agent skill before deploying it?▼

Run pressure scenarios with subagents that combine three or more pressures like time limits, sunk cost, and authority. First run without the skill to capture baseline failures verbatim, then verify the skill makes agents comply, and refactor to close any new rationalizations.

What makes a good skill description for discovery?▼

A good description starts with "Use when..." and lists only triggering conditions, symptoms, and situations in third person. Never summarize the skill's workflow, because agents may follow the description shortcut instead of reading the full skill body.

When should I not create a new skill?▼

Skip skill creation for one-off solutions, standard practices already well-documented, project-specific conventions that belong in CLAUDE.md, and mechanical constraints that can be enforced with regex or validation scripts instead of documentation.

Why do agents ignore skills under pressure?▼

Agents rationalize violations using excuses like sunk cost, time pressure, or "spirit versus letter" arguments. Counter this by adding explicit negations for each observed excuse, building rationalization tables, and stating that violating the letter violates the spirit.