writing-skills

Create and test agent skills using test-driven development methodology.

Updated Dec 23, 2025
One-click install
npx skills add https://github.com/macintorsten/aurapod --skill writing-skills-macintorsten
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/macintorsten/aurapod/tree/main/.github/skills/writing-skills
Command: npx skills add https://github.com/macintorsten/aurapod --skill writing-skills-macintorsten

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires graphviz.

What problem does it solve? Writing process documentation for AI agents often produces skills that agents ignore or rationalize away under pressure. This Skill applies test-driven development (RED-GREEN-REFACTOR) to skill authoring, ensuring skills are verified against real agent behavior before deployment. ## Core Features & Use Cases - TDD-Based Skill Authoring: Run baseline pressure scenarios with subagents, document failures verbatim, then write skills that address those specific rationalizations. - Discovery Optimization: Guidance on Claude Search Optimization (CSO), including description writing, keyword coverage, naming conventions, and token efficiency targets. - Bulletproofing Against Rationalization: Build rationalization tables, red flags lists, and explicit loophole counters so discipline-enforcing skills hold up under time, sunk cost, and authority pressures. - Use Case: When creating a new skill that enforces a rule like TDD, run pressure scenarios without the skill first, capture how agents violate the rule, write the skill to counter those exact excuses, and re-test until agents comply under maximum pressure. ## Quick Start Ask the agent to help you create a new skill by first running a baseline pressure scenario, then drafting the SKILL.md with proper frontmatter and testing it with subagents.

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 an AI agent?▼

A SKILL.md file needs YAML frontmatter with only name and description fields, followed by a markdown body with an overview, when-to-use triggers, core patterns, and quick reference sections. Keep the body under 500 lines and write the description in third person starting with "Use when".

How to test agent skills before deployment?▼

Test skills by running pressure scenarios with subagents: first without the skill to document baseline failures verbatim, then with the skill to verify compliance. Combine three or more pressures like time constraints, sunk cost, and authority for realistic testing.

What makes a good skill description for discovery?▼

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

Why do agents ignore or bypass skill instructions?▼

Agents rationalize away rules under pressure using excuses like sunk cost, pragmatism, or spirit-versus-letter arguments. Counter this by documenting rationalizations verbatim during baseline testing and adding explicit negations, red flags lists, and rationalization tables to the skill.

When should I not create a new skill?▼

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