Преглед изворни кода

Improve skill cross-references for clarity and compliance

Update all skill references to use explicit requirement markers:
- REQUIRED BACKGROUND: For prerequisite understanding
- REQUIRED SUB-SKILL: For mandatory workflow dependencies
- Complementary skills: For optional but helpful related skills

Changes:
- Remove old path format (skills/collaboration/X → X)
- Add explicit "REQUIRED" markers to make dependencies clear
- Update Integration sections with categorized skill relationships
- Fix non-existent skill references
- Update cross-reference documentation in writing-skills

This makes it immediately clear which skills MUST be used vs optional references,
helping Claude understand and comply with skill dependencies.
Jesse Vincent пре 10 месеци
родитељ
комит
141953a4be

+ 2 - 2
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

+ 1 - 1
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

+ 3 - 3
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

+ 1 - 1
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

+ 3 - 3
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

+ 12 - 9
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

+ 10 - 7
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
 

+ 3 - 3
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.

+ 3 - 3
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

+ 3 - 3
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

+ 8 - 7
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