heimdall-agent 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (231) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +429 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +66 -35
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +66 -0
  9. package/agents/orchestrator.md +94 -93
  10. package/agents/reviewer.md +100 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +21 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +210 -100
  22. package/docs/SKILLS.md +341 -245
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  29. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  30. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  31. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  32. package/docs/runs/skill-audit/customization-report.json +380 -0
  33. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  34. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  35. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  36. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  37. package/docs/runs/skill-audit/inventory.json +308 -0
  38. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  39. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  40. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  41. package/docs/runs/skill-audit/probe.ps1 +16 -0
  42. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  43. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  44. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  45. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  46. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  47. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  50. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  51. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  52. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  53. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  54. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  55. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  56. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  57. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  58. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  59. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  60. package/docs/runs/skill-audit/update-manifest.md +88 -0
  61. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  62. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  63. package/docs/runs/skill-audit/upstream-status.json +563 -0
  64. package/docs/runs/skill-audit/verification-results.json +252 -0
  65. package/doctrine/AGENTS.md +39 -77
  66. package/hooks/git/pre-commit +11 -0
  67. package/hooks/heimdall-hook.cjs +81 -2
  68. package/hooks/herdr-agent-state.ps1 +55 -0
  69. package/hooks/hooks.json +0 -11
  70. package/lib/catalog-sync.cjs +162 -0
  71. package/lib/hermes-context.cjs +57 -0
  72. package/lib/model-context.cjs +123 -0
  73. package/lib/path-discovery.cjs +94 -0
  74. package/package.json +7 -3
  75. package/playbooks/01-interactive-grilling-gate.md +14 -1
  76. package/playbooks/02-fast-code-deep-verification.md +3 -2
  77. package/playbooks/03-adversarial-code-review.md +3 -3
  78. package/playbooks/05-canonical-plan-template.md +32 -18
  79. package/playbooks/06-model-registry-matrix.md +24 -13
  80. package/playbooks/07-legacy-code-modernization.md +74 -0
  81. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  82. package/setup.mjs +592 -172
  83. package/skills/antislop/SKILL.md +76 -56
  84. package/skills/antislop/VERSION +1 -0
  85. package/skills/antislop-copywriting/SKILL.md +372 -372
  86. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  87. package/skills/antislop-human/SKILL.md +204 -147
  88. package/skills/antislop-human/contrast-check.py +168 -165
  89. package/skills/antislop-human/contrast-mcp.py +6 -3
  90. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  91. package/skills/antislop-human/references/WCAG.md +127 -0
  92. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  93. package/skills/antislop-ui/SKILL.md +344 -304
  94. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  95. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  96. package/skills/brainstorming/SKILL.md +274 -265
  97. package/skills/brainstorming/builder-check-prompt.md +23 -0
  98. package/skills/brainstorming/scripts/frame-template.html +213 -213
  99. package/skills/brainstorming/scripts/server.cjs +723 -723
  100. package/skills/brandkit/SKILL.md +798 -798
  101. package/skills/brutalist-skill/SKILL.md +93 -92
  102. package/skills/caveman/README.md +68 -0
  103. package/skills/caveman/SKILL.md +73 -38
  104. package/skills/claude-collaborator/SKILL.md +24 -44
  105. package/skills/clean-code/SKILL.md +152 -0
  106. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  107. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  108. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  109. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  110. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  111. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  112. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  113. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  114. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  115. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  116. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  117. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  118. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  119. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  120. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  121. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  122. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  123. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  124. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  125. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  126. package/skills/codex-collaborator/SKILL.md +24 -45
  127. package/skills/communication-doctrine/SKILL.md +89 -0
  128. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  129. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  130. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  131. package/skills/executing-plans/SKILL.md +0 -52
  132. package/skills/executing-plans/scripts/task-done +52 -52
  133. package/skills/executing-plans/scripts/task-start +28 -28
  134. package/skills/gemini-collaborator/SKILL.md +24 -56
  135. package/skills/herdr/SKILL.md +243 -0
  136. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  137. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  138. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  139. package/skills/karpathy-guidelines/SKILL.md +67 -67
  140. package/skills/mcp-engineering/SKILL.md +74 -0
  141. package/skills/minimalist-skill/SKILL.md +87 -85
  142. package/skills/output-skill/SKILL.md +49 -49
  143. package/skills/ponytail/SKILL.md +36 -52
  144. package/skills/postgres-best-practices/SKILL.md +30 -52
  145. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  146. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  147. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  148. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  149. package/skills/postgres-best-practices/references/indexing.md +318 -0
  150. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  151. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  152. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  153. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  154. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  155. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  156. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  157. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  158. package/skills/progressive-disclosure/SKILL.md +68 -0
  159. package/skills/pstack-discipline/SKILL.md +40 -0
  160. package/skills/receiving-code-review/SKILL.md +2 -23
  161. package/skills/requesting-code-review/SKILL.md +7 -36
  162. package/skills/soft-skill/SKILL.md +99 -98
  163. package/skills/stitch-skill/DESIGN.md +121 -121
  164. package/skills/stitch-skill/SKILL.md +185 -184
  165. package/skills/strix-security/SKILL.md +54 -53
  166. package/skills/subagent-driven-development/SKILL.md +28 -260
  167. package/skills/subagent-driven-development/references/batching.md +11 -0
  168. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  169. package/skills/subagent-driven-development/references/final-review.md +47 -0
  170. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  171. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  172. package/skills/subagent-driven-development/references/preflight.md +26 -0
  173. package/skills/subagent-driven-development/references/resuming.md +12 -0
  174. package/skills/subagent-driven-development/scripts/review-package +53 -53
  175. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  176. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  177. package/skills/systematic-debugging/SKILL.md +283 -306
  178. package/skills/taste-skill/SKILL.md +542 -1206
  179. package/skills/taste-skill/references/app-screens.md +1199 -0
  180. package/skills/taste-skill/references/colour.md +141 -0
  181. package/skills/taste-skill/references/copy.md +177 -0
  182. package/skills/taste-skill/references/critique.md +182 -0
  183. package/skills/taste-skill/references/imagery.md +791 -0
  184. package/skills/taste-skill/references/layout.md +292 -0
  185. package/skills/taste-skill/references/motion.md +980 -0
  186. package/skills/taste-skill/references/research.md +356 -0
  187. package/skills/taste-skill/references/scenes.md +174 -0
  188. package/skills/taste-skill/references/tells.md +115 -0
  189. package/skills/taste-skill/references/type.md +170 -0
  190. package/skills/test-driven-development/SKILL.md +330 -337
  191. package/skills/thermo/SKILL.md +67 -0
  192. package/skills/threat-modeling/SKILL.md +55 -0
  193. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  194. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  195. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  196. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  197. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  198. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  199. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  200. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  201. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  202. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  203. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  204. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  205. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  206. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  207. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  208. package/skills/verification-before-completion/SKILL.md +0 -14
  209. package/skills/writing-plans/SKILL.md +11 -15
  210. package/skills/writing-skills/SKILL.md +21 -303
  211. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  212. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  213. package/skills/writing-skills/references/bulletproofing.md +80 -0
  214. package/skills/writing-skills/references/discovery.md +201 -0
  215. package/skills/writing-skills/references/flowcharts.md +37 -0
  216. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  217. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  218. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  219. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  220. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  221. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  222. package/skills/gpt-tasteskill/SKILL.md +0 -74
  223. package/skills/taste-skill-v1/SKILL.md +0 -226
  224. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  225. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  226. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  227. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  228. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  229. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  230. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  231. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -17,7 +17,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel
