TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/LIDR-academy/lidr-specboot/llms.txt
Use this file to discover all available pages before exploring further.
writing-skills skill applies the discipline of Test-Driven Development to the creation of AI agent documentation. Writing a skill without first watching an agent fail without it is the same violation as writing production code without a failing test — you have no evidence the skill teaches the right thing.
Core Concept
Writing skills IS Test-Driven Development applied to process documentation. You write test cases (pressure scenarios), watch them fail (baseline agent behaviour without the skill), write the skill (the documentation), watch the tests pass (the agent complies), and refactor (close loopholes the agent finds). The cycle is identical to software TDD — only the artefacts differ. Personal skills (not tied to a specific project) live in agent-specific directories:~/.claude/skills/ for Claude Code, ~/.agents/skills/ for Codex. Project skills live in ai-specs/skills/.
TDD Mapping
| TDD Concept | Skill Creation Equivalent |
|---|---|
| Test case | Pressure scenario with a subagent |
| Production code | Skill document (SKILL.md) |
| Test fails (RED) | Agent violates the rule without the skill present |
| Test passes (GREEN) | Agent complies with the skill loaded |
| Refactor | Close loopholes while maintaining compliance |
| Write test first | Run baseline scenario before writing the skill |
| Watch it fail | Document the exact rationalizations the agent uses |
| Minimal code | Write the skill targeting those specific violations |
| Watch it pass | Verify the agent now complies |
| Refactor cycle | Find new rationalizations → plug → re-verify |
When to Create a Skill
Create a skill when:- A technique was not intuitively obvious — if you had to figure it out, future agents will too
- You would reference it again across different projects
- The pattern applies broadly, not just to one codebase
- Others on the team would benefit from the same guidance
- One-off solutions specific to a single task
- Standard practices that are already well-documented elsewhere
- Project-specific conventions — put those in
CLAUDE.md - Mechanical constraints that can be enforced with validation or automation (save documentation for judgment calls)
What a Skill Is vs. Is Not
| Skill IS | Skill IS NOT |
|---|---|
| A reusable technique or pattern | A narrative about how you solved a problem once |
| A reference guide for proven approaches | A one-time solution write-up |
| A tool that applies broadly across projects | A project-specific convention |
| Documentation for judgment calls | A substitute for automated enforcement |
The RED-GREEN-REFACTOR Cycle for Skills
RED — Run the Baseline Scenario
Before writing a single line of the skill, run a pressure scenario with a subagent without the skill present. Observe the raw behaviour:
- What choices does the agent make?
- What rationalizations does it produce (capture verbatim)?
- Which pressures triggered the violation: time pressure, sunk cost, authority, exhaustion?
Document Exact Violations
Record the specific rationalizations and shortcuts the agent used. These become the content of the skill — each rationalization needs an explicit counter in the skill body.For discipline-enforcing skills (rules the agent might try to skip), build a rationalization table from the baseline observations:
| Excuse | Reality |
|---|---|
| ”This is too simple to need a skill” | Simple tasks still benefit from consistent patterns |
| ”I’ll test after, same result” | Testing after confirms what code does, not what it should do |
| ”I’m following the spirit of the rule” | Violating the letter is violating the spirit |
GREEN — Write the Minimal Skill
Write
ai-specs/skills/{name}/SKILL.md addressing the specific rationalizations documented in the RED phase. Do not add content for hypothetical cases not observed in baseline testing.Required elements:- YAML frontmatter:
name,description(starts with “Use when…”),author,version - Overview: core principle in 1–2 sentences
- When to Use: bullet list of symptoms and triggering conditions
- Instructions: step-by-step process addressing the specific failures observed
- Common Mistakes: the rationalizations from baseline, with explicit counters
REFACTOR — Close Loopholes
Agents will find new rationalizations. For each new bypass discovered:
- Add an explicit counter to the skill
- Re-run the scenarios to confirm the counter works
- Repeat until the skill is bulletproof under maximum pressure
Verify and Deploy
Before deploying, confirm:
- Skill name uses only letters, numbers, and hyphens
-
descriptionfield starts with “Use when…” and describes triggering conditions only (no workflow summary) - Description is written in third person and stays under 500 characters if possible
- The skill addresses the specific baseline failures — not hypothetical ones
- Common Mistakes section captures the rationalization table
- Supporting files are only added for heavy reference (100+ lines) or reusable tools
sync-agent-symlinks), and verify one final time that the agent picks it up correctly.SKILL.md Structure
The Iron Law
Claude Search Optimization
Thedescription field is what the agent reads to decide whether to load the skill. It must describe when to use the skill — triggering conditions and symptoms — never the workflow itself.