find-skills
#!/usr/bin/env bash
# find-skills - Find and list skills with when_to_use guidance
# Shows all skills by default, filters by pattern if provided
set -euo pipefail
# Determine directories
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILLS_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
SUPERPOWERS_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/superpowers"
LOG_FILE="${SUPERPOWERS_DIR}/search-log.jsonl"
# Show help
if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
cat <<'EOF'
find-skills - Find and list skills with when_to_use guidance
USAGE:
find-skills Show all skills with when_to_use guidance
find-skills PATTERN Filter skills by grep pattern
find-skills --help Show this help
EXAMPLES:
find-skills # All skills
find-skills test # Skills matching "test"
find-skills 'test.*driven|TDD' # Regex pattern
OUTPUT:
Each line shows: Use skill-path/SKILL.md when [trigger]
Paths include /SKILL.md for direct use with Read tool
SEARCH:
Searches both skill content AND path names.
Skills location: ~/.config/superpowers/skills/
EOF
exit 0
fi
# Get pattern (optional)
PATTERN="${1:-}"
# Function to extract when_to_use from SKILL.md
get_when_to_use() {
local file="$1"
grep "^when_to_use:" "$file" 2>/dev/null | head -1 | sed 's/when_to_use: *//' || echo ""
}
# Function to get relative skill path (includes /SKILL.md)
get_skill_path() {
local file="$1"
local base_dir="$2"
local rel_path="${file#$base_dir/}"
echo "$rel_path"
}
# Collect all matching skills
results=()
# If pattern provided, log the search
if [[ -n "$PATTERN" ]]; then
timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "{\"timestamp\":\"$timestamp\",\"query\":\"$PATTERN\"}" >> "$LOG_FILE" 2>/dev/null || true
fi
# Search skills directory
while IFS= read -r file; do
[[ -z "$file" ]] && continue
skill_path=$(get_skill_path "$file" "$SKILLS_DIR")
when_to_use=$(get_when_to_use "$file")
results+=("$skill_path|$when_to_use")
done < <(
if [[ -n "$PATTERN" ]]; then
# Pattern mode: search content and paths
{
grep -E -r -- "$PATTERN" "$SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true
find "$SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null | grep -E -- "$PATTERN" 2>/dev/null || true
} | sort -u
else
# Show all
find "$SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true
fi
)
# Check if we found anything
if [[ ${#results[@]} -eq 0 ]]; then
if [[ -n "$PATTERN" ]]; then
echo "❌ No skills found matching: $PATTERN"
echo ""
echo "Search logged. If a skill should exist, consider writing it!"
else
echo "❌ No skills found"
fi
exit 0
fi
# Sort and display results
printf "%s\n" "${results[@]}" | sort | while IFS='|' read -r skill_path when_to_use; do
if [[ -n "$when_to_use" ]]; then
echo "Use $skill_path $when_to_use"
else
echo "$skill_path"
fi
done
exit 0
skill-run
#!/usr/bin/env bash
# Generic runner for skill scripts
#
# Usage: scripts/skill-run <skill-relative-path> [args...]
# Example: scripts/skill-run skills/collaboration/remembering-conversations/tool/search-conversations "query"
set -euo pipefail
if [[ $# -eq 0 ]]; then
cat <<'EOF'
Usage: scripts/skill-run <skill-relative-path> [args...]
Runs scripts from skills directory.
Examples:
scripts/skill-run skills/collaboration/remembering-conversations/tool/search-conversations "query"
scripts/skill-run skills/collaboration/remembering-conversations/tool/index-conversations --cleanup
The script will be found at:
${SUPERPOWERS_SKILLS_ROOT}/<skill-relative-path>
EOF
exit 1
fi
# Get the script path to run
SCRIPT_PATH="$1"
shift # Remove script path from args, leaving remaining args
# Determine directories
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILLS_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
# Try to run the script
SCRIPT="${SKILLS_ROOT}/${SCRIPT_PATH}"
if [[ -x "$SCRIPT" ]]; then
exec "$SCRIPT" "$@"
fi
# Not found
echo "Error: Script not found: $SCRIPT_PATH" >&2
echo "" >&2
echo "Searched:" >&2
echo " $SCRIPT" >&2
exit 1
SKILL.md
---
name: Getting Started with Skills
description: Skills wiki intro - mandatory workflows, search tool, brainstorming triggers
when_to_use: when starting any conversation
version: 4.0.2
---
# Getting Started with Skills
## Critical Rules
1. **Use Read tool before announcing skill usage.** The session-start hook does NOT read skills for you. Announcing without calling Read = lying.
2. **Follow mandatory workflows.** Brainstorming before coding. Check for skills before ANY task.
3. **Create TodoWrite todos for checklists.** Mental tracking = steps get skipped. Every time.
## Mandatory Workflow: Before ANY Task
**1. Check skills list** at session start, or run `find-skills [PATTERN]` to filter.
**2. If relevant skill exists, YOU MUST use it:**
- Use Read tool with full path: `${SUPERPOWERS_SKILLS_ROOT}/skills/category/skill-name/SKILL.md`
- Read ENTIRE file, not just frontmatter
- Announce: "I've read [Skill Name] skill and I'm using it to [purpose]"
- Follow it exactly
**Don't rationalize:**
- "I remember this skill" - Skills evolve. Read the current version.
- "Session-start showed it to me" - That was using-skills/SKILL.md only. Read the actual skill.
- "This doesn't count as a task" - It counts. Find and read skills.
**Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
If a skill for your task exists, you must use it or you will fail at your task.
## Skills with Checklists
If a skill has a checklist, YOU MUST create TodoWrite todos for EACH 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. The overhead of TodoWrite is tiny compared to the cost of missing steps.
**Examples:** skills/testing/test-driven-development/SKILL.md, skills/debugging/systematic-debugging/SKILL.md, skills/meta/writing-skills/SKILL.md
## 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]."
**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."
**Why:** Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the skill.
## How to Read a Skill
Every skill has the same structure:
1. **Frontmatter** - `when_to_use` tells you if this skill matches your situation
2. **Overview** - Core principle in 1-2 sentences
3. **Quick Reference** - Scan for your specific pattern
4. **Implementation** - Full details and examples
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.
## Instructions ≠ Permission to Skip Workflows
Your human partner's specific instructions describe WHAT to do, not HOW.
"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
**Red flags:** "Instruction was specific" • "Seems simple" • "Workflow is overkill"
**Why:** Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.
## Summary
**Starting any task:**
1. Run find-skills to check for relevant skills
2. If relevant skill exists → Use Read tool with full path (includes /SKILL.md)
3. Announce you're using it
4. Follow what it says
**Skill has checklist?** TodoWrite for every item.
**Finding a relevant skill = mandatory to read and use it. Not optional.**