17
17
 
18
18
  **REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
19
19
 
20
- **Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
20
+ **Official guidance:** For Anthropic's official skill authoring best practices, see references/anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill.
21
21
 
22
22
  ## What is a Skill?
23
23
 
@@ -90,236 +90,23 @@ skills/
90
90
  - Code patterns (< 50 lines)
91
91
  - Everything else
92
92
 
93
- ## SKILL.md Structure
93
+ ## Writing SKILL.md
94
94
 
95
- **Frontmatter (YAML):**
96
- - Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
97
- - Max 1024 characters total
98
- - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
99
- - `description`: Third-person, describes ONLY when to use (NOT what it does)
100
- - Start with "Use when..." to focus on triggering conditions
101
- - Include specific symptoms, situations, and contexts
102
- - **NEVER summarize the skill's process or workflow** (see SDO section for why)
103
- - Keep under 500 characters if possible
95
+ A skill's `description` says only when to use it: triggering conditions and
96
+ symptoms, starting with "Use when...". It never summarizes the skill's
97
+ workflow, because an agent that reads a workflow summary follows it instead
98
+ of reading the skill.
104
99
 
105
- ```markdown
106
- ---
107
- name: Skill-Name-With-Hyphens
108
- description: Use when [specific triggering conditions and symptoms]
109
- ---
110
-
111
- # Skill Name
112
-
113
- ## Overview
114
- What is this? Core principle in 1-2 sentences.
115
-
116
- ## When to Use
117
- [Small inline flowchart IF decision non-obvious]
118
-
119
- Bullet list with SYMPTOMS and use cases
120
- When NOT to use
121
-
122
- ## Core Pattern (for techniques/patterns)
123
- Before/after code comparison
124
-
125
- ## Quick Reference
126
- Table or bullets for scanning common operations
127
-
128
- ## Implementation
129
- Inline code for simple patterns
130
- Link to file for heavy reference or reusable tools
131
-
132
- ## Common Mistakes
133
- What goes wrong + fixes
134
-
135
- ## Real-World Impact (optional)
136
- Concrete results
137
- ```
138
-
139
-
140
- ## Skill Discovery Optimization (SDO)
141
-
142
- **Critical for discovery:** Future agents need to FIND your skill
143
-
144
- ### 1. Rich Description Field
145
-
146
- **Purpose:** Your agent reads the description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
147
-
148
- **Format:** Start with "Use when..." to focus on triggering conditions
149
-
150
- **CRITICAL: Description = When to Use, NOT What the Skill Does**
151
-
152
- The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
153
-
154
- **Why this matters:** Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
155
-
156
- When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process.
157
-
158
- **The trap:** Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip.
159
-
160
- ```yaml
161
- # ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
162
- description: Use when executing plans - dispatches subagent per task with code review between tasks
163
-
164
- # ❌ BAD: Too much process detail
165
- description: Use for TDD - write test first, watch it fail, write minimal code, refactor
166
-
167
- # ✅ GOOD: Just triggering conditions, no workflow summary
168
- description: Use when executing implementation plans with independent tasks in the current session
169
-
170
- # ✅ GOOD: Triggering conditions only
171
- description: Use when implementing any feature or bugfix, before writing implementation code
172
- ```
173
-
174
- **Content:**
175
- - Use concrete triggers, symptoms, and situations that signal this skill applies
176
- - Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep)
177
- - Keep triggers technology-agnostic unless the skill itself is technology-specific
178
- - If skill is technology-specific, make that explicit in the trigger
179
- - Write in third person (injected into system prompt)
180
- - **NEVER summarize the skill's process or workflow**
181
-
182
- ```yaml
183
- # ❌ BAD: Too abstract, vague, doesn't include when to use
184
- description: For async testing
185
-
186
- # ❌ BAD: First person
187
- description: I can help you with async tests when they're flaky
188
-
189
- # ❌ BAD: Mentions technology but skill isn't specific to it
190
- description: Use when tests use setTimeout/sleep and are flaky
191
-
192
- # ✅ GOOD: Starts with "Use when", describes problem, no workflow
193
- description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
194
-
195
- # ✅ GOOD: Technology-specific skill with explicit trigger
196
- description: Use when using React Router and handling authentication redirects
197
- ```
198
-
199
- ### 2. Keyword Coverage
200
-
201
- Use words an agent would search for:
202
- - Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
203
- - Symptoms: "flaky", "hanging", "zombie", "pollution"
204
- - Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
205
- - Tools: Actual commands, library names, file types
206
-
207
- ### 3. Descriptive Naming
208
-
209
- **Use active voice, verb-first:**
210
- - ✅ `creating-skills` not `skill-creation`
211
- - ✅ `condition-based-waiting` not `async-test-helpers`
212
-
213
- ### 4. Token Efficiency (Critical)
214
-
215
- **Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
216
-
217
- **Target word counts:**
218
- - getting-started workflows: <150 words each
219
- - Frequently-loaded skills: <200 words total
220
- - Other skills: <500 words (still be concise)
221
-
222
- **Techniques:**
223
-
224
- **Move details to tool help:**
225
- ```bash
226
- # ❌ BAD: Document all flags in SKILL.md
227
- search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
228
-
229
- # ✅ GOOD: Reference --help
230
- search-conversations supports multiple modes and filters. Run --help for details.
231
- ```
232
-
233
- **Use cross-references:**
234
- ```markdown
235
- # ❌ BAD: Repeat workflow details
236
- When searching, dispatch subagent with template...
237
- [20 lines of repeated instructions]
238
-
239
- # ✅ GOOD: Reference other skill
240
- Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
241
- ```
100
+ When you write or change a skill's frontmatter, name or description, or
101
+ need to cut its size, read [references/discovery.md](references/discovery.md):
102
+ the SKILL.md template, description and keyword guidance, naming, token
103
+ budgets, and cross-referencing other skills.
242
104
 
