mirror of
https://github.com/obra/superpowers.git
synced 2026-04-22 01:19:04 +08:00
Add personal superpowers overlay system
Enables users to write and manage their own skills alongside core skills.
## Key Features:
- Auto-setup on first session: Creates ~/.config/superpowers/ git repo
- Two-tier skills: Personal skills shadow core skills when paths match
- Environment variable support: PERSONAL_SUPERPOWERS_DIR, XDG_CONFIG_HOME
- GitHub integration: Optional public repo creation for sharing skills
- CLI-agnostic: Works across Claude Code, Codex CLI, Gemini CLI (future)
## Changes:
- Added hooks/setup-personal-superpowers.sh - Auto-initializes personal repo
- Updated hooks/session-start.sh - Runs setup, offers GitHub repo creation
- Updated list-skills, skills-search - Search both personal and core skills
- Renamed skills/meta/creating-skills → writing-skills
- Added skills/meta/setting-up-personal-superpowers - Setup documentation
- Added skills/meta/sharing-skills - Contribution workflow
- Removed skills/meta/installing-skills - Old ~/.clank system
- Removed all INDEX.md files - Replaced by list-skills tool
- Updated README.md, getting-started - Document personal skills workflow
## Architecture:
~/.config/superpowers/skills/ # Personal (user-created, git-tracked)
${CLAUDE_PLUGIN_ROOT}/skills/ # Core (read-only, from plugin)
Search order: Personal first, core second (first match wins)
This commit is contained in:
Jesse Vincent
@@ -1,14 +0,0 @@
|
||||
# Meta Skills
|
||||
|
||||
Skills about skills - how to create and use the skills system.
|
||||
|
||||
## Available Skills
|
||||
|
||||
- skills/meta/installing-skills - Fork, clone, and symlink clank repo to ~/.claude/skills. Use for initial setup, installing clank for the first time.
|
||||
|
||||
- skills/meta/creating-skills - How to create effective skills for future Claude instances. Use when you discover a technique, pattern, or tool worth documenting for reuse.
|
||||
|
||||
- skills/meta/testing-skills-with-subagents - Iteratively test and bulletproof skills using pressure scenarios and rationalization analysis. Use after writing skills that enforce discipline or rules, before deploying skills agents might want to bypass.
|
||||
|
||||
- skills/meta/gardening-skills-wiki - Maintain skills wiki health with automated checks for broken links, naming consistency, and INDEX coverage. Use when adding/removing skills, reorganizing categories, or for periodic maintenance.
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
<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>
|
||||
@@ -1,224 +0,0 @@
|
||||
---
|
||||
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.
|
||||
@@ -1,191 +0,0 @@
|
||||
#!/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 "$@"
|
||||
162
skills/meta/setting-up-personal-superpowers/SKILL.md
Normal file
162
skills/meta/setting-up-personal-superpowers/SKILL.md
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
name: Setting Up Personal Superpowers
|
||||
description: Automatic setup of ~/.config/superpowers/ for personal skills, optional GitHub repo creation
|
||||
when_to_use: Runs automatically on first session. Reference when helping users with personal skills setup.
|
||||
version: 1.0.0
|
||||
languages: bash
|
||||
---
|
||||
|
||||
# Setting Up Personal Superpowers
|
||||
|
||||
## Overview
|
||||
|
||||
Personal superpowers directory is automatically set up on your first session. It provides a place to create and manage your own skills alongside the core superpowers library.
|
||||
|
||||
**Default location:** `~/.config/superpowers/`
|
||||
|
||||
**Customizable via:**
|
||||
- `PERSONAL_SUPERPOWERS_DIR` environment variable (highest priority)
|
||||
- `XDG_CONFIG_HOME` environment variable (if set, uses `$XDG_CONFIG_HOME/superpowers`)
|
||||
- Falls back to `~/.config/superpowers`
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
~/.config/superpowers/
|
||||
├── .git/ # Git repository
|
||||
├── .gitignore # Ignores logs and indexes
|
||||
├── README.md # About your personal superpowers
|
||||
├── skills/ # Your personal skills
|
||||
│ └── your-skill/
|
||||
│ └── SKILL.md
|
||||
├── search-log.jsonl # Skill search history (not tracked)
|
||||
└── conversation-index/ # Conversation search index (not tracked)
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
The SessionStart hook runs `hooks/setup-personal-superpowers.sh` which:
|
||||
|
||||
1. Checks if `~/.config/superpowers/.git/` and `~/.config/superpowers/skills/` exist
|
||||
2. If not, creates directory structure
|
||||
3. Initializes git repository
|
||||
4. Creates `.gitignore`, `README.md`
|
||||
5. Makes initial commit
|
||||
6. Checks for `gh` CLI availability
|
||||
|
||||
If GitHub CLI is available and no remote exists, you'll see a recommendation to create a public GitHub repo.
|
||||
|
||||
## Creating GitHub Repository
|
||||
|
||||
When prompted, you can create a public `personal-superpowers` repo:
|
||||
|
||||
```bash
|
||||
cd ~/.config/superpowers
|
||||
gh repo create personal-superpowers --public --source=. --push
|
||||
gh repo edit --add-topic superpowers
|
||||
```
|
||||
|
||||
**Why public?** Superpowers are best when everyone can learn from them!
|
||||
|
||||
**Privacy:** If you prefer private or local-only:
|
||||
- **Private:** Use `--private` instead of `--public`
|
||||
- **Local-only:** Just use the local git repo without pushing to GitHub
|
||||
|
||||
## What Gets Tracked
|
||||
|
||||
**.gitignore includes:**
|
||||
- `search-log.jsonl` - Your skill search history
|
||||
- `conversation-index/` - Conversation search index
|
||||
- `conversation-archive/` - Archived conversations
|
||||
|
||||
**Everything else is tracked**, including:
|
||||
- Your personal skills in `skills/`
|
||||
- README.md
|
||||
- Any additional documentation you add
|
||||
|
||||
## Personal vs Core Skills
|
||||
|
||||
**Search order:**
|
||||
1. `~/.config/superpowers/skills/` (personal)
|
||||
2. `${CLAUDE_PLUGIN_ROOT}/skills/` (core)
|
||||
|
||||
**Personal skills shadow core skills** - if you have `~/.config/superpowers/skills/testing/test-driven-development/SKILL.md`, it will be used instead of the core version.
|
||||
|
||||
The `list-skills` and `skills-search` tools automatically search both locations with deduplication.
|
||||
|
||||
## Writing Skills
|
||||
|
||||
See skills/meta/writing-skills for how to create new skills.
|
||||
|
||||
All personal skills are written to `~/.config/superpowers/skills/`.
|
||||
|
||||
## Sharing Skills
|
||||
|
||||
See skills/meta/sharing-skills for how to contribute skills back to the core superpowers repository.
|
||||
|
||||
## Custom Location
|
||||
|
||||
To use a different location for your personal superpowers:
|
||||
|
||||
```bash
|
||||
# In your shell rc file (.bashrc, .zshrc, etc)
|
||||
export PERSONAL_SUPERPOWERS_DIR="$HOME/my-superpowers"
|
||||
|
||||
# Or use XDG_CONFIG_HOME
|
||||
export XDG_CONFIG_HOME="$HOME/.local/config" # Will use $HOME/.local/config/superpowers
|
||||
```
|
||||
|
||||
## Manual Setup
|
||||
|
||||
If auto-setup fails or you need to set up manually:
|
||||
|
||||
```bash
|
||||
# Use your preferred location
|
||||
SUPERPOWERS_DIR="${PERSONAL_SUPERPOWERS_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/superpowers}"
|
||||
mkdir -p "$SUPERPOWERS_DIR/skills"
|
||||
cd "$SUPERPOWERS_DIR"
|
||||
git init
|
||||
cat > .gitignore <<'EOF'
|
||||
search-log.jsonl
|
||||
conversation-index/
|
||||
conversation-archive/
|
||||
EOF
|
||||
|
||||
cat > README.md <<'EOF'
|
||||
# My Personal Superpowers
|
||||
|
||||
Personal skills and techniques for Claude Code.
|
||||
|
||||
Learn more about Superpowers: https://github.com/obra/superpowers
|
||||
EOF
|
||||
|
||||
git add .gitignore README.md
|
||||
git commit -m "Initial commit: Personal superpowers setup"
|
||||
|
||||
# Optional: Create GitHub repo
|
||||
gh repo create personal-superpowers --public --source=. --push
|
||||
gh repo edit --add-topic superpowers
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Setup failed during SessionStart:**
|
||||
File a bug at https://github.com/obra/superpowers/issues
|
||||
|
||||
**Personal skills not being found:**
|
||||
- Check `~/.config/superpowers/skills/` exists
|
||||
- Verify skill has `SKILL.md` file
|
||||
- Run `${CLAUDE_PLUGIN_ROOT}/skills/getting-started/list-skills` to see if it appears
|
||||
|
||||
**GitHub push failed:**
|
||||
- Check `gh auth status`
|
||||
- Verify repo was created: `gh repo view personal-superpowers`
|
||||
- Try manual push: `cd ~/.config/superpowers && git push -u origin main`
|
||||
|
||||
## Multi-CLI Support
|
||||
|
||||
The personal superpowers directory is CLI-agnostic. It works with:
|
||||
- Claude Code (current)
|
||||
- OpenAI Codex CLI (future)
|
||||
- Gemini CLI (future)
|
||||
|
||||
Each CLI installs its own base superpowers, but they all read from the same `~/.config/superpowers/skills/` for personal skills.
|
||||
240
skills/meta/sharing-skills/SKILL.md
Normal file
240
skills/meta/sharing-skills/SKILL.md
Normal file
@@ -0,0 +1,240 @@
|
||||
---
|
||||
name: Sharing Skills
|
||||
description: Contribute personal skills back to core superpowers via fork, branch, and PR
|
||||
when_to_use: When you have a personal skill that would benefit others and want to contribute it to the core superpowers library
|
||||
version: 1.0.0
|
||||
languages: bash
|
||||
---
|
||||
|
||||
# Sharing Skills
|
||||
|
||||
## Overview
|
||||
|
||||
Contribute personal skills from `~/.config/superpowers/skills/` back to the core superpowers repository.
|
||||
|
||||
**Workflow:** Fork → Clone to temp → Sync → Branch → Copy skill → Commit → Push → PR
|
||||
|
||||
## When to Share
|
||||
|
||||
**Share when:**
|
||||
- Skill applies broadly (not project-specific)
|
||||
- Pattern/technique others would benefit from
|
||||
- Well-tested and documented
|
||||
- Follows skills/meta/writing-skills guidelines
|
||||
|
||||
**Keep personal when:**
|
||||
- Project-specific or organization-specific
|
||||
- Experimental or unstable
|
||||
- Contains sensitive information
|
||||
- Too narrow/niche for general use
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- `gh` CLI installed and authenticated
|
||||
- Personal skill exists in `~/.config/superpowers/skills/your-skill/`
|
||||
- Skill has been tested (see skills/meta/writing-skills for TDD process)
|
||||
|
||||
## Sharing Workflow
|
||||
|
||||
### 1. Fork Core Repository
|
||||
|
||||
```bash
|
||||
# Check if you already have a fork
|
||||
gh repo view YOUR_USERNAME/superpowers 2>/dev/null || gh repo fork obra/superpowers
|
||||
```
|
||||
|
||||
### 2. Clone to Temporary Directory
|
||||
|
||||
```bash
|
||||
# Create temp directory for contribution
|
||||
temp_dir=$(mktemp -d)
|
||||
cd "$temp_dir"
|
||||
git clone git@github.com:YOUR_USERNAME/superpowers.git
|
||||
cd superpowers
|
||||
```
|
||||
|
||||
### 3. Sync with Upstream
|
||||
|
||||
```bash
|
||||
# Add upstream if not already added
|
||||
git remote add upstream https://github.com/obra/superpowers 2>/dev/null || true
|
||||
|
||||
# Fetch and merge latest from upstream
|
||||
git fetch upstream
|
||||
git checkout main
|
||||
git merge upstream/main
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### 4. Create Feature Branch
|
||||
|
||||
```bash
|
||||
# Branch name: add-skillname-skill
|
||||
skill_name="your-skill-name"
|
||||
git checkout -b "add-${skill_name}-skill"
|
||||
```
|
||||
|
||||
### 5. Copy Skill from Personal Repo
|
||||
|
||||
```bash
|
||||
# Copy skill directory from personal superpowers
|
||||
cp -r ~/.config/superpowers/skills/your-skill-name/ superpowers/skills/
|
||||
|
||||
# Verify it copied correctly
|
||||
ls -la superpowers/skills/your-skill-name/
|
||||
```
|
||||
|
||||
### 6. Commit Changes
|
||||
|
||||
```bash
|
||||
# Add and commit
|
||||
git add superpowers/skills/your-skill-name/
|
||||
git commit -m "Add ${skill_name} skill
|
||||
|
||||
$(cat <<'EOF'
|
||||
Brief description of what this skill does and why it's useful.
|
||||
|
||||
Tested with: [describe testing approach]
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### 7. Push to Your Fork
|
||||
|
||||
```bash
|
||||
git push -u origin "add-${skill_name}-skill"
|
||||
```
|
||||
|
||||
### 8. Create Pull Request
|
||||
|
||||
```bash
|
||||
# Create PR using gh CLI
|
||||
gh pr create \
|
||||
--repo obra/superpowers \
|
||||
--title "Add ${skill_name} skill" \
|
||||
--body "$(cat <<'EOF'
|
||||
## Summary
|
||||
Brief description of the skill and what problem it solves.
|
||||
|
||||
## Testing
|
||||
Describe how you tested this skill (pressure scenarios, baseline tests, etc.).
|
||||
|
||||
## Context
|
||||
Any additional context about why this skill is needed and how it should be used.
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### 9. Cleanup
|
||||
|
||||
```bash
|
||||
# Remove temp directory after PR is created
|
||||
cd ~
|
||||
rm -rf "$temp_dir"
|
||||
```
|
||||
|
||||
## Complete Example
|
||||
|
||||
Here's a complete example of sharing a personal skill called "async-patterns":
|
||||
|
||||
```bash
|
||||
# 1. Fork if needed
|
||||
gh repo view $(gh api user --jq .login)/superpowers 2>/dev/null || gh repo fork obra/superpowers
|
||||
|
||||
# 2-3. Clone and sync
|
||||
temp_dir=$(mktemp -d) && cd "$temp_dir"
|
||||
gh repo clone $(gh api user --jq .login)/superpowers
|
||||
cd superpowers
|
||||
git remote add upstream https://github.com/obra/superpowers 2>/dev/null || true
|
||||
git fetch upstream
|
||||
git checkout main
|
||||
git merge upstream/main
|
||||
git push origin main
|
||||
|
||||
# 4. Create branch
|
||||
git checkout -b "add-async-patterns-skill"
|
||||
|
||||
# 5. Copy skill
|
||||
cp -r ~/.config/superpowers/skills/async-patterns/ superpowers/skills/
|
||||
|
||||
# 6. Commit
|
||||
git add superpowers/skills/async-patterns/
|
||||
git commit -m "Add async-patterns skill
|
||||
|
||||
Patterns for handling asynchronous operations in tests and application code.
|
||||
|
||||
Tested with: Multiple pressure scenarios testing agent compliance."
|
||||
|
||||
# 7. Push
|
||||
git push -u origin "add-async-patterns-skill"
|
||||
|
||||
# 8. Create PR
|
||||
gh pr create \
|
||||
--repo obra/superpowers \
|
||||
--title "Add async-patterns skill" \
|
||||
--body "## Summary
|
||||
Patterns for handling asynchronous operations correctly in tests and application code.
|
||||
|
||||
## Testing
|
||||
Tested with multiple application scenarios. Agents successfully apply patterns to new code.
|
||||
|
||||
## Context
|
||||
Addresses common async pitfalls like race conditions, improper error handling, and timing issues."
|
||||
|
||||
# 9. Cleanup
|
||||
cd ~ && rm -rf "$temp_dir"
|
||||
```
|
||||
|
||||
## After PR is Merged
|
||||
|
||||
Once your PR is merged:
|
||||
|
||||
**Option 1: Keep personal version**
|
||||
- Useful if you want to continue iterating locally
|
||||
- Your personal version will shadow the core version
|
||||
- Can later delete personal version to use core
|
||||
|
||||
**Option 2: Delete personal version**
|
||||
```bash
|
||||
# Remove from personal repo to use core version
|
||||
rm -rf ~/.config/superpowers/skills/your-skill-name/
|
||||
cd ~/.config/superpowers
|
||||
git add skills/your-skill-name/
|
||||
git commit -m "Remove your-skill-name (now in core)"
|
||||
git push
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"gh: command not found"**
|
||||
- Install GitHub CLI: https://cli.github.com/
|
||||
- Authenticate: `gh auth login`
|
||||
|
||||
**"Permission denied (publickey)"**
|
||||
- Check SSH keys: `gh auth status`
|
||||
- Set up SSH: https://docs.github.com/en/authentication
|
||||
|
||||
**"Skill already exists in core"**
|
||||
- You're creating a modified version
|
||||
- Consider different skill name or shadow the core version in personal repo
|
||||
|
||||
**PR merge conflicts**
|
||||
- Rebase on latest upstream: `git fetch upstream && git rebase upstream/main`
|
||||
- Resolve conflicts
|
||||
- Force push: `git push -f origin your-branch`
|
||||
|
||||
## Multi-Skill Contributions
|
||||
|
||||
**Do NOT batch multiple skills in one PR.**
|
||||
|
||||
Each skill should:
|
||||
- Have its own feature branch
|
||||
- Have its own PR
|
||||
- Be independently reviewable
|
||||
|
||||
**Why?** Individual skills can be reviewed, iterated, and merged independently.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **skills/meta/writing-skills** - How to create well-tested skills
|
||||
- **skills/meta/setting-up-personal-superpowers** - Initial setup of personal repo
|
||||
@@ -1,16 +1,18 @@
|
||||
---
|
||||
name: Creating Skills
|
||||
name: Writing Skills
|
||||
description: TDD for process documentation - test with subagents before writing, iterate until bulletproof
|
||||
when_to_use: When you discover a technique, pattern, or tool worth documenting for reuse. When editing existing skills. When asked to modify skill documentation. When you've written a skill and need to verify it works before deploying.
|
||||
version: 4.1.0
|
||||
version: 5.0.0
|
||||
languages: all
|
||||
---
|
||||
|
||||
# Creating Skills
|
||||
# Writing Skills
|
||||
|
||||
## Overview
|
||||
|
||||
**Creating skills IS Test-Driven Development applied to process documentation.**
|
||||
**Writing skills IS Test-Driven Development applied to process documentation.**
|
||||
|
||||
**All personal skills are written to `~/.config/superpowers/skills/`** - this is your personal superpowers repository, separate from the core superpowers library.
|
||||
|
||||
You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
|
||||
|
||||
@@ -69,14 +71,16 @@ API docs, syntax guides, tool documentation (office docs)
|
||||
|
||||
## Directory Structure
|
||||
|
||||
**All skills are written to `~/.config/superpowers/skills/`:**
|
||||
|
||||
```
|
||||
skills/
|
||||
~/.config/superpowers/skills/
|
||||
skill-name/
|
||||
SKILL.md # Main reference (required)
|
||||
supporting-file.* # Only if needed
|
||||
```
|
||||
|
||||
**Flat namespace** - all skills in one searchable location
|
||||
**Flat namespace** - all personal skills in one searchable location
|
||||
|
||||
**Separate files for:**
|
||||
1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax
|
||||
@@ -527,7 +531,6 @@ helper1, helper2, step3, pattern4
|
||||
|
||||
**Do NOT:**
|
||||
- Create multiple skills in batch without testing each
|
||||
- Update INDEX.md before testing skills
|
||||
- Move to next skill before current one is verified
|
||||
- Skip testing because "batching is more efficient"
|
||||
|
||||
@@ -573,7 +576,7 @@ Deploying untested skills = deploying untested code. It's a violation of quality
|
||||
How future Claude finds your skill:
|
||||
|
||||
1. **Encounters problem** ("tests are flaky")
|
||||
2. **Greps skills** (`grep -r "flaky" ~/.claude/skills/`)
|
||||
2. **Searches skills** using `skills-search` tool (checks personal then core)
|
||||
3. **Finds SKILL.md** (rich when_to_use matches)
|
||||
4. **Scans overview** (is this relevant?)
|
||||
5. **Reads patterns** (quick reference table)
|
||||
Reference in New Issue
Block a user