mirror of
https://github.com/obra/superpowers.git
synced 2026-04-25 02:59: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
146
skills/getting-started/SKILL.md
Normal file
146
skills/getting-started/SKILL.md
Normal file
@@ -0,0 +1,146 @@
|
||||
---
|
||||
name: Getting Started with Skills
|
||||
description: Skills wiki intro - mandatory workflows, search tool, brainstorming triggers
|
||||
when_to_use: Read this FIRST at start of each conversation when skills are active
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Getting Started with Skills
|
||||
|
||||
Your personal wiki of proven techniques, patterns, and tools at `${CLAUDE_PLUGIN_ROOT}/skills/`.
|
||||
|
||||
## How to Reference Skills
|
||||
|
||||
**DO NOT use @ links** - they force-load entire files, burning 200k+ context instantly.
|
||||
|
||||
**INSTEAD, use skill path references:**
|
||||
- Format: `skills/category/skill-name` (no @ prefix, no /SKILL.md suffix)
|
||||
- Example: `skills/collaboration/brainstorming` or `skills/testing/test-driven-development`
|
||||
- Load with Read tool only when needed
|
||||
|
||||
**When you see skill references in documentation:**
|
||||
- `skills/path/name` → Use Read tool on `${CLAUDE_PLUGIN_ROOT}/skills/path/name/SKILL.md`
|
||||
- Load supporting files only when implementing
|
||||
|
||||
## Mandatory Workflow 1: Before ANY Task
|
||||
|
||||
**1. Search skills:**
|
||||
```bash
|
||||
${CLAUDE_PLUGIN_ROOT}/skills/getting-started/skills-search PATTERN
|
||||
```
|
||||
|
||||
**2. Search conversations:**
|
||||
Dispatch subagent (see Workflow 2) to check for relevant past work.
|
||||
|
||||
**If skills found:**
|
||||
1. READ the skill: `${CLAUDE_PLUGIN_ROOT}/skills/path/skill-name/SKILL.md`
|
||||
2. ANNOUNCE usage: "I'm using the [Skill Name] skill"
|
||||
3. FOLLOW the skill (many are rigid requirements)
|
||||
|
||||
**"This doesn't count as a task" is rationalization.** Skills/conversations exist and you didn't search for them or didn't use them = failed task.
|
||||
|
||||
## Mandatory Workflow 2: Historical Context Search
|
||||
|
||||
**When:** Your human partner mentions past work, issue feels familiar, starting task in familiar domain, stuck/blocked, before reinventing
|
||||
|
||||
**When NOT:** Info in current convo, codebase state questions, first encounter, partner wants fresh thinking
|
||||
|
||||
**How (use subagent for 50-100x context savings):**
|
||||
1. Dispatch subagent with template: `${CLAUDE_PLUGIN_ROOT}/skills/collaboration/remembering-conversations/tool/prompts/search-agent.md`
|
||||
2. Receive synthesis (200-1000 words) + source pointers
|
||||
3. Apply insights (never load raw .jsonl files)
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Partner: "How did we handle auth errors in React Router?"
|
||||
You: Searching past conversations...
|
||||
[Dispatch subagent → 350-word synthesis]
|
||||
[Apply without loading 50k tokens]
|
||||
```
|
||||
|
||||
**Red flags:** Reading .jsonl files directly, pasting excerpts, asking "which conversation?", browsing archives
|
||||
|
||||
**Pattern:** Search → Subagent synthesizes → Apply. Fast, focused, context-efficient.
|
||||
|
||||
## Announcing Skill Usage
|
||||
|
||||
**Every time you start using a skill, announce it:**
|
||||
|
||||
"I'm using the [Skill Name] skill to [what you're doing]."
|
||||
|
||||
**Examples:**
|
||||
- "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."
|
||||
- "I'm using the Systematic Debugging skill to find the root cause."
|
||||
- "I'm using the Refactoring Safely skill to extract these methods."
|
||||
|
||||
**Why:** Transparency helps your human partner understand your process and catch errors early.
|
||||
|
||||
## Skills with Checklists
|
||||
|
||||
**If a skill contains a checklist, you MUST create TodoWrite todos for EACH checklist item.**
|
||||
|
||||
**Don't:**
|
||||
- Work through checklist mentally
|
||||
- Skip creating todos "to save time"
|
||||
- Batch multiple items into one todo
|
||||
- Mark complete without doing them
|
||||
|
||||
**Why:** Checklists without TodoWrite tracking = steps get skipped. Every time.
|
||||
|
||||
**Examples:** TDD (write test, watch fail, implement, verify), Systematic Debugging (4 phases), Creating Skills (RED-GREEN-REFACTOR)
|
||||
|
||||
## Navigation
|
||||
|
||||
Really, try skills-search first.
|
||||
|
||||
**Categories:** skills/INDEX.md → testing, debugging, coding, architecture, collaboration, meta
|
||||
**Individual skill:** Load from category INDEX
|
||||
|
||||
## How to Read a Skill
|
||||
|
||||
1. **Frontmatter** - `when_to_use` match your situation?
|
||||
2. **Overview** - Core principle relevant?
|
||||
3. **Quick Reference** - Scan for your pattern
|
||||
4. **Implementation** - Full details
|
||||
5. **Supporting files** - Load only when implementing
|
||||
|
||||
**Many skills contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
|
||||
|
||||
**Some skills are flexible patterns (architecture, naming).** Adapt core principles to your context.
|
||||
|
||||
The skill itself tells you which type it is.
|
||||
|
||||
## Referencing Skills in Documentation
|
||||
|
||||
**When writing documentation that references other skills:**
|
||||
|
||||
Use path format without `@` prefix or `/SKILL.md` suffix:
|
||||
- ✅ Good: `skills/testing/test-driven-development`
|
||||
- ✅ Good: `skills/debugging/systematic-debugging`
|
||||
- ❌ 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.
|
||||
|
||||
**To read a skill reference:** Use Read tool on `${CLAUDE_PLUGIN_ROOT}/skills/category/skill-name/SKILL.md`
|
||||
|
||||
## Creating Skills
|
||||
|
||||
Found something valuable? See skills/meta/creating-skills
|
||||
|
||||
Want a skill that doesn't exist? Edit skills/REQUESTS.md (at ${CLAUDE_PLUGIN_ROOT}/skills/REQUESTS.md)
|
||||
|
||||
## Summary
|
||||
|
||||
**Starting conversation?** You just read this. Good.
|
||||
|
||||
**Starting any task?** Run skills-search first, announce usage, follow what you find.
|
||||
|
||||
**Skill has checklist?** TodoWrite for every item.
|
||||
|
||||
**Skills are mandatory when they exist, not optional.**
|
||||
|
||||
|
||||
## Last thing
|
||||
|
||||
In the first response after reading this guide, you MUST announce to the user that you have read the getting started guide
|
||||
83
skills/getting-started/skills-search
Executable file
83
skills/getting-started/skills-search
Executable file
@@ -0,0 +1,83 @@
|
||||
#!/usr/bin/env bash
|
||||
# skills-search - Find relevant skills using grep patterns
|
||||
# Logs all searches for gap analysis (gardening skill processes the log)
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
# Detect if running from repo or installed location
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
if [[ "$SCRIPT_DIR" == *"/.claude/skills/getting-started" ]]; then
|
||||
# Installed location
|
||||
SKILLS_DIR="${HOME}/.claude/skills"
|
||||
else
|
||||
# Running from repo
|
||||
SKILLS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
fi
|
||||
|
||||
LOG_FILE="${HOME}/.superpowers/search-log.jsonl"
|
||||
|
||||
# Show usage if no arguments
|
||||
if [[ $# -eq 0 ]]; then
|
||||
cat <<'EOF'
|
||||
Usage: skills-search PATTERN [PATTERN...]
|
||||
|
||||
Searches skills using grep patterns.
|
||||
|
||||
Examples:
|
||||
skills-search 'test.*driven|TDD'
|
||||
skills-search 'debug.*systematic|root.cause'
|
||||
skills-search 'refactor|extract'
|
||||
skills-search 'async.*test|flaky|timeout'
|
||||
skills-search 'validat.*input'
|
||||
|
||||
The search is logged. Failed searches help identify missing skills.
|
||||
EOF
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Log the search for gap analysis
|
||||
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
||||
query="$*"
|
||||
echo "{\"timestamp\":\"$timestamp\",\"query\":\"$query\"}" >> "$LOG_FILE" 2>/dev/null || true
|
||||
|
||||
# Search all SKILL.md files - both content AND path names
|
||||
# Content search: grep file contents
|
||||
content_matches=$(grep -E -r "$@" "$SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true)
|
||||
|
||||
# Filename search: find all SKILL.md paths, then grep the paths themselves
|
||||
all_skills=$(find "$SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true)
|
||||
path_matches=$(echo "$all_skills" | grep -E "$@" 2>/dev/null || true)
|
||||
|
||||
# Combine and deduplicate
|
||||
results=$(printf "%s\n%s" "$content_matches" "$path_matches" | sort -u | grep -v '^$' || true)
|
||||
|
||||
if [[ -z "$results" ]]; then
|
||||
echo "❌ No skills found matching: $*"
|
||||
echo ""
|
||||
echo "Search logged. If a skill should exist, it will be created."
|
||||
echo "Proceed carefully - document your approach."
|
||||
exit 0
|
||||
fi
|
||||
|
||||
echo "✅ Found skills:"
|
||||
echo ""
|
||||
|
||||
# Display results with metadata
|
||||
echo "$results" | while read -r file; do
|
||||
# Extract description from frontmatter
|
||||
description=$(grep "^description:" "$file" 2>/dev/null | sed 's/description: *//' || echo "")
|
||||
|
||||
# Get relative path without @ prefix or /SKILL.md suffix
|
||||
rel_path="${file#$SKILLS_DIR/}"
|
||||
rel_path="skills/${rel_path%/SKILL.md}"
|
||||
|
||||
if [[ -n "$description" ]]; then
|
||||
echo "$rel_path - $description"
|
||||
else
|
||||
echo "$rel_path"
|
||||
fi
|
||||
done
|
||||
|
||||
echo ""
|
||||
|
||||
exit 0
|
||||
Reference in New Issue
Block a user