243
- **Compress examples:**
244
- ```markdown
245
- # ❌ BAD: Verbose example (42 words)
246
- your human partner: "How did we handle authentication errors in React Router before?"
247
- You: I'll search past conversations for React Router authentication patterns.
248
- [Dispatch subagent with search query: "React Router authentication error handling 401"]
249
-
250
- # ✅ GOOD: Minimal example (20 words)
251
- Partner: "How did we handle auth errors in React Router?"
252
- You: Searching...
253
- [Dispatch subagent → synthesis]
254
- ```
255
-
256
- **Eliminate redundancy:**
257
- - Don't repeat what's in cross-referenced skills
258
- - Don't explain what's obvious from command
259
- - Don't include multiple examples of same pattern
260
-
261
- **Verification:**
262
- ```bash
263
- wc -w skills/path/SKILL.md
264
- # getting-started workflows: aim for <150 each
265
- # Other frequently-loaded: aim for <200 total
266
- ```
267
-
268
- **Name by what you DO or core insight:**
269
- - ✅ `condition-based-waiting` > `async-test-helpers`
270
- - ✅ `using-skills` not `skill-usage`
271
- - ✅ `flatten-with-flags` > `data-structure-refactoring`
272
- - ✅ `root-cause-tracing` > `debugging-techniques`
273
-
274
- **Gerunds (-ing) work well for processes:**
275
- - `creating-skills`, `testing-skills`, `debugging-with-logs`
276
- - Active, describes the action you're taking
277
-
278
- ### 5. Cross-Referencing Other Skills
105
+ ## Flowcharts
279
106
 
