mirror of
https://github.com/obra/superpowers.git
synced 2026-04-25 11:09:05 +08:00
Initial commit: Superpowers plugin v1.0.0
Core skills library as Claude Code plugin: - Testing skills: TDD, async testing, anti-patterns - Debugging skills: Systematic debugging, root cause tracing - Collaboration skills: Brainstorming, planning, code review - Meta skills: Creating and testing skills Features: - SessionStart hook for context injection - Skills-search tool for discovery - Commands: /brainstorm, /write-plan, /execute-plan - Data directory at ~/.superpowers/
This commit is contained in:
Jesse Vincent
14
skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md
Normal file
14
skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md
Normal file
@@ -0,0 +1,14 @@
|
||||
<EXTREMELY_IMPORTANT>
|
||||
You have a personal skills wiki at ~/.claude/skills/ with proven techniques, patterns, and tools that give you new capabilities.
|
||||
|
||||
STOP. Before doing ANYTHING else in this conversation, read this file: @skills/getting-started/SKILL.md
|
||||
|
||||
That file tells you how to find and use your skills.
|
||||
|
||||
ONLY after reading getting-started, are you allowed to proceed with the user's request.
|
||||
|
||||
When your partner proposes building or creating something, immediately use skills/collaboration/brainstorming
|
||||
|
||||
CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
|
||||
|
||||
</EXTREMELY_IMPORTANT>
|
||||
224
skills/meta/installing-skills/SKILL.md
Normal file
224
skills/meta/installing-skills/SKILL.md
Normal file
@@ -0,0 +1,224 @@
|
||||
---
|
||||
name: Installing Skills System
|
||||
description: Fork, clone to ~/.clank, run installer, edit CLAUDE.md
|
||||
when_to_use: Initial setup, installing clank for the first time
|
||||
version: 2.0.0
|
||||
languages: bash
|
||||
---
|
||||
|
||||
# Installing Skills System
|
||||
|
||||
## Overview
|
||||
|
||||
Installs the clank skills repository to `~/.clank/clank` and configures Claude to use it.
|
||||
|
||||
**For Claude agents:** Follow the "Installation Steps for Claude" section below.
|
||||
|
||||
**For humans:** Follow the "Quick Install" section.
|
||||
|
||||
## Installation Steps for Claude
|
||||
|
||||
When instructed to install clank, follow these steps exactly:
|
||||
|
||||
### Step 1: Clone Repository
|
||||
|
||||
**With GitHub CLI (if available):**
|
||||
```bash
|
||||
mkdir -p ~/.clank
|
||||
cd ~/.clank
|
||||
gh repo fork obra/clank --clone --remote-name upstream
|
||||
```
|
||||
|
||||
**Without GitHub CLI:**
|
||||
```bash
|
||||
mkdir -p ~/.clank
|
||||
cd ~/.clank
|
||||
git clone https://github.com/obra/clank.git
|
||||
```
|
||||
|
||||
### Step 2: Run Installer
|
||||
|
||||
```bash
|
||||
cd ~/.clank/clank
|
||||
./skills/meta/installing-skills/install.sh
|
||||
```
|
||||
|
||||
This creates symlinks for skills and commands.
|
||||
|
||||
### Step 3: Update CLAUDE.md
|
||||
|
||||
Use the Edit tool to add this XML section to the very beginning of `~/.claude/CLAUDE.md`:
|
||||
|
||||
```xml
|
||||
<EXTREMELY_IMPORTANT>
|
||||
You have a personal skills wiki at ~/.claude/skills/ with proven techniques, patterns, and tools that give you new capabilities.
|
||||
|
||||
STOP. Before doing ANYTHING else in this conversation, read this file: skills/getting-started
|
||||
|
||||
That file tells you how to find and use your skills.
|
||||
|
||||
ONLY after reading getting-started, are you allowed to proceed with the user's request.
|
||||
|
||||
CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
|
||||
|
||||
</EXTREMELY_IMPORTANT>
|
||||
```
|
||||
|
||||
### Step 4: Verify Installation
|
||||
|
||||
```bash
|
||||
ls -la ~/.claude/skills
|
||||
ls -la ~/.claude/commands
|
||||
~/.claude/skills/getting-started/skills-search 'test.*driven'
|
||||
```
|
||||
|
||||
### Step 5: Restart
|
||||
|
||||
Tell your human partner: "Installation complete. Please restart your Claude session to pick up the new CLAUDE.md configuration."
|
||||
|
||||
## Quick Install (for humans)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/obra/clank/main/skills/meta/installing-skills/install.sh | bash
|
||||
# Then manually add CLAUDE.md section from Step 3 above
|
||||
```
|
||||
|
||||
## What install.sh Does
|
||||
|
||||
1. **Validates** you're running from clank repo root (expects ~/.clank/clank)
|
||||
2. **Backs up** existing `~/.claude/skills` (if exists) to timestamped backup
|
||||
3. **Creates skills symlink**: `~/.claude/skills` → `~/.clank/clank/skills`
|
||||
4. **Symlinks individual commands** from `~/.clank/clank/commands/*.md` to `~/.claude/commands/`
|
||||
5. **Verifies** tools available (skills-search at `~/.claude/skills/getting-started/skills-search`)
|
||||
6. **Prints** CLAUDE.md XML snippet to add and verification steps
|
||||
|
||||
## Verification
|
||||
|
||||
After installation, verify it worked:
|
||||
|
||||
```bash
|
||||
# Should show symlink to ~/.clank/clank/skills
|
||||
ls -la ~/.claude/skills
|
||||
|
||||
# Should show individual command symlinks
|
||||
ls -la ~/.claude/commands/
|
||||
|
||||
# Test skills-search tool
|
||||
~/.claude/skills/getting-started/skills-search 'test.*driven'
|
||||
```
|
||||
|
||||
## What Gets Installed
|
||||
|
||||
**Skills** (`~/.claude/skills/`):
|
||||
- Library of proven techniques, patterns, and tools
|
||||
- Referenced with `@` syntax in code and documentation
|
||||
- Searchable with `skills-search` tool
|
||||
|
||||
**Commands** (`~/.claude/commands/`):
|
||||
- Individual symlinks to clank command files
|
||||
- Slash commands for Claude (`/brainstorm`, `/write-plan`, `/execute-plan`)
|
||||
- Each command references a skill using `@` syntax
|
||||
- Makes common workflows one command away
|
||||
|
||||
**Tools** (`~/.claude/skills/getting-started/`):
|
||||
- `skills-search` - Find relevant skills using grep patterns
|
||||
- Logs failed searches for gap analysis
|
||||
|
||||
## Why Fork?
|
||||
|
||||
Forking lets you:
|
||||
- **Customize** skills and commands for your workflow
|
||||
- **Contribute** improvements back via PR (see skills/contributing-skills)
|
||||
- **Stay synced** with upstream updates (`git pull upstream main`)
|
||||
- **Track** your customizations in version control
|
||||
|
||||
## Configure CLAUDE.md
|
||||
|
||||
After installation, edit your `~/.claude/CLAUDE.md` and add this section:
|
||||
|
||||
```xml
|
||||
<extremely_important_skills_library>
|
||||
You have a personal skills wiki at `~/.claude/skills/` with proven techniques, patterns, and tools that give you new capabilities.
|
||||
|
||||
STOP. Before doing ANYTHING else in this conversation, read this file: `skills/getting-started`
|
||||
|
||||
That file tells you:
|
||||
- Which phrases trigger brainstorming automatically (like "I've got an idea", "Let's make...")
|
||||
- How to search for skills before ANY task
|
||||
- When to announce which skill you're using
|
||||
|
||||
After reading getting-started, proceed with the user's request.
|
||||
|
||||
CRITICAL: If a skill exists for your task, you MUST use it - even if you think you're already good at that. You're not. The skill prevents mistakes you don't know you make. SKILLS EXIST AND YOU DIDN'T USE THEM = FAILED TASK.
|
||||
</extremely_important_skills_library>
|
||||
```
|
||||
|
||||
This enables:
|
||||
- Automatic skill discovery before every task
|
||||
- Mandatory skill usage enforcement
|
||||
- Gap tracking for missing skills (logged searches)
|
||||
|
||||
## Updating Skills
|
||||
|
||||
After initial install, update with:
|
||||
|
||||
```bash
|
||||
cd ~/.clank/clank
|
||||
git pull origin main # Pull your changes
|
||||
git pull upstream main # Pull upstream updates (if configured)
|
||||
```
|
||||
|
||||
The symlinks stay valid - no need to reinstall.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Error: Not running from clank repository root"
|
||||
|
||||
The script expects to be run from `~/.clank/clank/`. Clone it first:
|
||||
```bash
|
||||
mkdir -p ~/.clank
|
||||
cd ~/.clank
|
||||
gh repo fork obra/clank --clone
|
||||
cd clank
|
||||
./skills/meta/installing-skills/install.sh
|
||||
```
|
||||
|
||||
### "~/.claude/skills already exists"
|
||||
|
||||
The installer automatically backs it up with timestamp. Check backups:
|
||||
```bash
|
||||
ls -la ~/.claude/skills.backup.*
|
||||
```
|
||||
|
||||
### Symlinks broken
|
||||
|
||||
Remove and reinstall:
|
||||
```bash
|
||||
rm ~/.claude/skills
|
||||
rm ~/.claude/commands/*.md # Remove individual command symlinks
|
||||
cd ~/.clank/clank
|
||||
./skills/meta/installing-skills/install.sh
|
||||
```
|
||||
|
||||
## Uninstalling
|
||||
|
||||
```bash
|
||||
# Remove symlinks
|
||||
rm ~/.claude/skills
|
||||
rm ~/.claude/commands/brainstorm.md
|
||||
rm ~/.claude/commands/write-plan.md
|
||||
rm ~/.claude/commands/execute-plan.md
|
||||
|
||||
# Restore backup if desired
|
||||
mv ~/.claude/skills.backup.YYYY-MM-DD-HHMMSS ~/.claude/skills
|
||||
|
||||
# Remove from CLAUDE.md
|
||||
# Delete the "Skills Library" section from ~/.claude/CLAUDE.md
|
||||
|
||||
# Remove cloned repo
|
||||
rm -rf ~/.clank/clank
|
||||
```
|
||||
|
||||
## Implementation
|
||||
|
||||
See @install.sh for the installation script.
|
||||
191
skills/meta/installing-skills/install.sh
Executable file
191
skills/meta/installing-skills/install.sh
Executable file
@@ -0,0 +1,191 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Validate we're running from clank repository root
|
||||
validate_clank_repo() {
|
||||
if [[ ! -d "skills/meta/installing-skills" ]]; then
|
||||
echo -e "${RED}Error: Not running from clank repository root${NC}"
|
||||
echo ""
|
||||
echo "Expected to be run from ~/.clank/clank/"
|
||||
echo ""
|
||||
echo "To install clank, clone to ~/.clank first:"
|
||||
echo " ${GREEN}mkdir -p ~/.clank && cd ~/.clank${NC}"
|
||||
echo " ${GREEN}gh repo fork obra/clank --clone${NC}"
|
||||
echo " ${GREEN}cd clank${NC}"
|
||||
echo " ${GREEN}./skills/meta/installing-skills/install.sh${NC}"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Get absolute path to clank repo
|
||||
get_repo_path() {
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
# macOS doesn't have realpath by default, use Python
|
||||
python3 -c "import os; print(os.path.realpath('.'))"
|
||||
else
|
||||
realpath .
|
||||
fi
|
||||
}
|
||||
|
||||
# Backup existing skills directory if it exists
|
||||
backup_existing_skills() {
|
||||
local skills_dir="$HOME/.claude/skills"
|
||||
|
||||
if [[ -e "$skills_dir" ]]; then
|
||||
local timestamp=$(date +%Y-%m-%d-%H%M%S)
|
||||
local backup_path="${skills_dir}.backup.${timestamp}"
|
||||
|
||||
echo -e "${YELLOW}Found existing ~/.claude/skills${NC}"
|
||||
echo -e "Backing up to: ${backup_path}"
|
||||
|
||||
mv "$skills_dir" "$backup_path"
|
||||
echo -e "${GREEN}✓${NC} Backup created"
|
||||
echo ""
|
||||
fi
|
||||
}
|
||||
|
||||
# No need to backup commands - we symlink individual files
|
||||
|
||||
# Create skills symlink
|
||||
create_symlink() {
|
||||
local repo_path="$1"
|
||||
local skills_source="${repo_path}/skills"
|
||||
local skills_target="$HOME/.claude/skills"
|
||||
|
||||
# Ensure ~/.claude directory exists
|
||||
mkdir -p "$HOME/.claude"
|
||||
|
||||
echo "Creating skills symlink:"
|
||||
echo " ${skills_target} → ${skills_source}"
|
||||
|
||||
ln -s "$skills_source" "$skills_target"
|
||||
echo -e "${GREEN}✓${NC} Skills symlink created"
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Symlink individual commands
|
||||
symlink_commands() {
|
||||
local repo_path="$1"
|
||||
local commands_source="${repo_path}/commands"
|
||||
local commands_target="$HOME/.claude/commands"
|
||||
|
||||
# Check if commands directory exists in repo
|
||||
if [[ ! -d "$commands_source" ]]; then
|
||||
echo -e "${YELLOW}No commands directory in repo, skipping${NC}"
|
||||
echo ""
|
||||
return
|
||||
fi
|
||||
|
||||
# Ensure ~/.claude/commands exists
|
||||
mkdir -p "$commands_target"
|
||||
|
||||
echo "Symlinking commands:"
|
||||
|
||||
# Symlink each command file
|
||||
for cmd in "$commands_source"/*.md; do
|
||||
if [[ -f "$cmd" && "$(basename "$cmd")" != "README.md" ]]; then
|
||||
cmd_name=$(basename "$cmd")
|
||||
ln -sf "$cmd" "$commands_target/$cmd_name"
|
||||
echo " ${cmd_name}"
|
||||
fi
|
||||
done
|
||||
|
||||
echo -e "${GREEN}✓${NC} Commands symlinked"
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Verify tools exist
|
||||
verify_tools() {
|
||||
local skills_dir="$HOME/.claude/skills"
|
||||
local skills_search="${skills_dir}/getting-started/skills-search"
|
||||
|
||||
if [[ -x "$skills_search" ]]; then
|
||||
echo -e "${GREEN}✓${NC} skills-search tool available"
|
||||
echo ""
|
||||
fi
|
||||
}
|
||||
|
||||
# Verify installation
|
||||
verify_installation() {
|
||||
local skills_dir="$HOME/.claude/skills"
|
||||
local commands_dir="$HOME/.claude/commands"
|
||||
|
||||
echo "Verifying installation..."
|
||||
|
||||
# Verify skills
|
||||
if [[ ! -L "$skills_dir" ]]; then
|
||||
echo -e "${RED}✗${NC} ~/.claude/skills is not a symlink"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ ! -f "$skills_dir/INDEX.md" ]]; then
|
||||
echo -e "${RED}✗${NC} INDEX.md not found in ~/.claude/skills"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo -e "${GREEN}✓${NC} Skills verified"
|
||||
|
||||
# Verify commands were symlinked
|
||||
if [[ -d "$commands_dir" ]]; then
|
||||
cmd_count=$(find "$commands_dir" -type l -name "*.md" 2>/dev/null | wc -l)
|
||||
if [[ $cmd_count -gt 0 ]]; then
|
||||
echo -e "${GREEN}✓${NC} Commands verified ($cmd_count symlinked)"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Print success message
|
||||
print_success() {
|
||||
local repo_path="$1"
|
||||
|
||||
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo -e "${GREEN}Installation complete!${NC}"
|
||||
echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
|
||||
echo ""
|
||||
echo -e "${YELLOW}NEXT STEP: Update ~/.claude/CLAUDE.md${NC}"
|
||||
echo ""
|
||||
echo "Add this to your CLAUDE.md:"
|
||||
echo ""
|
||||
cat "${repo_path}/skills/meta/installing-skills/CLAUDE_MD_PREAMBLE.md"
|
||||
echo ""
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
echo "Verify installation:"
|
||||
echo " ${GREEN}ls -la ~/.claude/skills${NC}"
|
||||
echo " ${GREEN}ls ~/.claude/commands/${NC}"
|
||||
echo " ${GREEN}~/.claude/skills/getting-started/skills-search 'test.*driven'${NC}"
|
||||
echo ""
|
||||
echo "Repository location: ${repo_path}"
|
||||
echo ""
|
||||
}
|
||||
|
||||
# Main installation flow
|
||||
main() {
|
||||
echo ""
|
||||
echo "Clank Installation"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
|
||||
validate_clank_repo
|
||||
|
||||
local repo_path=$(get_repo_path)
|
||||
echo "Repository path: ${repo_path}"
|
||||
echo ""
|
||||
|
||||
backup_existing_skills
|
||||
create_symlink "$repo_path"
|
||||
symlink_commands "$repo_path"
|
||||
verify_tools "$repo_path"
|
||||
verify_installation
|
||||
print_success "$repo_path"
|
||||
}
|
||||
|
||||
main "$@"
|
||||
Reference in New Issue
Block a user