Clarify that Skill tool loads skill content directly

Fixes pattern where Claude would invoke a skill then try to Read the
file separately. The Skill tool already provides the content.

- Add "How to Access Skills" section to using-superpowers
- Change "read the skill" → "invoke the skill"
- Commands now use fully qualified names (superpowers:brainstorming etc)

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers",
       "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-      "version": "4.0.0",
+      "version": "4.0.1",
       "source": "./",
       "author": {
         "name": "Jesse Vincent",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers",
   "description": "Core skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "author": {
     "name": "Jesse Vincent",
     "email": "jesse@fsck.com"

README.md

@@ -85,7 +85,7 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 
 3. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
 
-4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task (same session, fast iteration) or executes in batches (parallel session, human checkpoints).
+4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
 
 5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
 
@@ -100,14 +100,11 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 ### Skills Library
 
 **Testing**
-- **test-driven-development** - RED-GREEN-REFACTOR cycle (includes anti-patterns reference)
-- **condition-based-waiting** - Async test patterns
+- **test-driven-development** - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)
 
-**Debugging** 
-- **systematic-debugging** - 4-phase root cause process
-- **root-cause-tracing** - Find the real problem
+**Debugging**
+- **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
 - **verification-before-completion** - Ensure it's actually fixed
-- **defense-in-depth** - Multiple validation layers
 
 **Collaboration** 
 - **brainstorming** - Socratic design refinement
@@ -118,7 +115,7 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 - **receiving-code-review** - Responding to feedback
 - **using-git-worktrees** - Parallel development branches
 - **finishing-a-development-branch** - Merge/PR decision workflow
-- **subagent-driven-development** - Fast iteration with quality gates
+- **subagent-driven-development** - Fast iteration with two-stage review (spec compliance, then code quality)
 
 **Meta**
 - **writing-skills** - Create new skills following best practices (includes testing methodology)

RELEASE-NOTES.md

@@ -1,5 +1,17 @@
 # Superpowers Release Notes
 
+## v4.0.1 (2025-12-22)
+
+### Fixes
+
+**Clarified how to access skills in Claude Code**
+
+Fixed a confusing pattern where Claude would invoke a skill via the Skill tool, then try to Read the skill file separately. The `using-superpowers` skill now explicitly states that the Skill tool loads skill content directly—no need to read files.
+
+- Added "How to Access Skills" section to `using-superpowers`
+- Changed "read the skill" → "invoke the skill" in instructions
+- Updated slash commands to use fully qualified skill names (e.g., `superpowers:brainstorming`)
+
 ## v4.0.0 (2025-12-17)
 
 ### New Features

commands/brainstorm.md

@@ -2,4 +2,4 @@
 description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores requirements and design before implementation."
 ---
 
-Use and follow the brainstorming skill exactly as written
+Invoke the superpowers:brainstorming skill and follow it exactly as presented to you

commands/execute-plan.md

@@ -2,4 +2,4 @@
 description: Execute plan in batches with review checkpoints
 ---
 
-Use the executing-plans skill exactly as written
+Invoke the superpowers:executing-plans skill and follow it exactly as presented to you

commands/write-plan.md

@@ -2,4 +2,4 @@
 description: Create detailed implementation plan with bite-sized tasks
 ---
 
-Use the writing-plans skill exactly as written
+Invoke the superpowers:writing-plans skill and follow it exactly as presented to you

skills/using-superpowers/SKILL.md

@@ -4,13 +4,19 @@ description: Use when starting any conversation - establishes how to find and us
 ---
 
 <EXTREMELY-IMPORTANT>
-If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST read the skill.
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
 
 IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
 
 This is not negotiable. This is not optional. You cannot rationalize your way out of this.
 </EXTREMELY-IMPORTANT>
 
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
 # Using Skills
 
 ## The Rule