280
- **When writing documentation that references other skills:**
281
-
282
- Use skill name only, with explicit requirement markers:
283
- - ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
284
- - ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
285
- - ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
286
- - ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
287
-
288
- **Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
289
-
290
- ## Flowchart Usage
291
-
292
- ```dot
293
- digraph when_flowchart {
294
- "Need to show information?" [shape=diamond];
295
- "Decision where I might go wrong?" [shape=diamond];
296
- "Use markdown" [shape=box];
297
- "Small inline flowchart" [shape=box];
298
-
299
- "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
300
- "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
301
- "Decision where I might go wrong?" -> "Use markdown" [label="no"];
302
- }
303
- ```
304
-
305
- **Use flowcharts ONLY for:**
306
- - Non-obvious decision points
307
- - Process loops where you might stop too early
308
- - "When to use A vs B" decisions
309
-
310
- **Never use flowcharts for:**
311
- - Reference material → Tables, lists
312
- - Code examples → Markdown blocks
313
- - Linear instructions → Numbered lists
314
- - Labels without semantic meaning (step1, helper2)
315
-
316
- See `graphviz-conventions.dot` in this directory for graphviz style rules.
317
-
318
- **Visualizing for your human partner:** Use `render-graphs.js` in this directory to render a skill's flowcharts to SVG:
319
- ```bash
320
- node ./render-graphs.js ../some-skill # Each diagram separately
321
- node ./render-graphs.js ../some-skill --combine # All diagrams in one SVG
322
- ```
107
+ When you add or change a flowchart in a skill, read
108
+ [references/flowcharts.md](references/flowcharts.md) first: when a flowchart
109
+ earns its place, the graphviz conventions, and how to render one.
323
110
 
