writing-skills

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

Updated Jan 2, 2025
One-click install
npx skills add https://github.com/mcinnisd/gymbro --skill writing-skills-mcinnisd
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/mcinnisd/gymbro/tree/main/.agents/skills/writing-skills
Command: npx skills add https://github.com/mcinnisd/gymbro --skill writing-skills-mcinnisd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing effective agent skills is hard because untested documentation often fails under real-world pressure, and authors cannot know if a skill actually changes agent behavior without observing baseline failures first. ## Core Features & Use Cases - TDD-Based Skill Authoring: Applies the RED-GREEN-REFACTOR cycle to documentation by running baseline pressure scenarios with subagents before writing any skill content. - Skill Discovery Optimization: Provides rules for writing descriptions, keywords, and naming so future agents can find and trigger the right skill. - Rationalization Bulletproofing: Supplies rationalization tables, red flag lists, and persuasion principles to close loopholes agents exploit under time, sunk-cost, or authority pressure. - Use Case: When creating a new discipline-enforcing skill like mandatory code review, run pressure scenarios without the skill, document the agent's excuses verbatim, then write minimal guidance that counters those exact rationalizations and re-test until compliant. ## Quick Start Ask the agent to create a new skill following the writing-skills TDD process, starting with a baseline pressure scenario before drafting 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 an effective SKILL.md file for AI agents?

Start with YAML frontmatter containing name and description, then write a concise body with overview, when-to-use triggers, core patterns, and common mistakes. Test the skill with pressure scenarios before deploying to verify agents actually comply.

How to test agent skills before deploying them?

Run baseline pressure scenarios with subagents without the skill to document failures verbatim, then write the skill addressing those failures and re-test. Combine three or more pressures like time limits, sunk cost, and authority for realistic testing.

What makes a good skill description for agent discovery?

Start with "Use when..." followed by specific triggering conditions and symptoms, written in third person. Never summarize the skill's workflow in the description, because agents may follow the summary instead of reading the full skill.

Why do agents ignore skill instructions under pressure?

Agents rationalize rule violations when facing time pressure, sunk costs, or authority figures. Counter this with explicit negations of specific excuses, rationalization tables, red flag lists, and foundational principles like "violating the letter is violating the spirit."

When should I not create a new agent skill?

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