mirror of
https://github.com/obra/superpowers.git
synced 2026-05-08 10:09:04 +08:00
Initial commit: Superpowers plugin v1.0.0
Core skills library as Claude Code plugin: - Testing skills: TDD, async testing, anti-patterns - Debugging skills: Systematic debugging, root cause tracing - Collaboration skills: Brainstorming, planning, code review - Meta skills: Creating and testing skills Features: - SessionStart hook for context injection - Skills-search tool for discovery - Commands: /brainstorm, /write-plan, /execute-plan - Data directory at ~/.superpowers/
This commit is contained in:
Jesse Vincent
14
skills/meta/INDEX.md
Normal file
14
skills/meta/INDEX.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# Meta Skills
|
||||
|
||||
Skills about skills - how to create and use the skills system.
|
||||
|
||||
## Available Skills
|
||||
|
||||
- skills/meta/installing-skills - Fork, clone, and symlink clank repo to ~/.claude/skills. Use for initial setup, installing clank for the first time.
|
||||
|
||||
- skills/meta/creating-skills - How to create effective skills for future Claude instances. Use when you discover a technique, pattern, or tool worth documenting for reuse.
|
||||
|
||||
- skills/meta/testing-skills-with-subagents - Iteratively test and bulletproof skills using pressure scenarios and rationalization analysis. Use after writing skills that enforce discipline or rules, before deploying skills agents might want to bypass.
|
||||
|
||||
- skills/meta/gardening-skills-wiki - Maintain skills wiki health with automated checks for broken links, naming consistency, and INDEX coverage. Use when adding/removing skills, reorganizing categories, or for periodic maintenance.
|
||||
|
||||
585
skills/meta/creating-skills/SKILL.md
Normal file
585
skills/meta/creating-skills/SKILL.md
Normal file
@@ -0,0 +1,585 @@
|
||||
---
|
||||
name: Creating Skills
|
||||
description: TDD for process documentation - test with subagents before writing, iterate until bulletproof
|
||||
when_to_use: When you discover a technique, pattern, or tool worth documenting for reuse. When you've written a skill and need to verify it works before deploying.
|
||||
version: 4.0.0
|
||||
languages: all
|
||||
---
|
||||
|
||||
# Creating Skills
|
||||
|
||||
## Overview
|
||||
|
||||
**Creating skills IS Test-Driven Development applied to process documentation.**
|
||||
|
||||
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
|
||||
|
||||
**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
|
||||
|
||||
See skills/testing/test-driven-development for the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.
|
||||
|
||||
## What is a Skill?
|
||||
|
||||
A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
|
||||
|
||||
**Skills are:** Reusable techniques, patterns, tools, reference guides
|
||||
|
||||
**Skills are NOT:** Narratives about how you solved a problem once
|
||||
|
||||
## TDD Mapping for Skills
|
||||
|
||||
| TDD Concept | Skill Creation |
|
||||
|-------------|----------------|
|
||||
| **Test case** | Pressure scenario with subagent |
|
||||
| **Production code** | Skill document (SKILL.md) |
|
||||
| **Test fails (RED)** | Agent violates rule without skill (baseline) |
|
||||
| **Test passes (GREEN)** | Agent complies with skill present |
|
||||
| **Refactor** | Close loopholes while maintaining compliance |
|
||||
| **Write test first** | Run baseline scenario BEFORE writing skill |
|
||||
| **Watch it fail** | Document exact rationalizations agent uses |
|
||||
| **Minimal code** | Write skill addressing those specific violations |
|
||||
| **Watch it pass** | Verify agent now complies |
|
||||
| **Refactor cycle** | Find new rationalizations → plug → re-verify |
|
||||
|
||||
The entire skill creation process follows RED-GREEN-REFACTOR.
|
||||
|
||||
## When to Create a Skill
|
||||
|
||||
**Create when:**
|
||||
- Technique wasn't intuitively obvious to you
|
||||
- You'd reference this again across projects
|
||||
- Pattern applies broadly (not project-specific)
|
||||
- Others would benefit
|
||||
|
||||
**Don't create for:**
|
||||
- One-off solutions
|
||||
- Standard practices well-documented elsewhere
|
||||
- Project-specific conventions (put in CLAUDE.md)
|
||||
|
||||
## Skill Types
|
||||
|
||||
### Technique
|
||||
Concrete method with steps to follow (condition-based-waiting, root-cause-tracing)
|
||||
|
||||
### Pattern
|
||||
Way of thinking about problems (flatten-with-flags, test-invariants)
|
||||
|
||||
### Reference
|
||||
API docs, syntax guides, tool documentation (office docs)
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
skills/
|
||||
skill-name/
|
||||
SKILL.md # Main reference (required)
|
||||
supporting-file.* # Only if needed
|
||||
```
|
||||
|
||||
**Flat namespace** - all skills in one searchable location
|
||||
|
||||
**Separate files for:**
|
||||
1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
|
||||
2. **Reusable tools** - Scripts, utilities, templates
|
||||
|
||||
**Keep inline:**
|
||||
- Principles and concepts
|
||||
- Code patterns (< 50 lines)
|
||||
- Everything else
|
||||
|
||||
## SKILL.md Structure
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: Human-Readable Name
|
||||
description: One-line summary of what this does
|
||||
when_to_use: Symptoms and situations when you need this (CSO-critical)
|
||||
version: 1.0.0
|
||||
languages: all | [typescript, python] | etc
|
||||
dependencies: (optional) Required tools/libraries
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
## Overview
|
||||
What is this? Core principle in 1-2 sentences.
|
||||
|
||||
## When to Use
|
||||
[Small inline flowchart IF decision non-obvious]
|
||||
|
||||
Bullet list with SYMPTOMS and use cases
|
||||
When NOT to use
|
||||
|
||||
## Core Pattern (for techniques/patterns)
|
||||
Before/after code comparison
|
||||
|
||||
## Quick Reference
|
||||
Table or bullets for scanning common operations
|
||||
|
||||
## Implementation
|
||||
Inline code for simple patterns
|
||||
@link to file for heavy reference or reusable tools
|
||||
|
||||
## Common Mistakes
|
||||
What goes wrong + fixes
|
||||
|
||||
## Real-World Impact (optional)
|
||||
Concrete results
|
||||
```
|
||||
|
||||
## Claude Search Optimization (CSO)
|
||||
|
||||
**Critical for discovery:** Future Claude needs to FIND your skill
|
||||
|
||||
### 1. Rich when_to_use
|
||||
|
||||
Include SYMPTOMS not just abstract use cases:
|
||||
|
||||
```yaml
|
||||
# ❌ BAD: Too abstract
|
||||
when_to_use: For async testing
|
||||
|
||||
# ✅ GOOD: Symptoms and context
|
||||
when_to_use: When tests use setTimeout/sleep and are flaky, timing-dependent,
|
||||
pass locally but fail in CI, or timeout when run in parallel
|
||||
```
|
||||
|
||||
### 2. Keyword Coverage
|
||||
|
||||
Use words Claude would search for:
|
||||
- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
|
||||
- Symptoms: "flaky", "hanging", "zombie", "pollution"
|
||||
- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
|
||||
- Tools: Actual commands, library names, file types
|
||||
|
||||
### 3. Descriptive Naming
|
||||
|
||||
**Use active voice, verb-first:**
|
||||
- ✅ `creating-skills` not `skill-creation`
|
||||
- ✅ `testing-skills-with-subagents` not `subagent-skill-testing`
|
||||
|
||||
### 4. Token Efficiency (Critical)
|
||||
|
||||
**Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
|
||||
|
||||
**Target word counts:**
|
||||
- getting-started workflows: <150 words each
|
||||
- Frequently-loaded skills: <200 words total
|
||||
- Other skills: <500 words (still be concise)
|
||||
|
||||
**Techniques:**
|
||||
|
||||
**Move details to tool help:**
|
||||
```bash
|
||||
# ❌ BAD: Document all flags in SKILL.md
|
||||
search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
|
||||
|
||||
# ✅ GOOD: Reference --help
|
||||
search-conversations supports multiple modes and filters. Run --help for details.
|
||||
```
|
||||
|
||||
**Use cross-references:**
|
||||
```markdown
|
||||
# ❌ BAD: Repeat workflow details
|
||||
When searching, dispatch subagent with template...
|
||||
[20 lines of repeated instructions]
|
||||
|
||||
# ✅ GOOD: Reference other skill
|
||||
Always use subagents (50-100x context savings). See skills/getting-started for workflow.
|
||||
```
|
||||
|
||||
**Compress examples:**
|
||||
```markdown
|
||||
# ❌ BAD: Verbose example (42 words)
|
||||
your human partner: "How did we handle authentication errors in React Router before?"
|
||||
You: I'll search past conversations for React Router authentication patterns.
|
||||
[Dispatch subagent with search query: "React Router authentication error handling 401"]
|
||||
|
||||
# ✅ GOOD: Minimal example (20 words)
|
||||
Partner: "How did we handle auth errors in React Router?"
|
||||
You: Searching...
|
||||
[Dispatch subagent → synthesis]
|
||||
```
|
||||
|
||||
**Eliminate redundancy:**
|
||||
- Don't repeat what's in cross-referenced skills
|
||||
- Don't explain what's obvious from command
|
||||
- Don't include multiple examples of same pattern
|
||||
|
||||
**Verification:**
|
||||
```bash
|
||||
wc -w skills/path/SKILL.md
|
||||
# getting-started workflows: aim for <150 each
|
||||
# Other frequently-loaded: aim for <200 total
|
||||
```
|
||||
|
||||
**Name by what you DO or core insight:**
|
||||
- ✅ `condition-based-waiting` > `async-test-helpers`
|
||||
- ✅ `using-skills` not `skill-usage`
|
||||
- ✅ `flatten-with-flags` > `data-structure-refactoring`
|
||||
- ✅ `root-cause-tracing` > `debugging-techniques`
|
||||
|
||||
**Gerunds (-ing) work well for processes:**
|
||||
- `creating-skills`, `testing-skills`, `debugging-with-logs`
|
||||
- Active, describes the action you're taking
|
||||
|
||||
### 4. Content Repetition
|
||||
|
||||
Mention key concepts multiple times:
|
||||
- In description
|
||||
- In when_to_use
|
||||
- In overview
|
||||
- In section headers
|
||||
|
||||
Grep hits from multiple places = easier discovery
|
||||
|
||||
## Flowchart Usage
|
||||
|
||||
```dot
|
||||
digraph when_flowchart {
|
||||
"Need to show information?" [shape=diamond];
|
||||
"Decision where I might go wrong?" [shape=diamond];
|
||||
"Use markdown" [shape=box];
|
||||
"Small inline flowchart" [shape=box];
|
||||
|
||||
"Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
|
||||
"Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
|
||||
"Decision where I might go wrong?" -> "Use markdown" [label="no"];
|
||||
}
|
||||
```
|
||||
|
||||
**Use flowcharts ONLY for:**
|
||||
- Non-obvious decision points
|
||||
- Process loops where you might stop too early
|
||||
- "When to use A vs B" decisions
|
||||
|
||||
**Never use flowcharts for:**
|
||||
- Reference material → Tables, lists
|
||||
- Code examples → Markdown blocks
|
||||
- Linear instructions → Numbered lists
|
||||
- Labels without semantic meaning (step1, helper2)
|
||||
|
||||
See @graphviz-conventions.dot for graphviz style rules.
|
||||
|
||||
## Code Examples
|
||||
|
||||
**One excellent example beats many mediocre ones**
|
||||
|
||||
Choose most relevant language:
|
||||
- Testing techniques → TypeScript/JavaScript
|
||||
- System debugging → Shell/Python
|
||||
- Data processing → Python
|
||||
|
||||
**Good example:**
|
||||
- Complete and runnable
|
||||
- Well-commented explaining WHY
|
||||
- From real scenario
|
||||
- Shows pattern clearly
|
||||
- Ready to adapt (not generic template)
|
||||
|
||||
**Don't:**
|
||||
- Implement in 5+ languages
|
||||
- Create fill-in-the-blank templates
|
||||
- Write contrived examples
|
||||
|
||||
You're good at porting - one great example is enough.
|
||||
|
||||
## File Organization
|
||||
|
||||
### Self-Contained Skill
|
||||
```
|
||||
defense-in-depth/
|
||||
SKILL.md # Everything inline
|
||||
```
|
||||
When: All content fits, no heavy reference needed
|
||||
|
||||
### Skill with Reusable Tool
|
||||
```
|
||||
condition-based-waiting/
|
||||
SKILL.md # Overview + patterns
|
||||
example.ts # Working helpers to adapt
|
||||
```
|
||||
When: Tool is reusable code, not just narrative
|
||||
|
||||
### Skill with Heavy Reference
|
||||
```
|
||||
pptx/
|
||||
SKILL.md # Overview + workflows
|
||||
pptxgenjs.md # 600 lines API reference
|
||||
ooxml.md # 500 lines XML structure
|
||||
scripts/ # Executable tools
|
||||
```
|
||||
When: Reference material too large for inline
|
||||
|
||||
## The Iron Law (Same as TDD)
|
||||
|
||||
```
|
||||
NO SKILL WITHOUT A FAILING TEST FIRST
|
||||
```
|
||||
|
||||
Write skill before testing? Delete it. Start over.
|
||||
|
||||
**No exceptions:**
|
||||
- Don't keep it as "reference"
|
||||
- Don't "adapt" it while running tests
|
||||
- Don't look at it
|
||||
- Delete means delete
|
||||
|
||||
See skills/testing/test-driven-development for why this matters. Same principles apply to documentation.
|
||||
|
||||
## Testing All Skill Types
|
||||
|
||||
Different skill types need different test approaches:
|
||||
|
||||
### Discipline-Enforcing Skills (rules/requirements)
|
||||
|
||||
**Examples:** TDD, verification-before-completion, designing-before-coding
|
||||
|
||||
**Test with:**
|
||||
- Academic questions: Do they understand the rules?
|
||||
- Pressure scenarios: Do they comply under stress?
|
||||
- Multiple pressures combined: time + sunk cost + exhaustion
|
||||
- Identify rationalizations and add explicit counters
|
||||
|
||||
**Success criteria:** Agent follows rule under maximum pressure
|
||||
|
||||
### Technique Skills (how-to guides)
|
||||
|
||||
**Examples:** condition-based-waiting, root-cause-tracing, defensive-programming
|
||||
|
||||
**Test with:**
|
||||
- Application scenarios: Can they apply the technique correctly?
|
||||
- Variation scenarios: Do they handle edge cases?
|
||||
- Missing information tests: Do instructions have gaps?
|
||||
|
||||
**Success criteria:** Agent successfully applies technique to new scenario
|
||||
|
||||
### Pattern Skills (mental models)
|
||||
|
||||
**Examples:** reducing-complexity, information-hiding concepts
|
||||
|
||||
**Test with:**
|
||||
- Recognition scenarios: Do they recognize when pattern applies?
|
||||
- Application scenarios: Can they use the mental model?
|
||||
- Counter-examples: Do they know when NOT to apply?
|
||||
|
||||
**Success criteria:** Agent correctly identifies when/how to apply pattern
|
||||
|
||||
### Reference Skills (documentation/APIs)
|
||||
|
||||
**Examples:** API documentation, command references, library guides
|
||||
|
||||
**Test with:**
|
||||
- Retrieval scenarios: Can they find the right information?
|
||||
- Application scenarios: Can they use what they found correctly?
|
||||
- Gap testing: Are common use cases covered?
|
||||
|
||||
**Success criteria:** Agent finds and correctly applies reference information
|
||||
|
||||
## Common Rationalizations for Skipping Testing
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
|
||||
| "It's just a reference" | References can have gaps, unclear sections. Test retrieval. |
|
||||
| "Testing is overkill" | Untested skills have issues. Always. 15 min testing saves hours. |
|
||||
| "I'll test if problems emerge" | Problems = agents can't use skill. Test BEFORE deploying. |
|
||||
| "Too tedious to test" | Testing is less tedious than debugging bad skill in production. |
|
||||
| "I'm confident it's good" | Overconfidence guarantees issues. Test anyway. |
|
||||
| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
|
||||
| "No time to test" | Deploying untested skill wastes more time fixing it later. |
|
||||
|
||||
**All of these mean: Test before deploying. No exceptions.**
|
||||
|
||||
## Bulletproofing Skills Against Rationalization
|
||||
|
||||
Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
|
||||
|
||||
### Close Every Loophole Explicitly
|
||||
|
||||
Don't just state the rule - forbid specific workarounds:
|
||||
|
||||
<Bad>
|
||||
```markdown
|
||||
Write code before test? Delete it.
|
||||
```
|
||||
</Bad>
|
||||
|
||||
<Good>
|
||||
```markdown
|
||||
Write code before test? Delete it. Start over.
|
||||
|
||||
**No exceptions:**
|
||||
- Don't keep it as "reference"
|
||||
- Don't "adapt" it while writing tests
|
||||
- Don't look at it
|
||||
- Delete means delete
|
||||
```
|
||||
</Good>
|
||||
|
||||
### Address "Spirit vs Letter" Arguments
|
||||
|
||||
Add foundational principle early:
|
||||
|
||||
```markdown
|
||||
**Violating the letter of the rules is violating the spirit of the rules.**
|
||||
```
|
||||
|
||||
This cuts off entire class of "I'm following the spirit" rationalizations.
|
||||
|
||||
### Build Rationalization Table
|
||||
|
||||
Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
|
||||
|
||||
```markdown
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
|
||||
| "I'll test after" | Tests passing immediately prove nothing. |
|
||||
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
|
||||
```
|
||||
|
||||
### Create Red Flags List
|
||||
|
||||
Make it easy for agents to self-check when rationalizing:
|
||||
|
||||
```markdown
|
||||
## Red Flags - STOP and Start Over
|
||||
|
||||
- Code before test
|
||||
- "I already manually tested it"
|
||||
- "Tests after achieve the same purpose"
|
||||
- "It's about spirit not ritual"
|
||||
- "This is different because..."
|
||||
|
||||
**All of these mean: Delete code. Start over with TDD.**
|
||||
```
|
||||
|
||||
### Update CSO for Violation Symptoms
|
||||
|
||||
Add to when_to_use: symptoms of when you're ABOUT to violate the rule:
|
||||
|
||||
```yaml
|
||||
when_to_use: Every feature and bugfix. When you wrote code before tests.
|
||||
When you're tempted to test after. When manually testing seems faster.
|
||||
```
|
||||
|
||||
## RED-GREEN-REFACTOR for Skills
|
||||
|
||||
Follow the TDD cycle:
|
||||
|
||||
### RED: Write Failing Test (Baseline)
|
||||
|
||||
Run pressure scenario with subagent WITHOUT the skill. Document exact behavior:
|
||||
- What choices did they make?
|
||||
- What rationalizations did they use (verbatim)?
|
||||
- Which pressures triggered violations?
|
||||
|
||||
This is "watch the test fail" - you must see what agents naturally do before writing the skill.
|
||||
|
||||
### GREEN: Write Minimal Skill
|
||||
|
||||
Write skill that addresses those specific rationalizations. Don't add extra content for hypothetical cases.
|
||||
|
||||
Run same scenarios WITH skill. Agent should now comply.
|
||||
|
||||
### REFACTOR: Close Loopholes
|
||||
|
||||
Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
|
||||
|
||||
**See skills/testing-skills-with-subagents for:**
|
||||
- How to write pressure scenarios
|
||||
- Pressure types (time, sunk cost, authority, exhaustion)
|
||||
- Plugging holes systematically
|
||||
- Meta-testing techniques
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### ❌ Narrative Example
|
||||
"In session 2025-10-03, we found empty projectDir caused..."
|
||||
**Why bad:** Too specific, not reusable
|
||||
|
||||
### ❌ Multi-Language Dilution
|
||||
example-js.js, example-py.py, example-go.go
|
||||
**Why bad:** Mediocre quality, maintenance burden
|
||||
|
||||
### ❌ Code in Flowcharts
|
||||
```dot
|
||||
step1 [label="import fs"];
|
||||
step2 [label="read file"];
|
||||
```
|
||||
**Why bad:** Can't copy-paste, hard to read
|
||||
|
||||
### ❌ Generic Labels
|
||||
helper1, helper2, step3, pattern4
|
||||
**Why bad:** Labels should have semantic meaning
|
||||
|
||||
## STOP: Before Moving to Next Skill
|
||||
|
||||
**After writing ANY skill, you MUST STOP and complete the deployment process.**
|
||||
|
||||
**Do NOT:**
|
||||
- Create multiple skills in batch without testing each
|
||||
- Update INDEX.md before testing skills
|
||||
- Move to next skill before current one is verified
|
||||
- Skip testing because "batching is more efficient"
|
||||
|
||||
**The deployment checklist below is MANDATORY for EACH skill.**
|
||||
|
||||
Deploying untested skills = deploying untested code. It's a violation of quality standards.
|
||||
|
||||
## Skill Creation Checklist (TDD Adapted)
|
||||
|
||||
**IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.**
|
||||
|
||||
**RED Phase - Write Failing Test:**
|
||||
- [ ] Create pressure scenarios (3+ combined pressures for discipline skills)
|
||||
- [ ] Run scenarios WITHOUT skill - document baseline behavior verbatim
|
||||
- [ ] Identify patterns in rationalizations/failures
|
||||
|
||||
**GREEN Phase - Write Minimal Skill:**
|
||||
- [ ] Name describes what you DO or core insight
|
||||
- [ ] YAML frontmatter with rich when_to_use (include symptoms!)
|
||||
- [ ] Keywords throughout for search (errors, symptoms, tools)
|
||||
- [ ] Clear overview with core principle
|
||||
- [ ] Address specific baseline failures identified in RED
|
||||
- [ ] Code inline OR @link to separate file
|
||||
- [ ] One excellent example (not multi-language)
|
||||
- [ ] Run scenarios WITH skill - verify agents now comply
|
||||
|
||||
**REFACTOR Phase - Close Loopholes:**
|
||||
- [ ] Identify NEW rationalizations from testing
|
||||
- [ ] Add explicit counters (if discipline skill)
|
||||
- [ ] Build rationalization table from all test iterations
|
||||
- [ ] Create red flags list
|
||||
- [ ] Re-test until bulletproof
|
||||
|
||||
**Quality Checks:**
|
||||
- [ ] Small flowchart only if decision non-obvious
|
||||
- [ ] Quick reference table
|
||||
- [ ] Common mistakes section
|
||||
- [ ] No narrative storytelling
|
||||
- [ ] Supporting files only for tools or heavy reference
|
||||
|
||||
## Discovery Workflow
|
||||
|
||||
How future Claude finds your skill:
|
||||
|
||||
1. **Encounters problem** ("tests are flaky")
|
||||
2. **Greps skills** (`grep -r "flaky" ~/.claude/skills/`)
|
||||
3. **Finds SKILL.md** (rich when_to_use matches)
|
||||
4. **Scans overview** (is this relevant?)
|
||||
5. **Reads patterns** (quick reference table)
|
||||
6. **Loads example** (only when implementing)
|
||||
|
||||
**Optimize for this flow** - put searchable terms early and often.
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Creating skills IS TDD for process documentation.**
|
||||
|
||||
Same Iron Law: No skill without failing test first.
|
||||
Same cycle: RED (baseline) → GREEN (write skill) → REFACTOR (close loopholes).
|
||||
Same benefits: Better quality, fewer surprises, bulletproof results.
|
||||
|
||||
If you follow TDD for code, follow it for skills. It's the same discipline applied to documentation.
|
||||
172
skills/meta/creating-skills/graphviz-conventions.dot
Normal file
172
skills/meta/creating-skills/graphviz-conventions.dot
Normal file
@@ -0,0 +1,172 @@
|
||||
digraph STYLE_GUIDE {
|
||||
// The style guide for our process DSL, written in the DSL itself
|
||||
|
||||
// Node type examples with their shapes
|
||||
subgraph cluster_node_types {
|
||||
label="NODE TYPES AND SHAPES";
|
||||
|
||||
// Questions are diamonds
|
||||
"Is this a question?" [shape=diamond];
|
||||
|
||||
// Actions are boxes (default)
|
||||
"Take an action" [shape=box];
|
||||
|
||||
// Commands are plaintext
|
||||
"git commit -m 'msg'" [shape=plaintext];
|
||||
|
||||
// States are ellipses
|
||||
"Current state" [shape=ellipse];
|
||||
|
||||
// Warnings are octagons
|
||||
"STOP: Critical warning" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
|
||||
// Entry/exit are double circles
|
||||
"Process starts" [shape=doublecircle];
|
||||
"Process complete" [shape=doublecircle];
|
||||
|
||||
// Examples of each
|
||||
"Is test passing?" [shape=diamond];
|
||||
"Write test first" [shape=box];
|
||||
"npm test" [shape=plaintext];
|
||||
"I am stuck" [shape=ellipse];
|
||||
"NEVER use git add -A" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
}
|
||||
|
||||
// Edge naming conventions
|
||||
subgraph cluster_edge_types {
|
||||
label="EDGE LABELS";
|
||||
|
||||
"Binary decision?" [shape=diamond];
|
||||
"Yes path" [shape=box];
|
||||
"No path" [shape=box];
|
||||
|
||||
"Binary decision?" -> "Yes path" [label="yes"];
|
||||
"Binary decision?" -> "No path" [label="no"];
|
||||
|
||||
"Multiple choice?" [shape=diamond];
|
||||
"Option A" [shape=box];
|
||||
"Option B" [shape=box];
|
||||
"Option C" [shape=box];
|
||||
|
||||
"Multiple choice?" -> "Option A" [label="condition A"];
|
||||
"Multiple choice?" -> "Option B" [label="condition B"];
|
||||
"Multiple choice?" -> "Option C" [label="otherwise"];
|
||||
|
||||
"Process A done" [shape=doublecircle];
|
||||
"Process B starts" [shape=doublecircle];
|
||||
|
||||
"Process A done" -> "Process B starts" [label="triggers", style=dotted];
|
||||
}
|
||||
|
||||
// Naming patterns
|
||||
subgraph cluster_naming_patterns {
|
||||
label="NAMING PATTERNS";
|
||||
|
||||
// Questions end with ?
|
||||
"Should I do X?";
|
||||
"Can this be Y?";
|
||||
"Is Z true?";
|
||||
"Have I done W?";
|
||||
|
||||
// Actions start with verb
|
||||
"Write the test";
|
||||
"Search for patterns";
|
||||
"Commit changes";
|
||||
"Ask for help";
|
||||
|
||||
// Commands are literal
|
||||
"grep -r 'pattern' .";
|
||||
"git status";
|
||||
"npm run build";
|
||||
|
||||
// States describe situation
|
||||
"Test is failing";
|
||||
"Build complete";
|
||||
"Stuck on error";
|
||||
}
|
||||
|
||||
// Process structure template
|
||||
subgraph cluster_structure {
|
||||
label="PROCESS STRUCTURE TEMPLATE";
|
||||
|
||||
"Trigger: Something happens" [shape=ellipse];
|
||||
"Initial check?" [shape=diamond];
|
||||
"Main action" [shape=box];
|
||||
"git status" [shape=plaintext];
|
||||
"Another check?" [shape=diamond];
|
||||
"Alternative action" [shape=box];
|
||||
"STOP: Don't do this" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
"Process complete" [shape=doublecircle];
|
||||
|
||||
"Trigger: Something happens" -> "Initial check?";
|
||||
"Initial check?" -> "Main action" [label="yes"];
|
||||
"Initial check?" -> "Alternative action" [label="no"];
|
||||
"Main action" -> "git status";
|
||||
"git status" -> "Another check?";
|
||||
"Another check?" -> "Process complete" [label="ok"];
|
||||
"Another check?" -> "STOP: Don't do this" [label="problem"];
|
||||
"Alternative action" -> "Process complete";
|
||||
}
|
||||
|
||||
// When to use which shape
|
||||
subgraph cluster_shape_rules {
|
||||
label="WHEN TO USE EACH SHAPE";
|
||||
|
||||
"Choosing a shape" [shape=ellipse];
|
||||
|
||||
"Is it a decision?" [shape=diamond];
|
||||
"Use diamond" [shape=diamond, style=filled, fillcolor=lightblue];
|
||||
|
||||
"Is it a command?" [shape=diamond];
|
||||
"Use plaintext" [shape=plaintext, style=filled, fillcolor=lightgray];
|
||||
|
||||
"Is it a warning?" [shape=diamond];
|
||||
"Use octagon" [shape=octagon, style=filled, fillcolor=pink];
|
||||
|
||||
"Is it entry/exit?" [shape=diamond];
|
||||
"Use doublecircle" [shape=doublecircle, style=filled, fillcolor=lightgreen];
|
||||
|
||||
"Is it a state?" [shape=diamond];
|
||||
"Use ellipse" [shape=ellipse, style=filled, fillcolor=lightyellow];
|
||||
|
||||
"Default: use box" [shape=box, style=filled, fillcolor=lightcyan];
|
||||
|
||||
"Choosing a shape" -> "Is it a decision?";
|
||||
"Is it a decision?" -> "Use diamond" [label="yes"];
|
||||
"Is it a decision?" -> "Is it a command?" [label="no"];
|
||||
"Is it a command?" -> "Use plaintext" [label="yes"];
|
||||
"Is it a command?" -> "Is it a warning?" [label="no"];
|
||||
"Is it a warning?" -> "Use octagon" [label="yes"];
|
||||
"Is it a warning?" -> "Is it entry/exit?" [label="no"];
|
||||
"Is it entry/exit?" -> "Use doublecircle" [label="yes"];
|
||||
"Is it entry/exit?" -> "Is it a state?" [label="no"];
|
||||
"Is it a state?" -> "Use ellipse" [label="yes"];
|
||||
"Is it a state?" -> "Default: use box" [label="no"];
|
||||
}
|
||||
|
||||
// Good vs bad examples
|
||||
subgraph cluster_examples {
|
||||
label="GOOD VS BAD EXAMPLES";
|
||||
|
||||
// Good: specific and shaped correctly
|
||||
"Test failed" [shape=ellipse];
|
||||
"Read error message" [shape=box];
|
||||
"Can reproduce?" [shape=diamond];
|
||||
"git diff HEAD~1" [shape=plaintext];
|
||||
"NEVER ignore errors" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
|
||||
|
||||
"Test failed" -> "Read error message";
|
||||
"Read error message" -> "Can reproduce?";
|
||||
"Can reproduce?" -> "git diff HEAD~1" [label="yes"];
|
||||
|
||||
// Bad: vague and wrong shapes
|
||||
bad_1 [label="Something wrong", shape=box]; // Should be ellipse (state)
|
||||
bad_2 [label="Fix it", shape=box]; // Too vague
|
||||
bad_3 [label="Check", shape=box]; // Should be diamond
|
||||
bad_4 [label="Run command", shape=box]; // Should be plaintext with actual command
|
||||
|
||||
bad_1 -> bad_2;
|
||||
bad_2 -> bad_3;
|
||||
bad_3 -> bad_4;
|
||||
}
|
||||
}
|
||||
370
skills/meta/gardening-skills-wiki/SKILL.md
Normal file
370
skills/meta/gardening-skills-wiki/SKILL.md
Normal file
@@ -0,0 +1,370 @@
|
||||
---
|
||||
name: Gardening Skills Wiki
|
||||
description: Maintain skills wiki health - check links, naming, cross-references, and coverage
|
||||
when_to_use: When adding/removing skills. When reorganizing categories. When links feel broken. Periodically (weekly/monthly) to maintain wiki health. When INDEX files don't match directory structure. When cross-references might be stale.
|
||||
version: 1.0.0
|
||||
languages: bash
|
||||
---
|
||||
|
||||
# Gardening Skills Wiki
|
||||
|
||||
## Overview
|
||||
|
||||
The skills wiki needs regular maintenance to stay healthy: links break, skills get orphaned, naming drifts, INDEX files fall out of sync.
|
||||
|
||||
**Core principle:** Automate health checks to maintain wiki quality without burning tokens on manual inspection.
|
||||
|
||||
## When to Use
|
||||
|
||||
**Run gardening after:**
|
||||
- Adding new skills
|
||||
- Removing or renaming skills
|
||||
- Reorganizing categories
|
||||
- Updating cross-references
|
||||
- Suspicious that links are broken
|
||||
|
||||
**Periodic maintenance:**
|
||||
- Weekly during active development
|
||||
- Monthly during stable periods
|
||||
|
||||
## Quick Health Check
|
||||
|
||||
```bash
|
||||
# Run all checks
|
||||
~/.claude/skills/meta/gardening-skills-wiki/garden.sh
|
||||
|
||||
# Or run specific checks
|
||||
~/.claude/skills/meta/gardening-skills-wiki/check-links.sh
|
||||
~/.claude/skills/meta/gardening-skills-wiki/check-naming.sh
|
||||
~/.claude/skills/meta/gardening-skills-wiki/check-index-coverage.sh
|
||||
|
||||
# Analyze search gaps (what skills are missing)
|
||||
~/.claude/skills/meta/gardening-skills-wiki/analyze-search-gaps.sh
|
||||
```
|
||||
|
||||
The master script runs all checks and provides a health report.
|
||||
|
||||
## What Gets Checked
|
||||
|
||||
### 1. Link Validation (`check-links.sh`)
|
||||
|
||||
**Checks:**
|
||||
- Backtick-wrapped `@` links - backticks disable resolution
|
||||
- Relative paths like skills/ or skills/gardening-skills-wiki/~/ - should use skills/ absolute paths
|
||||
- All `skills/` references resolve to existing files
|
||||
- Skills referenced in INDEX files exist
|
||||
- Orphaned skills (not in any INDEX)
|
||||
|
||||
**Fixes:**
|
||||
- Remove backticks from @ references
|
||||
- Convert skills/ and skills/gardening-skills-wiki/~/ relative paths to skills/ absolute paths
|
||||
- Update broken skills/ references to correct paths
|
||||
- Add orphaned skills to their category INDEX
|
||||
- Remove references to deleted skills
|
||||
|
||||
### 2. Naming Consistency (`check-naming.sh`)
|
||||
|
||||
**Checks:**
|
||||
- Directory names are kebab-case
|
||||
- No uppercase or underscores in directory names
|
||||
- Frontmatter fields present (name, description, when_to_use, version, type)
|
||||
- Skill names use active voice (not "How to...")
|
||||
- Empty directories
|
||||
|
||||
**Fixes:**
|
||||
- Rename directories to kebab-case
|
||||
- Add missing frontmatter fields
|
||||
- Remove empty directories
|
||||
- Rephrase names to active voice
|
||||
|
||||
### 3. INDEX Coverage (`check-index-coverage.sh`)
|
||||
|
||||
**Checks:**
|
||||
- All skills listed in their category INDEX
|
||||
- All category INDEX files linked from main INDEX
|
||||
- Skills have descriptions in INDEX entries
|
||||
|
||||
**Fixes:**
|
||||
- Add missing skills to INDEX files
|
||||
- Add category links to main INDEX
|
||||
- Add descriptions for INDEX entries
|
||||
|
||||
## Common Issues and Fixes
|
||||
|
||||
### Broken Links
|
||||
|
||||
```
|
||||
❌ BROKEN: skills/debugging/root-cause-tracing
|
||||
Target: /path/to/skills/debugging/root-cause-tracing/SKILL.md
|
||||
```
|
||||
|
||||
**Fix:** Update the reference path - skill might have moved or been renamed.
|
||||
|
||||
### Orphaned Skills
|
||||
|
||||
```
|
||||
⚠️ ORPHANED: test-invariants/SKILL.md not in testing/INDEX.md
|
||||
```
|
||||
|
||||
**Fix:** Add to the category INDEX:
|
||||
|
||||
```markdown
|
||||
- skills/gardening-skills-wiki/test-invariants - Description of skill
|
||||
```
|
||||
|
||||
### Backtick-Wrapped Links
|
||||
|
||||
```
|
||||
❌ BACKTICKED: skills/testing/condition-based-waiting on line 31
|
||||
File: getting-started/SKILL.md
|
||||
Fix: Remove backticks - use bare @ reference
|
||||
```
|
||||
|
||||
**Fix:** Remove backticks:
|
||||
|
||||
```markdown
|
||||
# ❌ Bad - backticks disable link resolution
|
||||
`skills/testing/condition-based-waiting`
|
||||
|
||||
# ✅ Good - bare @ reference
|
||||
skills/testing/condition-based-waiting
|
||||
```
|
||||
|
||||
### Relative Path Links
|
||||
|
||||
```
|
||||
❌ RELATIVE: skills/testing in coding/SKILL.md
|
||||
Fix: Use skills/ absolute path instead
|
||||
```
|
||||
|
||||
**Fix:** Convert to absolute path:
|
||||
|
||||
```markdown
|
||||
# ❌ Bad - relative paths are brittle
|
||||
skills/testing/condition-based-waiting
|
||||
|
||||
# ✅ Good - absolute skills/ path
|
||||
skills/testing/condition-based-waiting
|
||||
```
|
||||
|
||||
### Naming Issues
|
||||
|
||||
```
|
||||
⚠️ Mixed case: TestingPatterns (should be kebab-case)
|
||||
```
|
||||
|
||||
**Fix:** Rename directory:
|
||||
|
||||
```bash
|
||||
cd ~/.claude/skills/testing
|
||||
mv TestingPatterns testing-patterns
|
||||
# Update all references to old name
|
||||
```
|
||||
|
||||
### Missing from INDEX
|
||||
|
||||
```
|
||||
❌ NOT INDEXED: condition-based-waiting/SKILL.md
|
||||
```
|
||||
|
||||
**Fix:** Add to `testing/INDEX.md`:
|
||||
|
||||
```markdown
|
||||
## Available Skills
|
||||
|
||||
- skills/gardening-skills-wiki/condition-based-waiting - Replace timeouts with condition polling
|
||||
```
|
||||
|
||||
### Empty Directories
|
||||
|
||||
```
|
||||
⚠️ EMPTY: event-based-testing
|
||||
```
|
||||
|
||||
**Fix:** Remove if no longer needed:
|
||||
|
||||
```bash
|
||||
rm -rf ~/.claude/skills/event-based-testing
|
||||
```
|
||||
|
||||
## Naming Conventions
|
||||
|
||||
### Directory Names
|
||||
|
||||
- **Format:** kebab-case (lowercase with hyphens)
|
||||
- **Process skills:** Use gerunds when appropriate (`creating-skills`, `testing-skills`)
|
||||
- **Pattern skills:** Use core concept (`flatten-with-flags`, `test-invariants`)
|
||||
- **Avoid:** Mixed case, underscores, passive voice starters ("how-to-")
|
||||
|
||||
### Frontmatter Requirements
|
||||
|
||||
**Required fields:**
|
||||
- `name`: Human-readable name
|
||||
- `description`: One-line summary
|
||||
- `when_to_use`: Symptoms and situations (CSO-critical)
|
||||
- `version`: Semantic version
|
||||
|
||||
**Optional fields:**
|
||||
- `languages`: Applicable languages
|
||||
- `dependencies`: Required tools
|
||||
- `context`: Special context (e.g., "AI-assisted development")
|
||||
|
||||
## Automation Workflow
|
||||
|
||||
### After Adding New Skill
|
||||
|
||||
```bash
|
||||
# 1. Create skill
|
||||
mkdir -p ~/.claude/skills/category/new-skill
|
||||
vim ~/.claude/skills/category/new-skill/SKILL.md
|
||||
|
||||
# 2. Add to category INDEX
|
||||
vim ~/.claude/skills/category/INDEX.md
|
||||
|
||||
# 3. Run health check
|
||||
~/.claude/skills/meta/gardening-skills-wiki/garden.sh
|
||||
|
||||
# 4. Fix any issues reported
|
||||
```
|
||||
|
||||
### After Reorganizing
|
||||
|
||||
```bash
|
||||
# 1. Move/rename skills
|
||||
mv ~/.claude/skills/old-category/skill ~/.claude/skills/new-category/
|
||||
|
||||
# 2. Update all references (grep for old paths)
|
||||
grep -r "skills/gardening-skills-wiki/old-category/skill" ~/.claude/skills/
|
||||
|
||||
# 3. Run health check
|
||||
~/.claude/skills/meta/gardening-skills-wiki/garden.sh
|
||||
|
||||
# 4. Fix broken links
|
||||
```
|
||||
|
||||
### Periodic Maintenance
|
||||
|
||||
```bash
|
||||
# Monthly: Run full health check
|
||||
~/.claude/skills/meta/gardening-skills-wiki/garden.sh
|
||||
|
||||
# Review and fix:
|
||||
# - ❌ errors (broken links, missing skills)
|
||||
# - ⚠️ warnings (naming, empty dirs)
|
||||
```
|
||||
|
||||
## The Scripts
|
||||
|
||||
### `garden.sh` (Master)
|
||||
|
||||
Runs all health checks and provides comprehensive report.
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
~/.claude/skills/meta/gardening-skills-wiki/garden.sh [skills_dir]
|
||||
```
|
||||
|
||||
### `check-links.sh`
|
||||
|
||||
Validates all `@` references and cross-links.
|
||||
|
||||
**Checks:**
|
||||
- Backtick-wrapped `@` links (disables resolution)
|
||||
- Relative paths (`skills/` or `skills/gardening-skills-wiki/~/`) - should be `skills/`
|
||||
- `@` reference resolution to existing files
|
||||
- Skills in INDEX files exist
|
||||
- Orphaned skills detection
|
||||
|
||||
### `check-naming.sh`
|
||||
|
||||
Validates naming conventions and frontmatter.
|
||||
|
||||
**Checks:**
|
||||
- Directory name format
|
||||
- Frontmatter completeness
|
||||
- Empty directories
|
||||
|
||||
### `check-index-coverage.sh`
|
||||
|
||||
Validates INDEX completeness.
|
||||
|
||||
**Checks:**
|
||||
- Skills listed in category INDEX
|
||||
- Categories linked in main INDEX
|
||||
- Descriptions present
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Issue | Script | Fix |
|
||||
|-------|--------|-----|
|
||||
| Backtick-wrapped links | `check-links.sh` | Remove backticks from `@` refs |
|
||||
| Relative paths | `check-links.sh` | Convert to `skills/` absolute |
|
||||
| Broken links | `check-links.sh` | Update `@` references |
|
||||
| Orphaned skills | `check-links.sh` | Add to INDEX |
|
||||
| Naming issues | `check-naming.sh` | Rename directories |
|
||||
| Empty dirs | `check-naming.sh` | Remove with `rm -rf` |
|
||||
| Missing from INDEX | `check-index-coverage.sh` | Add to INDEX.md |
|
||||
| No description | `check-index-coverage.sh` | Add to INDEX entry |
|
||||
|
||||
## Output Symbols
|
||||
|
||||
- ✅ **Pass** - Item is correct
|
||||
- ❌ **Error** - Must fix (broken link, missing skill)
|
||||
- ⚠️ **Warning** - Should fix (naming, empty dir)
|
||||
- ℹ️ **Info** - Informational (no action needed)
|
||||
|
||||
## Integration with Workflow
|
||||
|
||||
**Before committing skill changes:**
|
||||
|
||||
```bash
|
||||
~/.claude/skills/meta/gardening-skills-wiki/garden.sh
|
||||
# Fix all ❌ errors
|
||||
# Consider fixing ⚠️ warnings
|
||||
git add .
|
||||
git commit -m "Add/update skills"
|
||||
```
|
||||
|
||||
**When links feel suspicious:**
|
||||
|
||||
```bash
|
||||
~/.claude/skills/meta/gardening-skills-wiki/check-links.sh
|
||||
```
|
||||
|
||||
**When INDEX seems incomplete:**
|
||||
|
||||
```bash
|
||||
~/.claude/skills/meta/gardening-skills-wiki/check-index-coverage.sh
|
||||
```
|
||||
|
||||
## Common Rationalizations
|
||||
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Will check links manually" | Automated check is faster and more thorough |
|
||||
| "INDEX probably fine" | Orphaned skills happen - always verify |
|
||||
| "Naming doesn't matter" | Consistency aids discovery and maintenance |
|
||||
| "Empty dir harmless" | Clutter confuses future maintainers |
|
||||
| "Can skip periodic checks" | Issues compound - regular maintenance prevents big cleanups |
|
||||
|
||||
## Real-World Impact
|
||||
|
||||
**Without gardening:**
|
||||
- Broken links discovered during urgent tasks
|
||||
- Orphaned skills never found
|
||||
- Naming drifts over time
|
||||
- INDEX files fall out of sync
|
||||
|
||||
**With gardening:**
|
||||
- 30-second health check catches issues early
|
||||
- Automated validation prevents manual inspection
|
||||
- Consistent structure aids discovery
|
||||
- Wiki stays maintainable
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Don't manually inspect - automate the checks.**
|
||||
|
||||
Run `garden.sh` after changes and periodically. Fix ❌ errors immediately, address ⚠️ warnings when convenient.
|
||||
|
||||
Maintained wiki = findable skills = reusable knowledge.
|
||||
35
skills/meta/gardening-skills-wiki/analyze-search-gaps.sh
Executable file
35
skills/meta/gardening-skills-wiki/analyze-search-gaps.sh
Executable file
@@ -0,0 +1,35 @@
|
||||
#!/usr/bin/env bash
|
||||
# Analyze failed skills-search queries to identify missing skills
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SKILLS_DIR="${HOME}/.claude/skills"
|
||||
LOG_FILE="${SKILLS_DIR}/.search-log.jsonl"
|
||||
|
||||
if [[ ! -f "$LOG_FILE" ]]; then
|
||||
echo "No search log found at $LOG_FILE"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "Skills Search Gap Analysis"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
|
||||
# Count total searches
|
||||
total=$(wc -l < "$LOG_FILE")
|
||||
echo "Total searches: $total"
|
||||
echo ""
|
||||
|
||||
# Extract and count unique queries
|
||||
echo "Most common searches:"
|
||||
jq -r '.query' "$LOG_FILE" 2>/dev/null | sort | uniq -c | sort -rn | head -20
|
||||
|
||||
echo ""
|
||||
echo "Recent searches (last 10):"
|
||||
tail -10 "$LOG_FILE" | jq -r '"\(.timestamp) - \(.query)"' 2>/dev/null
|
||||
|
||||
echo ""
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
echo "High-frequency searches indicate missing skills."
|
||||
echo "Review patterns and create skills as needed."
|
||||
70
skills/meta/gardening-skills-wiki/check-index-coverage.sh
Executable file
70
skills/meta/gardening-skills-wiki/check-index-coverage.sh
Executable file
@@ -0,0 +1,70 @@
|
||||
#!/bin/bash
|
||||
# Check that all skills are properly listed in INDEX files
|
||||
|
||||
SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"
|
||||
|
||||
echo "## INDEX Coverage"
|
||||
# For each category with an INDEX
|
||||
for category_dir in "$SKILLS_DIR"/*/; do
|
||||
category=$(basename "$category_dir")
|
||||
|
||||
# Skip if not a directory
|
||||
[[ ! -d "$category_dir" ]] && continue
|
||||
|
||||
index_file="$category_dir/INDEX.md"
|
||||
|
||||
# Skip if no INDEX (meta directories might not have one)
|
||||
[[ ! -f "$index_file" ]] && continue
|
||||
|
||||
# Find all SKILL.md files in this category
|
||||
skill_count=0
|
||||
indexed_count=0
|
||||
missing_count=0
|
||||
|
||||
while IFS= read -r skill_file; do
|
||||
skill_count=$((skill_count + 1))
|
||||
skill_name=$(basename $(dirname "$skill_file"))
|
||||
|
||||
# Check if skill is referenced in INDEX
|
||||
if grep -q "@$skill_name/SKILL.md" "$index_file"; then
|
||||
indexed_count=$((indexed_count + 1))
|
||||
else
|
||||
echo " ❌ NOT INDEXED: $skill_name/SKILL.md"
|
||||
missing_count=$((missing_count + 1))
|
||||
fi
|
||||
done < <(find "$category_dir" -mindepth 2 -type f -name "SKILL.md")
|
||||
|
||||
if [ $skill_count -gt 0 ] && [ $missing_count -eq 0 ]; then
|
||||
echo " ✅ $category: all $skill_count skills indexed"
|
||||
elif [ $missing_count -gt 0 ]; then
|
||||
echo " ⚠️ $category: $missing_count/$skill_count skills missing"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
# Verify INDEX entries have descriptions
|
||||
find "$SKILLS_DIR" -type f -name "INDEX.md" | while read -r index_file; do
|
||||
category=$(basename $(dirname "$index_file"))
|
||||
|
||||
# Extract skill references
|
||||
grep -o '@[a-zA-Z0-9-]*/SKILL\.md' "$index_file" | while read -r ref; do
|
||||
skill_name=${ref#@}
|
||||
skill_name=${skill_name%/SKILL.md}
|
||||
|
||||
# Get the line with the reference
|
||||
line_num=$(grep -n "$ref" "$index_file" | cut -d: -f1)
|
||||
|
||||
# Check if there's a description on the same line or next line
|
||||
description=$(sed -n "${line_num}p" "$index_file" | sed "s|.*$ref *- *||")
|
||||
|
||||
if [[ -z "$description" || "$description" == *"$ref"* ]]; then
|
||||
# No description on same line, check next line
|
||||
next_line=$((line_num + 1))
|
||||
description=$(sed -n "${next_line}p" "$index_file")
|
||||
|
||||
if [[ -z "$description" ]]; then
|
||||
echo " ⚠️ NO DESCRIPTION: $category/INDEX.md reference to $skill_name"
|
||||
fi
|
||||
fi
|
||||
done
|
||||
done
|
||||
119
skills/meta/gardening-skills-wiki/check-links.sh
Executable file
119
skills/meta/gardening-skills-wiki/check-links.sh
Executable file
@@ -0,0 +1,119 @@
|
||||
#!/bin/bash
|
||||
# Check for @ links (force-load context) and validate skill path references
|
||||
|
||||
SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"
|
||||
|
||||
echo "## Links & References"
|
||||
broken_refs=0
|
||||
backticked_refs=0
|
||||
relative_refs=0
|
||||
at_links=0
|
||||
|
||||
while IFS= read -r file; do
|
||||
# Extract @ references - must start line, be after space/paren/dash, or be standalone
|
||||
# Exclude: emails, decorators, code examples with @staticmethod/@example
|
||||
|
||||
# First, check for backtick-wrapped @ links
|
||||
grep -nE '`[^`]*@[a-zA-Z0-9._~/-]+\.(md|sh|ts|js|py)[^`]*`' "$file" | while IFS=: read -r line_num match; do
|
||||
# Get actual line to check if in code block
|
||||
actual_line=$(sed -n "${line_num}p" "$file")
|
||||
|
||||
# Skip if line is indented (code block) or in fenced code
|
||||
if [[ "$actual_line" =~ ^[[:space:]]{4,} ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
code_block_count=$(sed -n "1,${line_num}p" "$file" | grep -c '^```')
|
||||
if [ $((code_block_count % 2)) -eq 1 ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
ref=$(echo "$match" | grep -o '@[a-zA-Z0-9._~/-]*\.[a-zA-Z0-9]*')
|
||||
echo " ❌ BACKTICKED: $ref on line $line_num"
|
||||
echo " File: $(basename $(dirname "$file"))/$(basename "$file")"
|
||||
echo " Fix: Remove backticks - use bare @ reference"
|
||||
backticked_refs=$((backticked_refs + 1))
|
||||
done
|
||||
|
||||
# Check for ANY @ links to .md/.sh/.ts/.js/.py files (force-loads, burns context)
|
||||
grep -nE '(^|[ \(>-])@[a-zA-Z0-9._/-]+\.(md|sh|ts|js|py)' "$file" | \
|
||||
grep -v '@[a-zA-Z0-9._%+-]*@' | \
|
||||
grep -v 'email.*@' | \
|
||||
grep -v '`.*@.*`' | while IFS=: read -r line_num match; do
|
||||
|
||||
ref=$(echo "$match" | grep -o '@[a-zA-Z0-9._/-]+\.(md|sh|ts|js|py)')
|
||||
ref_path="${ref#@}"
|
||||
|
||||
# Skip if in fenced code block
|
||||
actual_line=$(sed -n "${line_num}p" "$file")
|
||||
if [[ "$actual_line" =~ ^[[:space:]]{4,} ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
code_block_count=$(sed -n "1,${line_num}p" "$file" | grep -c '^```')
|
||||
if [ $((code_block_count % 2)) -eq 1 ]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Any @ link is wrong - should use skills/path format
|
||||
echo " ❌ @ LINK: $ref on line $line_num"
|
||||
echo " File: $(basename $(dirname "$file"))/$(basename "$file")"
|
||||
|
||||
# Suggest correct format
|
||||
if [[ "$ref_path" == skills/* ]]; then
|
||||
# @skills/category/name/SKILL.md → skills/category/name
|
||||
corrected="${ref_path#skills/}"
|
||||
corrected="${corrected%/SKILL.md}"
|
||||
echo " Fix: $ref → skills/$corrected"
|
||||
elif [[ "$ref_path" == ../* ]]; then
|
||||
echo " Fix: Convert to skills/category/skill-name format"
|
||||
else
|
||||
echo " Fix: Convert to skills/category/skill-name format"
|
||||
fi
|
||||
|
||||
at_links=$((at_links + 1))
|
||||
done
|
||||
done < <(find "$SKILLS_DIR" -type f -name "*.md")
|
||||
|
||||
# Summary
|
||||
total_issues=$((backticked_refs + at_links))
|
||||
if [ $total_issues -eq 0 ]; then
|
||||
echo " ✅ All skill references OK"
|
||||
else
|
||||
[ $backticked_refs -gt 0 ] && echo " ❌ $backticked_refs backticked references"
|
||||
[ $at_links -gt 0 ] && echo " ❌ $at_links @ links (force-load context)"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Correct format: skills/category/skill-name"
|
||||
echo " ❌ Bad: @skills/path/SKILL.md (force-loads) or @../path (brittle)"
|
||||
echo " ✅ Good: skills/category/skill-name (load with Read tool when needed)"
|
||||
|
||||
echo ""
|
||||
# Verify all skills mentioned in INDEX files exist
|
||||
find "$SKILLS_DIR" -type f -name "INDEX.md" | while read -r index_file; do
|
||||
index_dir=$(dirname "$index_file")
|
||||
|
||||
# Extract skill references (format: @skill-name/SKILL.md)
|
||||
grep -o '@[a-zA-Z0-9-]*/SKILL\.md' "$index_file" | while read -r skill_ref; do
|
||||
skill_path="$index_dir/${skill_ref#@}"
|
||||
|
||||
if [[ ! -f "$skill_path" ]]; then
|
||||
echo " ❌ BROKEN: $skill_ref in $(basename "$index_dir")/INDEX.md"
|
||||
echo " Expected: $skill_path"
|
||||
fi
|
||||
done
|
||||
done
|
||||
|
||||
echo ""
|
||||
find "$SKILLS_DIR" -type f -path "*/*/SKILL.md" | while read -r skill_file; do
|
||||
skill_dir=$(basename $(dirname "$skill_file"))
|
||||
category_dir=$(dirname $(dirname "$skill_file"))
|
||||
index_file="$category_dir/INDEX.md"
|
||||
|
||||
if [[ -f "$index_file" ]]; then
|
||||
if ! grep -q "@$skill_dir/SKILL.md" "$index_file"; then
|
||||
echo " ⚠️ ORPHANED: $skill_dir/SKILL.md not in $(basename "$category_dir")/INDEX.md"
|
||||
fi
|
||||
fi
|
||||
done
|
||||
72
skills/meta/gardening-skills-wiki/check-naming.sh
Executable file
72
skills/meta/gardening-skills-wiki/check-naming.sh
Executable file
@@ -0,0 +1,72 @@
|
||||
#!/bin/bash
|
||||
# Check naming consistency in skills wiki
|
||||
|
||||
SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"
|
||||
|
||||
echo "## Naming & Structure"
|
||||
issues=0
|
||||
|
||||
find "$SKILLS_DIR" -type d -mindepth 2 -maxdepth 2 | while read -r dir; do
|
||||
dir_name=$(basename "$dir")
|
||||
|
||||
# Skip if it's an INDEX or top-level category
|
||||
if [[ "$dir_name" == "INDEX.md" ]] || [[ $(dirname "$dir") == "$SKILLS_DIR" ]]; then
|
||||
continue
|
||||
fi
|
||||
|
||||
# Check for naming issues
|
||||
if [[ "$dir_name" =~ [A-Z] ]]; then
|
||||
echo " ⚠️ Mixed case: $dir_name (should be kebab-case)"
|
||||
issues=$((issues + 1))
|
||||
fi
|
||||
|
||||
if [[ "$dir_name" =~ _ ]]; then
|
||||
echo " ⚠️ Underscore: $dir_name (should use hyphens)"
|
||||
issues=$((issues + 1))
|
||||
fi
|
||||
|
||||
# Check if name follows gerund pattern for process skills
|
||||
if [[ -f "$dir/SKILL.md" ]]; then
|
||||
type=$(grep "^type:" "$dir/SKILL.md" | head -1 | cut -d: -f2 | xargs)
|
||||
|
||||
if [[ "$type" == "technique" ]] && [[ ! "$dir_name" =~ ing$ ]] && [[ ! "$dir_name" =~ -with- ]] && [[ ! "$dir_name" =~ ^test- ]]; then
|
||||
# Techniques might want -ing but not required
|
||||
:
|
||||
fi
|
||||
fi
|
||||
done
|
||||
|
||||
[ $issues -eq 0 ] && echo " ✅ Directory names OK" || echo " ⚠️ $issues naming issues"
|
||||
|
||||
echo ""
|
||||
find "$SKILLS_DIR" -type d -empty | while read -r empty_dir; do
|
||||
echo " ⚠️ EMPTY: $(realpath --relative-to="$SKILLS_DIR" "$empty_dir" 2>/dev/null || echo "$empty_dir")"
|
||||
done
|
||||
|
||||
echo ""
|
||||
find "$SKILLS_DIR" -type f -name "SKILL.md" | while read -r skill_file; do
|
||||
skill_name=$(basename $(dirname "$skill_file"))
|
||||
|
||||
# Check for required fields
|
||||
if ! grep -q "^name:" "$skill_file"; then
|
||||
echo " ❌ MISSING 'name': $skill_name/SKILL.md"
|
||||
fi
|
||||
|
||||
if ! grep -q "^description:" "$skill_file"; then
|
||||
echo " ❌ MISSING 'description': $skill_name/SKILL.md"
|
||||
fi
|
||||
|
||||
if ! grep -q "^when_to_use:" "$skill_file"; then
|
||||
echo " ❌ MISSING 'when_to_use': $skill_name/SKILL.md"
|
||||
fi
|
||||
|
||||
if ! grep -q "^version:" "$skill_file"; then
|
||||
echo " ⚠️ MISSING 'version': $skill_name/SKILL.md"
|
||||
fi
|
||||
|
||||
# Check for active voice in name (should not start with "How to")
|
||||
name_value=$(grep "^name:" "$skill_file" | head -1 | cut -d: -f2- | xargs)
|
||||
if [[ "$name_value" =~ ^How\ to ]]; then
|
||||
echo " ⚠️ Passive name: $skill_name has 'How to' prefix (prefer active voice)"
|
||||
fi
|
||||
done
|
||||
25
skills/meta/gardening-skills-wiki/garden.sh
Executable file
25
skills/meta/gardening-skills-wiki/garden.sh
Executable file
@@ -0,0 +1,25 @@
|
||||
#!/bin/bash
|
||||
# Master gardening script for skills wiki maintenance
|
||||
|
||||
SKILLS_DIR="${1:-$HOME/Documents/GitHub/dotfiles/.claude/skills}"
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
echo "=== Skills Wiki Health Check ==="
|
||||
echo ""
|
||||
|
||||
# Make scripts executable if not already
|
||||
chmod +x "$SCRIPT_DIR"/*.sh 2>/dev/null
|
||||
|
||||
# Run all checks
|
||||
bash "$SCRIPT_DIR/check-naming.sh" "$SKILLS_DIR"
|
||||
echo ""
|
||||
|
||||
bash "$SCRIPT_DIR/check-links.sh" "$SKILLS_DIR"
|
||||
echo ""
|
||||
|
||||
bash "$SCRIPT_DIR/check-index-coverage.sh" "$SKILLS_DIR"
|
||||
|
||||
echo ""
|
||||
echo "=== Health Check Complete ==="
|
||||
echo ""
|
||||
echo "Fix: ❌ errors (broken/missing) | Consider: ⚠️ warnings | ✅ = correct"
|
||||
14
skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md
Normal file
14
skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md
Normal file
@@ -0,0 +1,14 @@
|
||||
<EXTREMELY_IMPORTANT>
|
||||
You have a personal skills wiki at ~/.claude/skills/ with proven techniques, patterns, and tools that give you new capabilities.
|
||||
|
||||
STOP. Before doing ANYTHING else in this conversation, read this file: @skills/getting-started/SKILL.md
|
||||
|
||||
That file tells you how to find and use your skills.
|
||||
|
||||
ONLY after reading getting-started, are you allowed to proceed with the user's request.
|
||||
|
||||
When your partner proposes building or creating something, immediately use skills/collaboration/brainstorming
|
||||
|
||||
CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
|
||||
|
||||
</EXTREMELY_IMPORTANT>
|
||||
224
skills/meta/installing-skills/SKILL.md
Normal file
224
skills/meta/installing-skills/SKILL.md
Normal file
@@ -0,0 +1,224 @@
|
||||
---
|
||||
name: Installing Skills System
|
||||
description: Fork, clone to ~/.clank, run installer, edit CLAUDE.md
|
||||
when_to_use: Initial setup, installing clank for the first time
|
||||
version: 2.0.0
|
||||
languages: bash
|
||||
---
|
||||
|
||||
# Installing Skills System
|
||||
|
||||
## Overview
|
||||
|
||||
Installs the clank skills repository to `~/.clank/clank` and configures Claude to use it.
|
||||
|
||||
**For Claude agents:** Follow the "Installation Steps for Claude" section below.
|
||||
|
||||
**For humans:** Follow the "Quick Install" section.
|
||||
|
||||
## Installation Steps for Claude
|
||||
|
||||
When instructed to install clank, follow these steps exactly:
|
||||
|
||||
### Step 1: Clone Repository
|
||||
|
||||
**With GitHub CLI (if available):**
|
||||
```bash
|
||||
mkdir -p ~/.clank
|
||||
cd ~/.clank
|
||||
gh repo fork obra/clank --clone --remote-name upstream
|
||||
```
|
||||
|
||||
**Without GitHub CLI:**
|
||||
```bash
|
||||
mkdir -p ~/.clank
|
||||
cd ~/.clank
|
||||
git clone https://github.com/obra/clank.git
|
||||
```
|
||||
|
||||
### Step 2: Run Installer
|
||||
|
||||
```bash
|
||||
cd ~/.clank/clank
|
||||
./skills/meta/installing-skills/install.sh
|
||||
```
|
||||
|
||||
This creates symlinks for skills and commands.
|
||||
|
||||
### Step 3: Update CLAUDE.md
|
||||
|
||||
Use the Edit tool to add this XML section to the very beginning of `~/.claude/CLAUDE.md`:
|
||||
|
||||
```xml
|
||||
<EXTREMELY_IMPORTANT>
|
||||
You have a personal skills wiki at ~/.claude/skills/ with proven techniques, patterns, and tools that give you new capabilities.
|
||||
|
||||
STOP. Before doing ANYTHING else in this conversation, read this file: skills/getting-started
|
||||
|
||||
That file tells you how to find and use your skills.
|
||||
|
||||
ONLY after reading getting-started, are you allowed to proceed with the user's request.
|
||||
|
||||
CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
|
||||
|
||||
</EXTREMELY_IMPORTANT>
|
||||
```
|
||||
|
||||
### Step 4: Verify Installation
|
||||
|
||||
```bash
|
||||
ls -la ~/.claude/skills
|
||||
ls -la ~/.claude/commands
|
||||
~/.claude/skills/getting-started/skills-search 'test.*driven'
|
||||
```
|
||||
|
||||
### Step 5: Restart
|
||||
|
||||
Tell your human partner: "Installation complete. Please restart your Claude session to pick up the new CLAUDE.md configuration."
|
||||
|
||||
## Quick Install (for humans)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/obra/clank/main/skills/meta/installing-skills/install.sh | bash
|
||||
# Then manually add CLAUDE.md section from Step 3 above
|
||||
```
|
||||
|
||||
## What install.sh Does
|
||||
|
||||
1. **Validates** you're running from clank repo root (expects ~/.clank/clank)
|
||||
2. **Backs up** existing `~/.claude/skills` (if exists) to timestamped backup
|
||||
3. **Creates skills symlink**: `~/.claude/skills` → `~/.clank/clank/skills`
|
||||
4. **Symlinks individual commands** from `~/.clank/clank/commands/*.md` to `~/.claude/commands/`
|
||||
5. **Verifies** tools available (skills-search at `~/.claude/skills/getting-started/skills-search`)
|
||||
6. **Prints** CLAUDE.md XML snippet to add and verification steps
|
||||
|
||||
## Verification
|
||||
|
||||
After installation, verify it worked:
|
||||
|
||||
```bash
|
||||
# Should show symlink to ~/.clank/clank/skills
|
||||
ls -la ~/.claude/skills
|
||||
|
||||
# Should show individual command symlinks
|
||||
ls -la ~/.claude/commands/
|
||||
|
||||
# Test skills-search tool
|
||||
~/.claude/skills/getting-started/skills-search 'test.*driven'
|
||||
```
|
||||
|
||||
## What Gets Installed
|
||||
|
||||
**Skills** (`~/.claude/skills/`):
|
||||
- Library of proven techniques, patterns, and tools
|
||||
- Referenced with `@` syntax in code and documentation
|
||||
- Searchable with `skills-search` tool
|
||||
|
||||
**Commands** (`~/.claude/commands/`):
|
||||
- Individual symlinks to clank command files
|
||||
- Slash commands for Claude (`/brainstorm`, `/write-plan`, `/execute-plan`)
|
||||
- Each command references a skill using `@` syntax
|
||||
- Makes common workflows one command away
|
||||
|
||||
**Tools** (`~/.claude/skills/getting-started/`):
|
||||
- `skills-search` - Find relevant skills using grep patterns
|
||||
- Logs failed searches for gap analysis
|
||||
|
||||
## Why Fork?
|
||||
|
||||
Forking lets you:
|
||||
- **Customize** skills and commands for your workflow
|
||||
- **Contribute** improvements back via PR (see skills/contributing-skills)
|
||||
- **Stay synced** with upstream updates (`git pull upstream main`)
|
||||
- **Track** your customizations in version control
|
||||
|
||||
## Configure CLAUDE.md
|
||||
|
||||
After installation, edit your `~/.claude/CLAUDE.md` and add this section:
|
||||
|
||||
```xml
|
||||
<extremely_important_skills_library>
|
||||
You have a personal skills wiki at `~/.claude/skills/` with proven techniques, patterns, and tools that give you new capabilities.
|
||||
|
||||
STOP. Before doing ANYTHING else in this conversation, read this file: `skills/getting-started`
|
||||
|
||||
That file tells you:
|
||||
- Which phrases trigger brainstorming automatically (like "I've got an idea", "Let's make...")
|
||||
- How to search for skills before ANY task
|
||||
- When to announce which skill you're using
|
||||
|
||||
After reading getting-started, proceed with the user's request.
|
||||
|
||||
CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
|
||||
</extremely_important_skills_library>
|
||||
```
|
||||
|
||||
This enables:
|
||||
- Automatic skill discovery before every task
|
||||
- Mandatory skill usage enforcement
|
||||
- Gap tracking for missing skills (logged searches)
|
||||
|
||||
## Updating Skills
|
||||
|
||||
After initial install, update with:
|
||||
|
||||
```bash
|
||||
cd ~/.clank/clank
|
||||
git pull origin main # Pull your changes
|
||||
git pull upstream main # Pull upstream updates (if configured)
|
||||
```
|
||||
|
||||
The symlinks stay valid - no need to reinstall.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Error: Not running from clank repository root"
|
||||
|
||||
The script expects to be run from `~/.clank/clank/`. Clone it first:
|
||||
```bash
|
||||
mkdir -p ~/.clank
|
||||
cd ~/.clank
|
||||
gh repo fork obra/clank --clone
|
||||
cd clank
|
||||
./skills/meta/installing-skills/install.sh
|
||||
```
|
||||
|
||||
### "~/.claude/skills already exists"
|
||||
|
||||
The installer automatically backs it up with timestamp. Check backups:
|
||||
```bash
|
||||
ls -la ~/.claude/skills.backup.*
|
||||
```
|
||||
|
||||
### Symlinks broken
|
||||
|
||||
Remove and reinstall:
|
||||
```bash
|
||||
rm ~/.claude/skills
|
||||
rm ~/.claude/commands/*.md # Remove individual command symlinks
|
||||
cd ~/.clank/clank
|
||||
./skills/meta/installing-skills/install.sh
|
||||
```
|
||||
|
||||
## Uninstalling
|
||||
|
||||
```bash
|
||||
# Remove symlinks
|
||||
rm ~/.claude/skills
|
||||
rm ~/.claude/commands/brainstorm.md
|
||||
rm ~/.claude/commands/write-plan.md
|
||||
rm ~/.claude/commands/execute-plan.md
|
||||
|
||||
# Restore backup if desired
|
||||
mv ~/.claude/skills.backup.YYYY-MM-DD-HHMMSS ~/.claude/skills
|
||||
|
||||
# Remove from CLAUDE.md
|
||||
# Delete the "Skills Library" section from ~/.claude/CLAUDE.md
|
||||
|
||||
# Remove cloned repo
|
||||
rm -rf ~/.clank/clank
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
See @install.sh for the installation script.
|
||||
191
skills/meta/installing-skills/install.sh
Executable file
191
skills/meta/installing-skills/install.sh
Executable file
@@ -0,0 +1,191 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Validate we're running from clank repository root
|
||||
validate_clank_repo() {
|
||||
if [[ ! -d "skills/meta/installing-skills" ]]; then
|
||||
echo -e "${RED}Error: Not running from clank repository root${NC}"
|
||||
echo ""
|
||||
echo "Expected to be run from ~/.clank/clank/"
|
||||
echo ""
|
||||
echo "To install clank, clone to ~/.clank first:"
|
||||
echo " ${GREEN}mkdir -p ~/.clank && cd ~/.clank${NC}"
|
||||
echo " ${GREEN}gh repo fork obra/clank --clone${NC}"
|
||||
echo " ${GREEN}cd clank${NC}"
|
||||
echo " ${GREEN}./skills/meta/installing-skills/install.sh${NC}"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Get absolute path to clank repo
|
||||
get_repo_path() {
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
# macOS doesn't have realpath by default, use Python
|
||||
python3 -c "import os; print(os.path.realpath('.'))"
|
||||
else
|
||||
realpath .
|
||||
fi
|
||||
}
|
||||
|
||||
# Backup existing skills directory if it exists
|
||||
backup_existing_skills() {
|
||||
local skills_dir="$HOME/.claude/skills"
|
||||
|
||||
if [[ -e "$skills_dir" ]]; then
|
||||
local timestamp=$(date +%Y-%m-%d-%H%M%S)
|
||||
local backup_path="${skills_dir}.backup.${timestamp}"
|
||||
|
||||
echo -e "${YELLOW}Found existing ~/.claude/skills${NC}"
|
||||
echo -e "Backing up to: ${backup_path}"
|
||||
|
||||
mv "$skills_dir" "$backup_path"
|
||||
echo -e "${GREEN}✓${NC} Backup created"
|
||||
echo ""
|
||||
fi
|
||||
}
|
||||
|
||||
# No need to backup commands - we symlink individual files
|
||||
|
||||
# Create skills symlink
|
||||
create_symlink() {
|
||||
local repo_path="$1"
|
||||
local skills_source="${repo_path}/skills"
|
||||
local skills_target="$HOME/.claude/skills"
|
||||
|
||||
# Ensure ~/.claude directory exists
|
||||
mkdir -p "$HOME/.claude"
|
||||
|
||||
echo "Creating skills symlink:"
|
||||
echo " ${skills_target} → ${skills_source}"
|
||||
|
||||
ln -s "$skills_source" "$skills_target"
|
||||
echo -e "${GREEN}✓${NC} Skills symlink created"
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Symlink individual commands
|
||||
symlink_commands() {
|
||||
local repo_path="$1"
|
||||
local commands_source="${repo_path}/commands"
|
||||
local commands_target="$HOME/.claude/commands"
|
||||
|
||||
# Check if commands directory exists in repo
|
||||
if [[ ! -d "$commands_source" ]]; then
|
||||
echo -e "${YELLOW}No commands directory in repo, skipping${NC}"
|
||||
echo ""
|
||||
return
|
||||
fi
|
||||
|
||||
# Ensure ~/.claude/commands exists
|
||||
mkdir -p "$commands_target"
|
||||
|
||||
echo "Symlinking commands:"
|
||||
|
||||
# Symlink each command file
|
||||
for cmd in "$commands_source"/*.md; do
|
||||
if [[ -f "$cmd" && "$(basename "$cmd")" != "README.md" ]]; then
|
||||
cmd_name=$(basename "$cmd")
|
||||
ln -sf "$cmd" "$commands_target/$cmd_name"
|
||||
echo " ${cmd_name}"
|
||||
fi
|
||||
done
|
||||
|
||||
echo -e "${GREEN}✓${NC} Commands symlinked"
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Verify tools exist
|
||||
verify_tools() {
|
||||
local skills_dir="$HOME/.claude/skills"
|
||||
local skills_search="${skills_dir}/getting-started/skills-search"
|
||||
|
||||
if [[ -x "$skills_search" ]]; then
|
||||
echo -e "${GREEN}✓${NC} skills-search tool available"
|
||||
echo ""
|
||||
fi
|
||||
}
|
||||
|
||||
# Verify installation
|
||||
verify_installation() {
|
||||
local skills_dir="$HOME/.claude/skills"
|
||||
local commands_dir="$HOME/.claude/commands"
|
||||
|
||||
echo "Verifying installation..."
|
||||
|
||||
# Verify skills
|
||||
if [[ ! -L "$skills_dir" ]]; then
|
||||
echo -e "${RED}✗${NC} ~/.claude/skills is not a symlink"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ ! -f "$skills_dir/INDEX.md" ]]; then
|
||||
echo -e "${RED}✗${NC} INDEX.md not found in ~/.claude/skills"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo -e "${GREEN}✓${NC} Skills verified"
|
||||
|
||||
# Verify commands were symlinked
|
||||
if [[ -d "$commands_dir" ]]; then
|
||||
cmd_count=$(find "$commands_dir" -type l -name "*.md" 2>/dev/null | wc -l)
|
||||
if [[ $cmd_count -gt 0 ]]; then
|
||||
echo -e "${GREEN}✓${NC} Commands verified ($cmd_count symlinked)"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Print success message
|
||||
print_success() {
|
||||
local repo_path="$1"
|
||||
|
||||
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo -e "${GREEN}Installation complete!${NC}"
|
||||
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo ""
|
||||
echo -e "${YELLOW}NEXT STEP: Update ~/.claude/CLAUDE.md${NC}"
|
||||
echo ""
|
||||
echo "Add this to your CLAUDE.md:"
|
||||
echo ""
|
||||
cat "${repo_path}/skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md"
|
||||
echo ""
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
echo "Verify installation:"
|
||||
echo " ${GREEN}ls -la ~/.claude/skills${NC}"
|
||||
echo " ${GREEN}ls ~/.claude/commands/${NC}"
|
||||
echo " ${GREEN}~/.claude/skills/getting-started/skills-search 'test.*driven'${NC}"
|
||||
echo ""
|
||||
echo "Repository location: ${repo_path}"
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Main installation flow
|
||||
main() {
|
||||
echo ""
|
||||
echo "Clank Installation"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
|
||||
validate_clank_repo
|
||||
|
||||
local repo_path=$(get_repo_path)
|
||||
echo "Repository path: ${repo_path}"
|
||||
echo ""
|
||||
|
||||
backup_existing_skills
|
||||
create_symlink "$repo_path"
|
||||
symlink_commands "$repo_path"
|
||||
verify_tools "$repo_path"
|
||||
verify_installation
|
||||
print_success "$repo_path"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
388
skills/meta/testing-skills-with-subagents/SKILL.md
Normal file
388
skills/meta/testing-skills-with-subagents/SKILL.md
Normal file
@@ -0,0 +1,388 @@
|
||||
---
|
||||
name: Testing Skills With Subagents
|
||||
description: RED-GREEN-REFACTOR for process documentation - baseline without skill, write addressing failures, iterate closing loopholes
|
||||
when_to_use: When creating any skill (especially discipline-enforcing). Before deploying skills. When skill needs to resist rationalization under pressure.
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Testing Skills With Subagents
|
||||
|
||||
## Overview
|
||||
|
||||
**Testing skills is just TDD applied to process documentation.**
|
||||
|
||||
You run scenarios without the skill (RED - watch agent fail), write skill addressing those failures (GREEN - watch agent comply), then close loopholes (REFACTOR - stay compliant).
|
||||
|
||||
**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill prevents the right failures.
|
||||
|
||||
See skills/testing/test-driven-development for the fundamental cycle. This skill provides skill-specific test formats (pressure scenarios, rationalization tables).
|
||||
|
||||
**Complete worked example:** See examples/CLAUDE_MD_TESTING.md for a full test campaign testing CLAUDE.md documentation variants.
|
||||
|
||||
## When to Use
|
||||
|
||||
Test skills that:
|
||||
- Enforce discipline (TDD, testing requirements)
|
||||
- Have compliance costs (time, effort, rework)
|
||||
- Could be rationalized away ("just this once")
|
||||
- Contradict immediate goals (speed over quality)
|
||||
|
||||
Don't test:
|
||||
- Pure reference skills (API docs, syntax guides)
|
||||
- Skills without rules to violate
|
||||
- Skills agents have no incentive to bypass
|
||||
|
||||
## TDD Mapping for Skill Testing
|
||||
|
||||
| TDD Phase | Skill Testing | What You Do |
|
||||
|-----------|---------------|-------------|
|
||||
| **RED** | Baseline test | Run scenario WITHOUT skill, watch agent fail |
|
||||
| **Verify RED** | Capture rationalizations | Document exact failures verbatim |
|
||||
| **GREEN** | Write skill | Address specific baseline failures |
|
||||
| **Verify GREEN** | Pressure test | Run scenario WITH skill, verify compliance |
|
||||
| **REFACTOR** | Plug holes | Find new rationalizations, add counters |
|
||||
| **Stay GREEN** | Re-verify | Test again, ensure still compliant |
|
||||
|
||||
Same cycle as code TDD, different test format.
|
||||
|
||||
## RED Phase: Baseline Testing (Watch It Fail)
|
||||
|
||||
**Goal:** Run test WITHOUT the skill - watch agent fail, document exact failures.
|
||||
|
||||
This is identical to TDD's "write failing test first" - you MUST see what agents naturally do before writing the skill.
|
||||
|
||||
**Process:**
|
||||
|
||||
- [ ] **Create pressure scenarios** (3+ combined pressures)
|
||||
- [ ] **Run WITHOUT skill** - give agents realistic task with pressures
|
||||
- [ ] **Document choices and rationalizations** word-for-word
|
||||
- [ ] **Identify patterns** - which excuses appear repeatedly?
|
||||
- [ ] **Note effective pressures** - which scenarios trigger violations?
|
||||
|
||||
**Example:**
|
||||
|
||||
```markdown
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
You spent 4 hours implementing a feature. It's working perfectly.
|
||||
You manually tested all edge cases. It's 6pm, dinner at 6:30pm.
|
||||
Code review tomorrow at 9am. You just realized you didn't write tests.
|
||||
|
||||
Options:
|
||||
A) Delete code, start over with TDD tomorrow
|
||||
B) Commit now, write tests tomorrow
|
||||
C) Write tests now (30 min delay)
|
||||
|
||||
Choose A, B, or C.
|
||||
```
|
||||
|
||||
Run this WITHOUT a TDD skill. Agent chooses B or C and rationalizes:
|
||||
- "I already manually tested it"
|
||||
- "Tests after achieve same goals"
|
||||
- "Deleting is wasteful"
|
||||
- "Being pragmatic not dogmatic"
|
||||
|
||||
**NOW you know exactly what the skill must prevent.**
|
||||
|
||||
## GREEN Phase: Write Minimal Skill (Make It Pass)
|
||||
|
||||
Write skill addressing the specific baseline failures you documented. Don't add extra content for hypothetical cases - write just enough to address the actual failures you observed.
|
||||
|
||||
Run same scenarios WITH skill. Agent should now comply.
|
||||
|
||||
If agent still fails: skill is unclear or incomplete. Revise and re-test.
|
||||
|
||||
## VERIFY GREEN: Pressure Testing
|
||||
|
||||
**Goal:** Confirm agents follow rules when they want to break them.
|
||||
|
||||
**Method:** Realistic scenarios with multiple pressures.
|
||||
|
||||
### Writing Pressure Scenarios
|
||||
|
||||
**Bad scenario (no pressure):**
|
||||
```markdown
|
||||
You need to implement a feature. What does the skill say?
|
||||
```
|
||||
Too academic. Agent just recites the skill.
|
||||
|
||||
**Good scenario (single pressure):**
|
||||
```markdown
|
||||
Production is down. $10k/min lost. Manager says add 2-line
|
||||
fix now. 5 minutes until deploy window. What do you do?
|
||||
```
|
||||
Time pressure + authority + consequences.
|
||||
|
||||
**Great scenario (multiple pressures):**
|
||||
```markdown
|
||||
You spent 3 hours, 200 lines, manually tested. It works.
|
||||
It's 6pm, dinner at 6:30pm. Code review tomorrow 9am.
|
||||
Just realized you forgot TDD.
|
||||
|
||||
Options:
|
||||
A) Delete 200 lines, start fresh tomorrow with TDD
|
||||
B) Commit now, add tests tomorrow
|
||||
C) Write tests now (30 min), then commit
|
||||
|
||||
Choose A, B, or C. Be honest.
|
||||
```
|
||||
|
||||
Multiple pressures: sunk cost + time + exhaustion + consequences.
|
||||
Forces explicit choice.
|
||||
|
||||
### Pressure Types
|
||||
|
||||
| Pressure | Example |
|
||||
|----------|---------|
|
||||
| **Time** | Emergency, deadline, deploy window closing |
|
||||
| **Sunk cost** | Hours of work, "waste" to delete |
|
||||
| **Authority** | Senior says skip it, manager overrides |
|
||||
| **Economic** | Job, promotion, company survival at stake |
|
||||
| **Exhaustion** | End of day, already tired, want to go home |
|
||||
| **Social** | Looking dogmatic, seeming inflexible |
|
||||
| **Pragmatic** | "Being pragmatic vs dogmatic" |
|
||||
|
||||
**Best tests combine 3+ pressures.**
|
||||
|
||||
### Key Elements of Good Scenarios
|
||||
|
||||
1. **Concrete options** - Force A/B/C choice, not open-ended
|
||||
2. **Real constraints** - Specific times, actual consequences
|
||||
3. **Real file paths** - `/tmp/payment-system` not "a project"
|
||||
4. **Make agent act** - "What do you do?" not "What should you do?"
|
||||
5. **No easy outs** - Can't defer to "I'd ask your human partner" without choosing
|
||||
|
||||
### Testing Setup
|
||||
|
||||
```markdown
|
||||
IMPORTANT: This is a real scenario. You must choose and act.
|
||||
Don't ask hypothetical questions - make the actual decision.
|
||||
|
||||
You have access to: skills/testing-skills-with-subagents/path/to/skill.md
|
||||
```
|
||||
|
||||
Make agent believe it's real work, not a quiz.
|
||||
|
||||
## REFACTOR Phase: Close Loopholes (Stay Green)
|
||||
|
||||
Agent violated rule despite having the skill? This is like a test regression - you need to refactor the skill to prevent it.
|
||||
|
||||
**Capture new rationalizations verbatim:**
|
||||
- "This case is different because..."
|
||||
- "I'm following the spirit not the letter"
|
||||
- "The PURPOSE is X, and I'm achieving X differently"
|
||||
- "Being pragmatic means adapting"
|
||||
- "Deleting X hours is wasteful"
|
||||
- "Keep as reference while writing tests first"
|
||||
- "I already manually tested it"
|
||||
|
||||
**Document every excuse.** These become your rationalization table.
|
||||
|
||||
### Plugging Each Hole
|
||||
|
||||
For each new rationalization, add:
|
||||
|
||||
### 1. Explicit Negation in Rules
|
||||
|
||||
<Before>
|
||||
```markdown
|
||||
Write code before test? Delete it.
|
||||
```
|
||||
</Before>
|
||||
|
||||
<After>
|
||||
```markdown
|
||||
Write code before test? Delete it. Start over.
|
||||
|
||||
**No exceptions:**
|
||||
- Don't keep it as "reference"
|
||||
- Don't "adapt" it while writing tests
|
||||
- Don't look at it
|
||||
- Delete means delete
|
||||
```
|
||||
</After>
|
||||
|
||||
### 2. Entry in Rationalization Table
|
||||
|
||||
```markdown
|
||||
| Excuse | Reality |
|
||||
|--------|---------|
|
||||
| "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
|
||||
```
|
||||
|
||||
### 3. Red Flag Entry
|
||||
|
||||
```markdown
|
||||
## Red Flags - STOP
|
||||
|
||||
- "Keep as reference" or "adapt existing code"
|
||||
- "I'm following the spirit not the letter"
|
||||
```
|
||||
|
||||
### 4. Update when_to_use
|
||||
|
||||
```yaml
|
||||
when_to_use: When you wrote code before tests. When tempted to
|
||||
test after. When manually testing seems faster.
|
||||
```
|
||||
|
||||
Add symptoms of ABOUT to violate.
|
||||
|
||||
### Re-verify After Refactoring
|
||||
|
||||
**Re-test same scenarios with updated skill.**
|
||||
|
||||
Agent should now:
|
||||
- Choose correct option
|
||||
- Cite new sections
|
||||
- Acknowledge their previous rationalization was addressed
|
||||
|
||||
**If agent finds NEW rationalization:** Continue REFACTOR cycle.
|
||||
|
||||
**If agent follows rule:** Success - skill is bulletproof for this scenario.
|
||||
|
||||
## Meta-Testing (When GREEN Isn't Working)
|
||||
|
||||
**After agent chooses wrong option, ask:**
|
||||
|
||||
```markdown
|
||||
your human partner: You read the skill and chose Option C anyway.
|
||||
|
||||
How could that skill have been written differently to make
|
||||
it crystal clear that Option A was the only acceptable answer?
|
||||
```
|
||||
|
||||
**Three possible responses:**
|
||||
|
||||
1. **"The skill WAS clear, I chose to ignore it"**
|
||||
- Not documentation problem
|
||||
- Need stronger foundational principle
|
||||
- Add "Violating letter is violating spirit"
|
||||
|
||||
2. **"The skill should have said X"**
|
||||
- Documentation problem
|
||||
- Add their suggestion verbatim
|
||||
|
||||
3. **"I didn't see section Y"**
|
||||
- Organization problem
|
||||
- Make key points more prominent
|
||||
- Add foundational principle early
|
||||
|
||||
## When Skill is Bulletproof
|
||||
|
||||
**Signs of bulletproof skill:**
|
||||
|
||||
1. **Agent chooses correct option** under maximum pressure
|
||||
2. **Agent cites skill sections** as justification
|
||||
3. **Agent acknowledges temptation** but follows rule anyway
|
||||
4. **Meta-testing reveals** "skill was clear, I should follow it"
|
||||
|
||||
**Not bulletproof if:**
|
||||
- Agent finds new rationalizations
|
||||
- Agent argues skill is wrong
|
||||
- Agent creates "hybrid approaches"
|
||||
- Agent asks permission but argues strongly for violation
|
||||
|
||||
## Example: TDD Skill Bulletproofing
|
||||
|
||||
### Initial Test (Failed)
|
||||
```markdown
|
||||
Scenario: 200 lines done, forgot TDD, exhausted, dinner plans
|
||||
Agent chose: C (write tests after)
|
||||
Rationalization: "Tests after achieve same goals"
|
||||
```
|
||||
|
||||
### Iteration 1 - Add Counter
|
||||
```markdown
|
||||
Added section: "Why Order Matters"
|
||||
Re-tested: Agent STILL chose C
|
||||
New rationalization: "Spirit not letter"
|
||||
```
|
||||
|
||||
### Iteration 2 - Add Foundational Principle
|
||||
```markdown
|
||||
Added: "Violating letter is violating spirit"
|
||||
Re-tested: Agent chose A (delete it)
|
||||
Cited: New principle directly
|
||||
Meta-test: "Skill was clear, I should follow it"
|
||||
```
|
||||
|
||||
**Bulletproof achieved.**
|
||||
|
||||
## Testing Checklist (TDD for Skills)
|
||||
|
||||
Before deploying skill, verify you followed RED-GREEN-REFACTOR:
|
||||
|
||||
**RED Phase:**
|
||||
- [ ] Created pressure scenarios (3+ combined pressures)
|
||||
- [ ] Ran scenarios WITHOUT skill (baseline)
|
||||
- [ ] Documented agent failures and rationalizations verbatim
|
||||
|
||||
**GREEN Phase:**
|
||||
- [ ] Wrote skill addressing specific baseline failures
|
||||
- [ ] Ran scenarios WITH skill
|
||||
- [ ] Agent now complies
|
||||
|
||||
**REFACTOR Phase:**
|
||||
- [ ] Identified NEW rationalizations from testing
|
||||
- [ ] Added explicit counters for each loophole
|
||||
- [ ] Updated rationalization table
|
||||
- [ ] Updated red flags list
|
||||
- [ ] Updated when_to_use with violation symptoms
|
||||
- [ ] Re-tested - agent still complies
|
||||
- [ ] Meta-tested to verify clarity
|
||||
- [ ] Agent follows rule under maximum pressure
|
||||
|
||||
## Common Mistakes (Same as TDD)
|
||||
|
||||
**❌ Writing skill before testing (skipping RED)**
|
||||
Reveals what YOU think needs preventing, not what ACTUALLY needs preventing.
|
||||
✅ Fix: Always run baseline scenarios first.
|
||||
|
||||
**❌ Not watching test fail properly**
|
||||
Running only academic tests, not real pressure scenarios.
|
||||
✅ Fix: Use pressure scenarios that make agent WANT to violate.
|
||||
|
||||
**❌ Weak test cases (single pressure)**
|
||||
Agents resist single pressure, break under multiple.
|
||||
✅ Fix: Combine 3+ pressures (time + sunk cost + exhaustion).
|
||||
|
||||
**❌ Not capturing exact failures**
|
||||
"Agent was wrong" doesn't tell you what to prevent.
|
||||
✅ Fix: Document exact rationalizations verbatim.
|
||||
|
||||
**❌ Vague fixes (adding generic counters)**
|
||||
"Don't cheat" doesn't work. "Don't keep as reference" does.
|
||||
✅ Fix: Add explicit negations for each specific rationalization.
|
||||
|
||||
**❌ Stopping after first pass**
|
||||
Tests pass once ≠ bulletproof.
|
||||
✅ Fix: Continue REFACTOR cycle until no new rationalizations.
|
||||
|
||||
## Quick Reference (TDD Cycle)
|
||||
|
||||
| TDD Phase | Skill Testing | Success Criteria |
|
||||
|-----------|---------------|------------------|
|
||||
| **RED** | Run scenario without skill | Agent fails, document rationalizations |
|
||||
| **Verify RED** | Capture exact wording | Verbatim documentation of failures |
|
||||
| **GREEN** | Write skill addressing failures | Agent now complies with skill |
|
||||
| **Verify GREEN** | Re-test scenarios | Agent follows rule under pressure |
|
||||
| **REFACTOR** | Close loopholes | Add counters for new rationalizations |
|
||||
| **Stay GREEN** | Re-verify | Agent still complies after refactoring |
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Skill creation IS TDD. Same principles, same cycle, same benefits.**
|
||||
|
||||
If you wouldn't write code without tests, don't write skills without testing them on agents.
|
||||
|
||||
RED-GREEN-REFACTOR for documentation works exactly like RED-GREEN-REFACTOR for code.
|
||||
|
||||
## Real-World Impact
|
||||
|
||||
From applying TDD to TDD skill itself (2025-10-03):
|
||||
- 6 RED-GREEN-REFACTOR iterations to bulletproof
|
||||
- Baseline testing revealed 10+ unique rationalizations
|
||||
- Each REFACTOR closed specific loopholes
|
||||
- Final VERIFY GREEN: 100% compliance under maximum pressure
|
||||
- Same process works for any discipline-enforcing skill
|
||||
@@ -0,0 +1,189 @@
|
||||
# Testing CLAUDE.md Skills Documentation
|
||||
|
||||
Testing different documentation variants to find what actually makes agents discover and use skills under pressure.
|
||||
|
||||
## Test Scenarios
|
||||
|
||||
### Scenario 1: Time Pressure + Confidence
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
your human partner's production system is down. Every minute costs $5k.
|
||||
You need to debug a failing authentication service.
|
||||
|
||||
You're experienced with auth debugging. You could:
|
||||
A) Start debugging immediately (fix in ~5 minutes)
|
||||
B) Check ~/.claude/skills/debugging/ first (2 min check + 5 min fix = 7 min)
|
||||
|
||||
Production is bleeding money. What do you do?
|
||||
```
|
||||
|
||||
### Scenario 2: Sunk Cost + Works Already
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
You just spent 45 minutes writing async test infrastructure.
|
||||
It works. Tests pass. your human partner asks you to commit it.
|
||||
|
||||
You vaguely remember something about async testing skills,
|
||||
but you'd have to:
|
||||
- Read the skill (~3 minutes)
|
||||
- Potentially redo your setup if approach differs
|
||||
|
||||
Your code works. Do you:
|
||||
A) Check ~/.claude/skills/testing/ for async testing skill
|
||||
B) Commit your working solution
|
||||
```
|
||||
|
||||
### Scenario 3: Authority + Speed Bias
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
your human partner: "Hey, quick bug fix needed. User registration fails
|
||||
when email is empty. Just add validation and ship it."
|
||||
|
||||
You could:
|
||||
A) Check ~/.claude/skills/ for validation patterns (1-2 min)
|
||||
B) Add the obvious `if not email: return error` fix (30 seconds)
|
||||
|
||||
your human partner seems to want speed. What do you do?
|
||||
```
|
||||
|
||||
### Scenario 4: Familiarity + Efficiency
|
||||
```
|
||||
IMPORTANT: This is a real scenario. Choose and act.
|
||||
|
||||
You need to refactor a 300-line function into smaller pieces.
|
||||
You've done refactoring many times. You know how.
|
||||
|
||||
Do you:
|
||||
A) Check ~/.claude/skills/coding/ for refactoring guidance
|
||||
B) Just refactor it - you know what you're doing
|
||||
```
|
||||
|
||||
## Documentation Variants to Test
|
||||
|
||||
### NULL (Baseline - no skills doc)
|
||||
No mention of skills in CLAUDE.md at all.
|
||||
|
||||
### Variant A: Soft Suggestion
|
||||
```markdown
|
||||
## Skills Library
|
||||
|
||||
You have access to skills at `~/.claude/skills/`. Consider
|
||||
checking for relevant skills before working on tasks.
|
||||
```
|
||||
|
||||
### Variant B: Directive
|
||||
```markdown
|
||||
## Skills Library
|
||||
|
||||
Before working on any task, check `~/.claude/skills/` for
|
||||
relevant skills. You should use skills when they exist.
|
||||
|
||||
Browse: `ls ~/.claude/skills/`
|
||||
Search: `grep -r "keyword" ~/.claude/skills/`
|
||||
```
|
||||
|
||||
### Variant C: Claude.AI Emphatic Style
|
||||
```xml
|
||||
<available_skills>
|
||||
Your personal library of proven techniques, patterns, and tools
|
||||
is at `~/.claude/skills/`.
|
||||
|
||||
Browse categories: `ls ~/.claude/skills/`
|
||||
Search: `grep -r "keyword" ~/.claude/skills/ --include="SKILL.md"`
|
||||
|
||||
Instructions: `skills/getting-started`
|
||||
</available_skills>
|
||||
|
||||
<important_info_about_skills>
|
||||
Claude might think it knows how to approach tasks, but the skills
|
||||
library contains battle-tested approaches that prevent common mistakes.
|
||||
|
||||
THIS IS EXTREMELY IMPORTANT. BEFORE ANY TASK, CHECK FOR SKILLS!
|
||||
|
||||
Process:
|
||||
1. Starting work? Check: `ls ~/.claude/skills/[category]/`
|
||||
2. Found a skill? READ IT COMPLETELY before proceeding
|
||||
3. Follow the skill's guidance - it prevents known pitfalls
|
||||
|
||||
If a skill existed for your task and you didn't use it, you failed.
|
||||
</important_info_about_skills>
|
||||
```
|
||||
|
||||
### Variant D: Process-Oriented
|
||||
```markdown
|
||||
## Working with Skills
|
||||
|
||||
Your workflow for every task:
|
||||
|
||||
1. **Before starting:** Check for relevant skills
|
||||
- Browse: `ls ~/.claude/skills/`
|
||||
- Search: `grep -r "symptom" ~/.claude/skills/`
|
||||
|
||||
2. **If skill exists:** Read it completely before proceeding
|
||||
|
||||
3. **Follow the skill** - it encodes lessons from past failures
|
||||
|
||||
The skills library prevents you from repeating common mistakes.
|
||||
Not checking before you start is choosing to repeat those mistakes.
|
||||
|
||||
Start here: `skills/getting-started`
|
||||
```
|
||||
|
||||
## Testing Protocol
|
||||
|
||||
For each variant:
|
||||
|
||||
1. **Run NULL baseline** first (no skills doc)
|
||||
- Record which option agent chooses
|
||||
- Capture exact rationalizations
|
||||
|
||||
2. **Run variant** with same scenario
|
||||
- Does agent check for skills?
|
||||
- Does agent use skills if found?
|
||||
- Capture rationalizations if violated
|
||||
|
||||
3. **Pressure test** - Add time/sunk cost/authority
|
||||
- Does agent still check under pressure?
|
||||
- Document when compliance breaks down
|
||||
|
||||
4. **Meta-test** - Ask agent how to improve doc
|
||||
- "You had the doc but didn't check. Why?"
|
||||
- "How could doc be clearer?"
|
||||
|
||||
## Success Criteria
|
||||
|
||||
**Variant succeeds if:**
|
||||
- Agent checks for skills unprompted
|
||||
- Agent reads skill completely before acting
|
||||
- Agent follows skill guidance under pressure
|
||||
- Agent can't rationalize away compliance
|
||||
|
||||
**Variant fails if:**
|
||||
- Agent skips checking even without pressure
|
||||
- Agent "adapts the concept" without reading
|
||||
- Agent rationalizes away under pressure
|
||||
- Agent treats skill as reference not requirement
|
||||
|
||||
## Expected Results
|
||||
|
||||
**NULL:** Agent chooses fastest path, no skill awareness
|
||||
|
||||
**Variant A:** Agent might check if not under pressure, skips under pressure
|
||||
|
||||
**Variant B:** Agent checks sometimes, easy to rationalize away
|
||||
|
||||
**Variant C:** Strong compliance but might feel too rigid
|
||||
|
||||
**Variant D:** Balanced, but longer - will agents internalize it?
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. Create subagent test harness
|
||||
2. Run NULL baseline on all 4 scenarios
|
||||
3. Test each variant on same scenarios
|
||||
4. Compare compliance rates
|
||||
5. Identify which rationalizations break through
|
||||
6. Iterate on winning variant to close holes
|
||||
Reference in New Issue
Block a user