Claude Code Superpowers — Contributor Guidelines
Overview
This repo ships 24 skills across 5 layers: discipline, domain expertise, intelligence, coordination, and execution. Skills are Markdown files that shape Claude's behavior — they are code, not prose.
If You Are an AI Agent
Read this before doing anything else.
Skills are behavior-shaping instructions. Modifying them incorrectly can cause Claude to follow the wrong workflow silently — no error, just wrong behavior. The bar for changes is high.
Before proposing any change you MUST:
- Identify the real problem — what specific session, error, or user experience motivated the change?
- Check for existing patterns — grep the skill for prior handling of this case
- Test the change — run the tests in
tests/ before claiming it works
- Show the diff — get explicit human approval on the complete diff before committing
If you cannot identify a real problem, do not make the change.
Skill Change Requirements
Skills are not documentation — they enforce agent behavior. When modifying any SKILL.md:
- Understand the Iron Law or core principle of the skill first
- Do not weaken enforcement language ("NEVER", "MANDATORY", "Iron Law")
- Do not add optional language ("consider", "might", "could") to required steps
- Run at minimum
tests/claude-code/test-helpers.sh assertions against the changed skill
- Document what behavior changed and why in the commit message
What Belongs in This Repo
In scope:
- General-purpose skills useful across all engineering projects
- Domain skills with broad applicability (ML, AI, Embedded, Frontend)
- Infrastructure improvements (hooks, tests, install script)
- Bug fixes with clear reproduction steps
Out of scope:
- Project-specific skills or workflows
- Skills for specific tools or services
- Rebranding or cosmetic changes
- Changes that weaken enforcement without eval evidence
Architecture
skills/ ← 5-layer skill system (24 skills)
Discipline: oracle, forge, hunter, sentinel, architect, blueprint
Domain: gradient, nexus, ironcore, prism
Intelligence: chronicle, horizon, pathfinder
Coordination: vector, legion, commander, phantom, tribunal, ascend
Execution: vault, seal, exodus, arbiter, sculptor
hooks/ ← SessionStart auto-loader (fires on startup/clear/compact)
agents/ ← code-reviewer agent definition
tests/ ← automated verification suite
install.sh ← one-line installer
examples/ ← memory system templates
Tests
Run before any PR:
# Fast skill behavior tests
bash tests/claude-code/run-skill-tests.sh
# Skill triggering tests (verify skills fire from real prompts)
bash tests/skill-triggering/run-all.sh
# Integration tests (slow, ~10-30 min)
bash tests/claude-code/run-skill-tests.sh --integration
Skill Name Mapping
This repo uses epic codenames. The mapping from workflow names:
| Codename | Workflow name |
|---|
| ORACLE | pre-task-intelligence |
| FORGE | test-driven-development |
| HUNTER | systematic-debugging |
| SENTINEL | verification-before-completion |
| ARCHITECT | design-before-code |
| BLUEPRINT | writing-plans |
| PHANTOM | executing-plans / subagent-driven-development |
| CHRONICLE | learning-from-experience |
| PATHFINDER | codebase-onboarding |
| VECTOR | model-routing |
| LEGION | swarm-coordination |
| COMMANDER | dispatching-parallel-agents |
| TRIBUNAL | requesting-code-review |
| ASCEND | using-superpowers |
| VAULT | using-git-worktrees |
| SEAL | finishing-a-development-branch |
| ARBITER | receiving-code-review |
| SCULPTOR | writing-skills |