Installation

How to install SuperSpecs into your local environment.

Prerequisites

Bash — setup.sh is the install script (macOS / Linux / WSL)
Node.js — only required if you use the npx / npm install path; not needed for direct bash usage

Installation Methods

Option 1 — Global clone (recommended)

Clone once, use in every project on your machine.

git clone https://github.com/your-org/superspecs.git ~/.superspecs
bash ~/.superspecs/setup.sh

Then, in any project you want to use SuperSpecs in, add the bootstrap files. The skills are already symlinked globally so your agents will find them automatically.

Option 2 — Per-project clone

Embed SuperSpecs directly inside a project. Useful when you want the framework versioned alongside the project.

cd your-project
git clone https://github.com/your-org/superspecs.git .superspecs
bash .superspecs/setup.sh

setup.sh symlinks skills both at project level (.claude/skills/, .agents/skills/, etc.) and globally (~/.claude/skills/, ~/.agents/skills/, etc.).

Option 3 — npm global install

npm install -g superspecs
superspecs install

superspecs install runs setup.sh from the package's own directory. Same result as Option 1.

Option 4 — npx (no install)

npx superspecs install

Downloads the package, runs setup.sh, and discards the download. Good for a one-off bootstrap. Skills will be symlinked from the npx cache, so re-running after cache eviction re-installs them.

What `setup.sh` Does

Running setup.sh from any install method does three things:

1. Project-level skill symlinks

Creates <skills-dir>/<skill-name>.md symlinks inside agent config dirs relative to where the script runs:

Directory	Agent
`.claude/skills/`	Claude Code
`.cursor/skills/`	Cursor
`.windsurf/skills/`	Windsurf
`.agents/skills/`	OpenCode / Aider

2. Global skill symlinks

Creates the same symlinks in your home directory so agents pick up skills across all projects:

Directory	Agent
`~/.claude/skills/`	Claude Code
`~/.agents/skills/`	OpenCode
`~/.codex/skills/`	Codex
`~/.gemini/skills/`	Gemini CLI
`~/.copilot/skills/`	GitHub Copilot CLI
`~/.windsurf/skills/`	Windsurf (if installed)
`~/.cursor/skills/`	Cursor (if installed)
`~/.kiro/skills/`	Kiro (if installed)

3. Project directory scaffold

Creates the superspec/ working directories if they don't already exist:

superspec/
├── specs/
├── phases/
├── archive/
└── wiki/
    ├── _index.md
    └── _manifest.json

Verifying the Install

After running setup.sh, confirm skills are in place:

ls ~/.claude/skills/
# plan-discuss.md  plan-spec.md  execute-pick-spec.md ...
 
ls ~/.agents/skills/
# same list

Then open your agent and say:

Tell me about your superspecs

A correctly installed agent will describe the four-phase lifecycle and the available slash commands.