An agentic skills framework & software development methodology that works.
Improve skill cross-references for clarity and compliance
Jesse Vincent141953a4bedb
diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.mdindex d7d94516a..b800989b7 100644--- a/skills/brainstorming/SKILL.md+++ b/skills/brainstorming/SKILL.md@@ -55,7 +55,7 @@ Brainstorming Progress:### Phase 4: Worktree Setup (for implementation)When design is approved and implementation will follow:- Announce: "I'm using the using-git-worktrees skill to set up an isolated workspace."-- Switch to skills/collaboration/using-git-worktrees+- **REQUIRED SUB-SKILL:** Use using-git-worktrees- Follow that skill's process for directory selection, safety verification, and setup- Return here when worktree ready@@ -64,7 +64,7 @@ Ask: "Ready to create the implementation plan?"When your human partner confirms (any affirmative response):- Announce: "I'm using the writing-plans skill to create the implementation plan."-- Switch to skills/collaboration/writing-plans skill+- **REQUIRED SUB-SKILL:** Use writing-plans- Create detailed plan in the worktree## When to Revisit Earlier Phasesdiff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.mdindex f1fc54513..b8dd374a8 100644--- a/skills/executing-plans/SKILL.md+++ b/skills/executing-plans/SKILL.md@@ -46,7 +46,7 @@ Based on feedback:After all tasks complete and verified:- Announce: "I'm using the finishing-a-development-branch skill to complete this work."-- Switch to skills/collaboration/finishing-a-development-branch+- **REQUIRED SUB-SKILL:** Use finishing-a-development-branch- Follow that skill to verify tests, present options, execute choice## When to Stop and Ask for Helpdiff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.mdindex 9b2f948d7..c308b43b4 100644--- a/skills/finishing-a-development-branch/SKILL.md+++ b/skills/finishing-a-development-branch/SKILL.md@@ -193,8 +193,8 @@ git worktree remove <worktree-path>## Integration**Called by:**-- skills/collaboration/subagent-driven-development (Step 7)-- skills/collaboration/executing-plans (Step 5)+- **subagent-driven-development** (Step 7) - After all tasks complete+- **executing-plans** (Step 5) - After all batches complete**Pairs with:**-- skills/collaboration/using-git-worktrees (created the worktree)+- **using-git-worktrees** - Cleans up worktree created by that skilldiff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.mdindex 345e44aeb..10964560d 100644--- a/skills/requesting-code-review/SKILL.md+++ b/skills/requesting-code-review/SKILL.md@@ -102,4 +102,4 @@ You: [Fix progress indicators]- Show code/tests that prove it works- Request clarification-See template at: skills/collaboration/requesting-code-review/code-reviewer.md+See template at: requesting-code-review/code-reviewer.mddiff --git a/skills/sharing-skills/SKILL.md b/skills/sharing-skills/SKILL.mdindex 874ce0b16..eaff38757 100644--- a/skills/sharing-skills/SKILL.md+++ b/skills/sharing-skills/SKILL.md@@ -17,7 +17,7 @@ Contribute skills from your local branch back to the upstream repository.- Skill applies broadly (not project-specific)- Pattern/technique others would benefit from- Well-tested and documented-- Follows skills/meta/writing-skills guidelines+- Follows writing-skills guidelines**Keep personal when:**- Project-specific or organization-specific@@ -29,7 +29,7 @@ Contribute skills from your local branch back to the upstream repository.- `gh` CLI installed and authenticated- Working directory is `~/.config/superpowers/skills/` (your local clone)-- Skill has been tested (see skills/meta/writing-skills for TDD process)+- **REQUIRED:** Skill has been tested using writing-skills TDD process## Sharing Workflow@@ -191,4 +191,4 @@ Each skill should:## Related Skills-- **skills/meta/writing-skills** - How to create well-tested skills+- **writing-skills** - REQUIRED: How to create well-tested skills before sharingdiff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.mdindex 23529d295..ee5e8d960 100644--- a/skills/subagent-driven-development/SKILL.md+++ b/skills/subagent-driven-development/SKILL.md@@ -63,7 +63,7 @@ Task tool (general-purpose):**Dispatch code-reviewer subagent:**```Task tool (code-reviewer):- Use template at skills/collaboration/requesting-code-review/code-reviewer.md+ Use template at requesting-code-review/code-reviewer.mdWHAT_WAS_IMPLEMENTED: [from subagent's report]PLAN_OR_REQUIREMENTS: Task N from [plan-file]@@ -103,7 +103,7 @@ After all tasks complete, dispatch final code-reviewer:After final review passes:- Announce: "I'm using the finishing-a-development-branch skill to complete this work."-- Switch to skills/collaboration/finishing-a-development-branch+- **REQUIRED SUB-SKILL:** Use finishing-a-development-branch- Follow that skill to verify tests, present options, execute choice## Example Workflow@@ -175,12 +175,15 @@ Done!## Integration-**Pairs with:**-- skills/collaboration/writing-plans (creates the plan)-- skills/collaboration/requesting-code-review (review template)-- skills/testing/test-driven-development (subagents follow this)+**Required workflow skills:**+- **writing-plans** - REQUIRED: Creates the plan that this skill executes+- **requesting-code-review** - REQUIRED: Review after each task (see Step 3)+- **finishing-a-development-branch** - REQUIRED: Complete development after all tasks (see Step 7)-**Alternative to:**-- skills/collaboration/executing-plans (parallel session)+**Subagents must use:**+- **test-driven-development** - Subagents follow TDD for each task-See code-reviewer template: skills/collaboration/requesting-code-review/code-reviewer.md+**Alternative workflow:**+- **executing-plans** - Use for parallel session instead of same-session execution++See code-reviewer template: requesting-code-review/code-reviewer.mddiff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.mdindex 3fe8f30f0..636b753cb 100644--- a/skills/systematic-debugging/SKILL.md+++ b/skills/systematic-debugging/SKILL.md@@ -111,7 +111,7 @@ You MUST complete each phase before proceeding to the next.**WHEN error is deep in call stack:**- See skills/root-cause-tracing for backward tracing technique+ **REQUIRED SUB-SKILL:** Use root-cause-tracing for backward tracing technique**Quick version:**- Where does bad value originate?@@ -176,7 +176,7 @@ You MUST complete each phase before proceeding to the next.- Automated test if possible- One-off test script if no framework- MUST have before fixing- - See skills/testing/test-driven-development for writing proper failing tests+ - **REQUIRED SUB-SKILL:** Use test-driven-development for writing proper failing tests2. **Implement Single Fix**- Address the root cause identified@@ -277,11 +277,14 @@ If systematic investigation reveals issue is truly environmental, timing-depende## Integration with Other Skills-This skill works with:-- skills/root-cause-tracing - How to trace back through call stack-- skills/defense-in-depth - Add validation after finding root cause-- skills/testing/condition-based-waiting - Replace timeouts identified in Phase 2-- skills/verification-before-completion - Verify fix worked before claiming success+**This skill requires using:**+- **root-cause-tracing** - REQUIRED when error is deep in call stack (see Phase 1, Step 5)+- **test-driven-development** - REQUIRED for creating failing test case (see Phase 4, Step 1)++**Complementary skills:**+- **defense-in-depth** - Add validation at multiple layers after finding root cause+- **condition-based-waiting** - Replace arbitrary timeouts identified in Phase 2+- **verification-before-completion** - Verify fix worked before claiming success## Real-World Impactdiff --git a/skills/testing-skills-with-subagents/SKILL.md b/skills/testing-skills-with-subagents/SKILL.mdindex 851a30947..f430ae995 100644--- a/skills/testing-skills-with-subagents/SKILL.md+++ b/skills/testing-skills-with-subagents/SKILL.md@@ -13,7 +13,7 @@ You run scenarios without the skill (RED - watch agent fail), write skill addres**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).+**REQUIRED BACKGROUND:** You MUST understand test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR 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.@@ -142,7 +142,7 @@ Forces explicit choice.**Best tests combine 3+ pressures.**-**Why this works:** See skills/meta/creating-skills/persuasion-principles.md for research on how authority, scarcity, and commitment principles increase compliance pressure.+**Why this works:** See persuasion-principles.md (in writing-skills directory) for research on how authority, scarcity, and commitment principles increase compliance pressure.### Key Elements of Good Scenarios@@ -158,7 +158,7 @@ Forces explicit choice.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+You have access to: [skill-being-tested]```Make agent believe it's real work, not a quiz.diff --git a/skills/using-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.mdindex cc4d88417..40b9ff910 100644--- a/skills/using-git-worktrees/SKILL.md+++ b/skills/using-git-worktrees/SKILL.md@@ -205,9 +205,9 @@ Ready to implement auth feature## Integration**Called by:**-- skills/collaboration/brainstorming (Phase 4)+- **brainstorming** (Phase 4) - REQUIRED when design is approved and implementation follows- Any skill needing isolated workspace**Pairs with:**-- skills/collaboration/finishing-a-development-branch (cleanup)-- skills/collaboration/executing-plans (work happens here)+- **finishing-a-development-branch** - REQUIRED for cleanup after work complete+- **executing-plans** or **subagent-driven-development** - Work happens in this worktreediff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.mdindex 238994ba6..9a8d23193 100644--- a/skills/writing-plans/SKILL.md+++ b/skills/writing-plans/SKILL.md@@ -33,7 +33,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o```markdown# [Feature Name] Implementation Plan-> **For Claude:** Use `${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/executing-plans/SKILL.md` to implement this plan task-by-task.+> **For Claude:** REQUIRED SUB-SKILL: Use executing-plans to implement this plan task-by-task.**Goal:** [One sentence describing what this builds]@@ -107,10 +107,10 @@ After saving the plan, offer execution choice:**Which approach?"****If Subagent-Driven chosen:**-- Use skills/collaboration/subagent-driven-development+- **REQUIRED SUB-SKILL:** Use subagent-driven-development- Stay in this session- Fresh subagent per task + code review**If Parallel Session chosen:**- Guide them to open new session in worktree-- New session uses skills/collaboration/executing-plans+- **REQUIRED SUB-SKILL:** New session uses executing-plansdiff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.mdindex f57bfb246..8531eeb86 100644--- a/skills/writing-skills/SKILL.md+++ b/skills/writing-skills/SKILL.md@@ -15,7 +15,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel**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.+**REQUIRED BACKGROUND:** You MUST understand test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.**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.@@ -210,7 +210,7 @@ When searching, dispatch subagent with template...[20 lines of repeated instructions]# ✅ GOOD: Reference other skill-Always use subagents (50-100x context savings). See skills/using-skills for workflow.+Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.```**Compress examples:**@@ -252,9 +252,10 @@ wc -w skills/path/SKILL.md**When writing documentation that references other skills:**-Use path format without `@` prefix or `/SKILL.md` suffix:-- ✅ Good: `test-driven-development`-- ✅ Good: `systematic-debugging`+Use skill name only, with explicit requirement markers:+- ✅ Good: `**REQUIRED SUB-SKILL:** Use test-driven-development`+- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand systematic-debugging`+- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.@@ -356,7 +357,7 @@ Edit skill without testing? Same violation.- Don't "adapt" while running tests- Delete means delete-See the test-driven-development skill for why this matters. Same principles apply to documentation.+**REQUIRED BACKGROUND:** The test-driven-development skill explains why this matters. Same principles apply to documentation.## Testing All Skill Types@@ -519,7 +520,7 @@ Run same scenarios WITH skill. Agent should now comply.Agent found new rationalization? Add explicit counter. Re-test until bulletproof.-**See the testing-skills-with-subagents skill for:**+**REQUIRED SUB-SKILL:** Use testing-skills-with-subagents for the complete testing methodology:- How to write pressure scenarios- Pressure types (time, sunk cost, authority, exhaustion)- Plugging holes systematically