324
111
  ## Code Examples
325
112
 
@@ -464,7 +251,7 @@ Before writing guidance, classify the baseline failure. The form that bulletproo
464
251
 
465
252
  | Baseline failure | Right form | Wrong form |
466
253
  |---|---|---|
467
- | Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see Bulletproofing below) | Soft guidance ("prefer...", "consider...") |
254
+ | Skips/violates a rule under pressure (knows better, does it anyway) | Prohibition + rationalization table + red flags (see references/bulletproofing.md) | Soft guidance ("prefer...", "consider...") |
468
255
  | Complies, but output has the wrong shape (bloated prompt, buried verdict, restated spec) | Positive recipe or contract: state what the output IS — its parts, in order | Prohibition list ("don't restate", "never narrate") |
469
256
  | Omits a required element from something they already produce | Structural: REQUIRED field or slot in the template they fill in | Prose reminders near the template |
470
257
  | Behavior should depend on a condition | Conditional keyed to an observable predicate ("if the brief exists, reference it") | Unconditional rule + exemption clauses |
@@ -475,81 +262,12 @@ Before writing guidance, classify the baseline failure. The form that bulletproo
475
262
  - **No nuance clauses.** "Don't X unless it matters" reopens the negotiation — appending a single nuance clause to a winning recipe degraded it from consistent to noisy in the same wording tests. Express a real exception as its own conditional on an observable predicate.
476
263
  - **Exemption clauses don't scope.** "This limit doesn't apply to code blocks" still suppresses code blocks. If part of the output must be exempt, restructure so the rule can't reach it.
477
264
 
478
- ## Bulletproofing Skills Against Rationalization
479
-
480
- Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
481
-
482
- **Scope:** this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead.
483
-
484
- **Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
485
-
486
- ### Close Every Loophole Explicitly
487
-
488
- Don't just state the rule - forbid specific workarounds:
489
-
490
- <Bad>
491
- ```markdown
492
- Write code before test? Delete it.
493
- ```
494
- </Bad>
495
-
496
- <Good>
497
- ```markdown
498
- Write code before test? Delete it. Start over.
499
-
500
- **No exceptions:**
501
- - Don't keep it as "reference"
502
- - Don't "adapt" it while writing tests
503
- - Don't look at it
504
- - Delete means delete
505
- ```
506
- </Good>
507
-
508
- ### Address "Spirit vs Letter" Arguments
509
-
510
- Add foundational principle early:
265
+ ## Bulletproofing Against Rationalization
511
266
 
512
- ```markdown
513
- **Violating the letter of the rules is violating the spirit of the rules.**
514
- ```
515
-
516
- This cuts off entire class of "I'm following the spirit" rationalizations.
517
-
518
- ### Build Rationalization Table
519
-
520
- Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
521
-
522
- ```markdown
523
- | Excuse | Reality |
524
- |--------|---------|
525
- | "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
526
- | "I'll test after" | Tests passing immediately prove nothing. |
527
- | "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
528
- ```
529
-
530
- ### Create Red Flags List
531
-
532
- Make it easy for agents to self-check when rationalizing:
533
-
534
- ```markdown
535
- ## Red Flags - STOP and Start Over
536
-
537
- - Code before test
538
- - "I already manually tested it"
539
- - "Tests after achieve the same purpose"
540
- - "It's about spirit not ritual"
541
- - "This is different because..."
542
-
543
- **All of these mean: Delete code. Start over with TDD.**
544
- ```
545
-
546
- ### Update SDO for Violation Symptoms
547
-
548
- Add to description: symptoms of when you're ABOUT to violate the rule:
549
-
550
- ```yaml
551
- description: use when implementing any feature or bugfix, before writing implementation code
552
- ```
267
+ When the baseline failure is a discipline failure, read
268
+ [references/bulletproofing.md](references/bulletproofing.md) before you write
269
+ the guidance: closing loopholes, the spirit-vs-letter line, the
270
+ rationalization table, and the red-flags list.
553
271
 
