writing-skills

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

Updated May 21, 2026
One-click install
npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill writing-skills-cagesthrottleus
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/CagesThrottleUs/private-ai-harness/tree/main/skills/writing-skills
Command: npx skills add https://github.com/CagesThrottleUs/private-ai-harness --skill writing-skills-cagesthrottleus

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Untested skill documentation often fails in practice because authors never observe how agents actually behave without it, leading to instructions that agents ignore, misinterpret, or rationalize away under pressure. ## 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. - Rationalization Bulletproofing: Provides rationalization tables, red flag lists, and explicit loophole counters so discipline-enforcing skills resist agent workarounds. - Discovery Optimization (CSO): Defines naming, description, and keyword rules so future agents can find the skill via search, plus token-efficiency targets for frequently loaded skills. - Use Case: When creating a new skill like a code-review checklist, run pressure scenarios (time pressure, sunk cost, authority) against a subagent without the skill, document its exact excuses, then write the minimal skill that counters those specific failures and re-test until compliant. ## Quick Start Ask the agent to help you create a new skill by first running baseline pressure scenarios with subagents, then writing the SKILL.md that addresses 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 that agents actually follow?

Run pressure scenarios with subagents before writing anything, document their exact failures and rationalizations, then write the minimal skill addressing those specific failures. Re-test with the skill present and iterate until agents comply under maximum pressure.

What should go in a skill description field?

Write only triggering conditions starting with "Use when..." in third person, including specific symptoms and situations. 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?

Create realistic scenarios combining three or more pressures like time limits, sunk cost, and authority, then run them with subagents with and without the skill. Capture verbatim rationalizations and add explicit counters until no new loopholes appear.

When should I not create a new skill?

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

Why do agents ignore skills under time pressure?

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