writing-skills

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

Updated Jul 30, 2026
One-click install
npx skills add https://github.com/johsquaree/claude-basic-docs --skill writing-skills-johsquaree
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/johsquaree/claude-basic-docs/tree/main/.claude/skills/writing-skills
Command: npx skills add https://github.com/johsquaree/claude-basic-docs --skill writing-skills-johsquaree

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Untested skill documentation often fails in practice because agents rationalize away rules under time pressure, sunk cost, or authority. This Skill applies test-driven development to skill authoring so new or edited skills are 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). - Skill Discovery Optimization (SDO): Guidance for writing name and description frontmatter with triggering conditions, keyword coverage, and token efficiency so agents find the skill. - Testing methodology references: Includes detailed guides for pressure-scenario testing, persuasion principles for discipline-enforcing skills, and Anthropic's official authoring best practices. - Use Case: Before publishing a new TDD-enforcement skill, run a scenario where an agent has 200 lines of untested code and a dinner deadline, document its rationalizations, then write counters until the agent complies under maximum pressure. ## 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 documentation.

Frequently Asked Questions about writing-skills

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

FAQPage Schema
How do I test a new agent skill before deploying it?

Run pressure scenarios with subagents without the skill first to capture baseline failures and verbatim rationalizations. Then write the skill addressing those failures, re-test with the skill present, and iterate to close loopholes until agents comply under combined pressures like time, sunk cost, and exhaustion.

What makes a good skill description for discovery?

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

What is the RED-GREEN-REFACTOR cycle for skills?

RED means running a pressure scenario without the skill and watching the agent fail. GREEN means writing the minimal skill that makes the agent comply. REFACTOR means adding explicit counters to new rationalizations and re-testing until the skill is bulletproof.

When should I not create a skill?

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

Why do agents ignore skills under pressure?

Agents rationalize violations with excuses like sunk cost, authority overrides, or spirit-versus-letter arguments. Counter this with explicit negations of each loophole, rationalization tables, red-flag lists, and persuasion principles such as authority and commitment.