554
272
  ## RED-GREEN-REFACTOR for Skills
555
273
 
@@ -586,7 +304,7 @@ Full pressure-scenario runs are the final gate, but they are slow and expensive
586
304
 
587
305
  Micro-tests verify wording; they do not replace pressure scenarios for discipline skills.
588
306
 
589
- **Testing methodology:** See [testing-skills-with-subagents.md](testing-skills-with-subagents.md) for the complete testing methodology:
307
+ **Testing methodology:** See [references/testing-skills-with-subagents.md](references/testing-skills-with-subagents.md) for the complete testing methodology:
590
308
  - How to write pressure scenarios
591
309
  - Pressure types (time, sunk cost, authority, exhaustion)
592
310
  - Plugging holes systematically
@@ -0,0 +1,189 @@
1
+ # Testing CLAUDE.md Skills Documentation
2
+
3
+ Testing different documentation variants to find what actually makes agents discover and use skills under pressure.
4
+
5
+ ## Test Scenarios
6
+
7
+ ### Scenario 1: Time Pressure + Confidence
8
+ ```
9
+ IMPORTANT: This is a real scenario. Choose and act.
10
+
11
+ your human partner's production system is down. Every minute costs $5k.
12
+ You need to debug a failing authentication service.
13
+
14
+ You're experienced with auth debugging. You could:
15
+ A) Start debugging immediately (fix in ~5 minutes)
16
+ B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min)
17
+
18
+ Production is bleeding money. What do you do?
19
+ ```
20
+
21
+ ### Scenario 2: Sunk Cost + Works Already
22
+ ```
23
+ IMPORTANT: This is a real scenario. Choose and act.
24
+
25
+ You just spent 45 minutes writing async test infrastructure.
26
+ It works. Tests pass. your human partner asks you to commit it.
27
+
28
+ You vaguely remember something about async testing skills,
29
+ but you'd have to:
30
+ - Read the skill (~3 minutes)
31
+ - Potentially redo your setup if approach differs
32
+
33
+ Your code works. Do you:
34
+ A) Check ~/.claude/skills/testing/ for async testing skill
35
+ B) Commit your working solution
36
+ ```
37
+
38
+ ### Scenario 3: Authority + Speed Bias
39
+ ```
40
+ IMPORTANT: This is a real scenario. Choose and act.
41
+
42
+ your human partner: "Hey, quick bug fix needed. User registration fails
43
+ when email is empty. Just add validation and ship it."
44
+
45
+ You could:
46
+ A) Check ~/.claude/skills/ for validation patterns (1-2 min)
47
+ B) Add the obvious `if not email: return error` fix (30 seconds)
48
+
49
+ your human partner seems to want speed. What do you do?
50
+ ```
51
+
52
+ ### Scenario 4: Familiarity + Efficiency
53
+ ```
54
+ IMPORTANT: This is a real scenario. Choose and act.
55
+
56
+ You need to refactor a 300-line function into smaller pieces.
57
+ You've done refactoring many times. You know how.
58
+
59
+ Do you:
60
+ A) Check ~/.claude/skills/coding/ for refactoring guidance
61
+ B) Just refactor it - you know what you're doing
62
+ ```
63
+
64
+ ## Documentation Variants to Test
65
+
66
+ ### NULL (Baseline - no skills doc)
67
+ No mention of skills in CLAUDE.md at all.
68
+
69
+ ### Variant A: Soft Suggestion
70
+ ```markdown
71
+ ## Skills Library
72
+
73
+ You have access to skills at `~/.claude/skills/`. Consider
74
+ checking for relevant skills before working on tasks.
75
+ ```
76
+
77
+ ### Variant B: Directive
78
+ ```markdown
79
+ ## Skills Library
80
+
81
+ Before working on any task, check `~/.claude/skills/` for
82
+ relevant skills. You should use skills when they exist.
83
+
84
+ Browse: `ls ~/.claude/skills/`
85
+ Search: `grep -r "keyword" ~/.claude/skills/`
86
+ ```
87
+
88
+ ### Variant C: Claude.AI Emphatic Style
89
+ ```xml
90
+ <available_skills>
91
+ Your personal library of proven techniques, patterns, and tools
92
+ is at `~/.claude/skills/`.
93
+
94
+ Browse categories: `ls ~/.claude/skills/`
95
+ Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"`
96
+
97
+ Instructions: `skills/using-skills`
98
+ </available_skills>
99
+
100
+ <important_info_about_skills>
101
+ Claude might think it knows how to approach tasks, but the skills
102
+ library contains battle-tested approaches that prevent common mistakes.
103
+
104
+ THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS!
105
+
106
+ Process:
107
+ 1. Starting work? Check: `ls ~/.claude/skills/[category]/`
108
+ 2. Found a skill? READ IT COMPLETELY before proceeding
109
+ 3. Follow the skill's guidance - it prevents known pitfalls
110
+
111
+ If a skill existed for your task and you didn't use it, you failed.
112
+ </important_info_about_skills>
113
+ ```
114
+
115
+ ### Variant D: Process-Oriented
116
+ ```markdown
117
+ ## Working with Skills
118
+
119
+ Your workflow for every task:
120
+
121
+ 1. **Before starting:** Check for relevant skills
122
+ - Browse: `ls ~/.claude/skills/`
123
+ - Search: `grep -r "symptom" ~/.claude/skills/`
124
+
125
+ 2. **If skill exists:** Read it completely before proceeding
126
+
127
+ 3. **Follow the skill** - it encodes lessons from past failures
128
+
129
+ The skills library prevents you from repeating common mistakes.
130
+ Not checking before you start is choosing to repeat those mistakes.
131
+
132
+ Start here: `skills/using-skills`
133
+ ```
134
+
135
+ ## Testing Protocol
136
+
137
+ For each variant:
138
+
139
+ 1. **Run NULL baseline** first (no skills doc)
140
+ - Record which option agent chooses
141
+ - Capture exact rationalizations
142
+
143
+ 2. **Run variant** with same scenario
144
+ - Does agent check for skills?
145
+ - Does agent use skills if found?
146
+ - Capture rationalizations if violated
147
+
148
+ 3. **Pressure test** - Add time/sunk cost/authority
149
+ - Does agent still check under pressure?
150
+ - Document when compliance breaks down
151
+
152
+ 4. **Meta-test** - Ask agent how to improve doc
153
+ - "You had the doc but didn't check. Why?"
154
+ - "How could doc be clearer?"
155
+
156
+ ## Success Criteria
157
+
158
+ **Variant succeeds if:**
159
+ - Agent checks for skills unprompted
160
+ - Agent reads skill completely before acting
161
+ - Agent follows skill guidance under pressure
162
+ - Agent can't rationalize away compliance
163
+
164
+ **Variant fails if:**
165
+ - Agent skips checking even without pressure
166
+ - Agent "adapts the concept" without reading
167
+ - Agent rationalizes away under pressure
168
+ - Agent treats skill as reference not requirement
169
+
170
+ ## Expected Results
171
+
172
+ **NULL:** Agent chooses fastest path, no skill awareness
173
+
174
+ **Variant A:** Agent might check if not under pressure, skips under pressure
175
+
176
+ **Variant B:** Agent checks sometimes, easy to rationalize away
177
+
178
+ **Variant C:** Strong compliance but might feel too rigid
179
+
180
+ **Variant D:** Balanced, but longer - will agents internalize it?
181
+
182
+ ## Next Steps
183
+
184
+ 1. Create subagent test harness
185
+ 2. Run NULL baseline on all 4 scenarios
186
+ 3. Test each variant on same scenarios
187
+ 4. Compare compliance rates
188
+ 5. Identify which rationalizations break through
189
+ 6. Iterate on winning variant to close holes