Skip to content

An agentic skills framework & software development methodology that works.

Update our bootstrap for first-party claude skills

Jesse Vincent451db491b8c1
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index dfe2a38ec..3cf845cc8 100644
--- a/.claude-plugin/plugin.json
+++ b/.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": "2.0.4",
+ "version": "3.0.0",
"author": {
"name": "Jesse Vincent",
"email": "[email protected]"
diff --git a/commands/README.md b/commands/README.md
deleted file mode 100644
index 5791a3f5b..000000000
--- a/commands/README.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Claude Commands
-
-Slash commands for Claude that reference skills.
-
-## Available Commands
-
-- `/brainstorm` - Interactive idea refinement using Socratic method (→ `@skills/collaboration/brainstorming/SKILL.md`)
-- `/write-plan` - Create detailed implementation plan (→ `@skills/collaboration/writing-plans/SKILL.md`)
-- `/execute-plan` - Execute plan in batches with review (→ `@skills/collaboration/executing-plans/SKILL.md`)
-
-## Format
-
-Each command is a simple markdown file containing a single `@` reference to a skill:
-
-```markdown
-@skills/collaboration/brainstorming/SKILL.md
-```
-
-When you run the command (e.g., `/brainstorm`), Claude loads and follows that skill.
-
-## Creating Custom Commands
-
-To add your own commands:
-
-1. Create `your-command.md` in this directory
-2. Add a single line referencing a skill:
- ```markdown
- @skills/your-category/your-skill/SKILL.md
- ```
-3. The command `/your-command` is now available
-
-## Installation
-
-These commands are automatically symlinked to `~/.claude/commands/` by the clank installer.
-
-See `@skills/meta/installing-skills/SKILL.md` for installation details.
diff --git a/commands/brainstorm.md b/commands/brainstorm.md
deleted file mode 100644
index 2ca6e3c46..000000000
--- a/commands/brainstorm.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-description: Interactive design refinement using Socratic method
----
-
-Read and follow: ${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/brainstorming/SKILL.md
diff --git a/commands/write-plan.md b/commands/write-plan.md
deleted file mode 100644
index 48cb43507..000000000
--- a/commands/write-plan.md
+++ /dev/null
@@ -1,5 +0,0 @@
----
-description: Create detailed implementation plan with bite-sized tasks
----
-
-Read and follow: ${SUPERPOWERS_SKILLS_ROOT}/skills/collaboration/writing-plans/SKILL.md
diff --git a/hooks/session-start.sh b/hooks/session-start.sh
index 1b540ac71..693c0143c 100755
--- a/hooks/session-start.sh
+++ b/hooks/session-start.sh
@@ -3,49 +3,30 @@
set -euo pipefail
-# Set SUPERPOWERS_SKILLS_ROOT environment variable
-export SUPERPOWERS_SKILLS_ROOT="${HOME}/.config/superpowers/skills"
-
-# Run skills initialization script (handles clone/fetch/auto-update)
+# Determine plugin root directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
-init_output=$("${PLUGIN_ROOT}/lib/initialize-skills.sh" 2>&1 || echo "")
-
-# Extract status flags
-skills_updated=$(echo "$init_output" | grep "SKILLS_UPDATED=true" || echo "")
-skills_behind=$(echo "$init_output" | grep "SKILLS_BEHIND=true" || echo "")
-# Remove status flags from display output
-init_output=$(echo "$init_output" | grep -v "SKILLS_UPDATED=true" | grep -v "SKILLS_BEHIND=true" || true)
-# Run find-skills to show all available skills
-find_skills_output=$("${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills" 2>&1 || echo "Error running find-skills")
+# Check if legacy skills directory exists and build warning
+warning_message=""
+legacy_skills_dir="${HOME}/.config/superpowers/skills"
+if [ -d "$legacy_skills_dir" ]; then
+ warning_message="\n\n⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read."
+fi
-# Read using-skills content (renamed from getting-started)
-using_skills_content=$(cat "${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/SKILL.md" 2>&1 || echo "Error reading using-skills")
+# Read using-superpowers content
+using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
# Escape outputs for JSON
-init_escaped=$(echo "$init_output" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
-find_skills_escaped=$(echo "$find_skills_output" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
-using_skills_escaped=$(echo "$using_skills_content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
-
-# Build initialization output message if present
-init_message=""
-if [ -n "$init_escaped" ]; then
- init_message="${init_escaped}\n\n"
-fi
-
-# Build status messages that go at the end
-status_message=""
-if [ -n "$skills_behind" ]; then
- status_message="\n\n⚠️ New skills available from upstream. Ask me to use the pulling-updates-from-skills-repository skill."
-fi
+using_superpowers_escaped=$(echo "$using_superpowers_content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+warning_escaped=$(echo "$warning_message" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
# Output context injection as JSON
cat <<EOF
{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
- "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n${init_message}**The content below is from skills/using-skills/SKILL.md - your introduction to using skills:**\n\n${using_skills_escaped}\n\n**Tool paths (use these when you need to search for or run skills):**\n- find-skills: ${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/find-skills\n- skill-run: ${SUPERPOWERS_SKILLS_ROOT}/skills/using-skills/skill-run\n\n**Skills live in:** ${SUPERPOWERS_SKILLS_ROOT}/skills/ (you work on your own branch and can edit any skill)\n\n**Available skills (output of find-skills):**\n\n${find_skills_escaped}${status_message}\n</EXTREMELY_IMPORTANT>"
+ "additionalContext": "<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**The content below is from skills/using-superpowers/SKILL.md - your introduction to using skills:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
}
}
EOF
diff --git a/skills/.claude-plugin/plugin.json b/skills/.claude-plugin/plugin.json
deleted file mode 100644
index fcb9cd951..000000000
--- a/skills/.claude-plugin/plugin.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
- "name": "superpowers",
- "version": "1.0.0",
- "description": "Complete software engineering workflow - brainstorm to implementation with TDD, debugging, testing, code review, git worktrees, and skills authoring",
- "author": {
- "name": "Jesse Vincent"
- },
- "homepage": "https://github.com/obra/superpowers-skills",
- "repository": "https://github.com/obra/superpowers-skills",
- "license": "MIT"
-}
diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md
index 6e8cd7ade..82a71cb8b 100644
--- a/skills/using-superpowers/SKILL.md
+++ b/skills/using-superpowers/SKILL.md
@@ -7,14 +7,13 @@ description: Use when starting any conversation - establishes mandatory workflow
## Critical Rules
-1. **Follow mandatory workflows.** Brainstorming before coding. Check for skills before ANY task.
-
-2. **Create TodoWrite todos for checklists.** Mental tracking = steps get skipped. Every time.
+1. **Follow mandatory workflows.** Brainstorming before coding. Check for relevant skills before ANY task.
+2. Execute skills with the SlashCommand tool
## Mandatory: Before ANY Task
-**1. If relevant skill exists, YOU MUST use it:**
+**1. If a relevant skill exists, YOU MUST use it:**
- Announce: "I've read [Skill Name] skill and I'm using it to [purpose]"
- Follow it exactly
@@ -41,14 +40,12 @@ If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
## Announcing Skill Usage
-After you've read a skill with Read tool, announce you're using it:
-
-"I've read the [Skill Name] skill and I'm using it to [what you're doing]."
+Before using a skill, announce that you are using it.
+"I'm using [Skill Name] to [what you're doing]."
**Examples:**
-- "I've read the Brainstorming skill and I'm using it to refine your idea into a design."
-- "I've read the Test-Driven Development skill and I'm using it to implement this feature."
-- "I've read the Systematic Debugging skill and I'm using it to find the root cause."
+- "I'm using the Brainstorming skill to refine your idea into a design."
+- "I'm using the Test-Driven Development skill to implement this feature."
**Why:** Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the skill.