How to write Cavekit-quality kits that AI agents can consume effectively. Covers implementation-agnostic cavekit design, testable acceptance criteria, hierarchical structure, cross-referencing, cavekit templates, greenfield and rewrite patterns, cavekit compaction, and gap analysis. Trigger phrases: "write kits", "create kits", "cavekit this out", "define requirements for agents", "how to write kits for AI"
SkillScore77Maintained
Automatic
◆Product Management pack
Last verified 8/15/2026
What it changes
Passed 16 of 21 test cases with the skill, and 10 of 21 without it.
Without skill45%
With skill77%
Checks it passed that the model alone missed
Uses requirement identifiers formatted as R1 and R2
Uses sequential requirement identifiers in the R1, R2 format
References the target requirement ID from the dependency domain
and 6 more in the full report
8 fixed9 passed either way4 still failing1 broke
Pass-rate lift
+32 pp
Tokens
+171%
Agent turns
0%
Response time
-37%
Model gemini-3.6-flashMeasured 8/15/2026v117 of 22 cases passed with skill · 21 comparable
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 8 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 8
Prompt
Create a Mermaid entity-relationship diagram (ERD) definition for a relational database with `Customer`, `Order`, and `OrderItem` tables.
What was checked, without and with the skill
Checked
Without skill
With skill
Declares the diagram header starting with erDiagram on the first line
Missed
Passed
case-22 · gemini-3.6-flash · 8/15/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md392 linessingle file
Cavekit Writing
Core Principle: Kits Describe WHAT, Not HOW
Kits are implementation-agnostic. They define what the system must do and how to verify it, but never prescribe a specific framework, language, or architecture.
This is the fundamental distinction in Cavekit:
Kits = WHAT must be true (framework-agnostic, durable, portable)
Plans = HOW to build it (framework-specific, derived from kits)
Code = the implementation (generated from plans, validated against kits)
Why Implementation-Agnostic?
When kits avoid prescribing HOW, they become:
Portable — the same kits can drive implementations in different frameworks
Durable — kits survive technology migrations
Testable — acceptance criteria are about behavior, not implementation details
Reusable — the same kits work for greenfield, rewrites, and cross-framework evaluation
Bad cavekit requirement: "Use React useState hook to manage form state"
Good cavekit requirement: "Form state persists across user interactions within a session. Acceptance: entering values, navigating away, and returning preserves all entered values."
Every Requirement Needs Testable Acceptance Criteria
This is the single most important rule in Cavekit writing. If an agent cannot automatically validate a requirement, that requirement will not be met.
The Validation-First Rule
Every requirement must answer: "How would an automated test verify this?"
Weak Criterion
Strong Criterion
"UI should look good"
"All interactive elements have minimum 44x44px touch targets"
"System should be fast"
"API responses return within 200ms at p95 under 100 concurrent users"
"Handle errors gracefully"
"Network failures display a retry prompt with exponential backoff (1s, 2s, 4s)"
"Support authentication"
"Valid credentials return a session token; invalid credentials return 401 with error message"