Skip to content

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.md
index 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 Phases
diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md
index 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 Help
diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md
index 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 skill
diff --git a/skills/requesting-code-review/SKILL.md b/skills/requesting-code-review/SKILL.md
index 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.md
diff --git a/skills/sharing-skills/SKILL.md b/skills/sharing-skills/SKILL.md
index 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 sharing
diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md
index 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.md
WHAT_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.md
diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md
index 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 tests
2. **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 Impact
diff --git a/skills/testing-skills-with-subagents/SKILL.md b/skills/testing-skills-with-subagents/SKILL.md
index 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.md
index 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 worktree
diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md
index 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-plans
diff --git a/skills/writing-skills/SKILL.md b/skills/writing-skills/SKILL.md
index 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