Skip to main content

FOR EVERYONE — A QUICK REFERENCE

Commands & scripts

This is the lookup page. Every claude-kit command in one place, with what it does and when you'd use it. Day to day you'll only need a few — but when you want the full picture, it's all here.

You type the slash commands inside Claude Code. The scripts are the engine room underneath — you rarely run them by hand, but it's good to know they exist.

Slash commands​

These are the things you type. Start with /kit-init; the rest you'll reach for as you go.

CommandWhat it doesReach for it when
/kit-initSets up a tailored .claude/ for your project from a role profile — agents, skills, rules, scripts, config.You're starting in a new project. Run it once.
/kit-customizeAdd, edit, or delete agents; wire skills and tools onto them; lint them; build and save a custom profile.You want to shape who's on your team. (It activates on its own when you ask to create or edit an agent.)
/kit-annotateClick any part of your running React app and leave a note; Claude reads it and fixes the code.You're reviewing a React app and want to point instead of describe.
/kit-updateShows a plain-language changelog and merges in what's new — without touching your customizations.You see an "update available" notice.
/kit-docsOpens the kit's own guides inside Claude Code.You want to read the docs without leaving your editor.
/kit-contributePackages an agent you built into a reusable template and opens a pull request upstream.You made something good and want to share it.

Useful flags​

A few commands take options. The ones worth knowing:

CommandFlagWhat it does
/kit-init--dry-runPreviews the whole setup and writes nothing. A safe first look.
/kit-annotatesetup · watch · review · statusPicks the mode. watch is hands-free — Claude picks up notes as you add them.
/kit-update(always previews)Shows exactly what will be added or merged before anything is written.
# A typical first session in a new project
/kit-init --dry-run    # look first
/kit-init              # then set it up for real

# Review a React app by pointing at it
/kit-annotate watch

Scripts behind the scenes​

The slash commands lean on a small set of shell scripts inside your project's .claude/ and scripts/ folders. You almost never call these yourself — Claude runs them for you — but here's what each one is responsible for.

ScriptResponsible for
init.shScaffolds your .claude/ from a profile. Also runs the safe merge-upgrade.
annotate-setup.shWires the visual annotation toolbar into a React app.
kit-version-check.shQuietly checks whether your project is behind the installed plugin.
lib/react-detect.shFigures out whether you have a React app and which framework.
lib/kit-config.shReads your project's settings so the other scripts know your setup.
setup-labels.shCreates the issue labels (kind, priority, role) on your GitHub repo.
setup-milestones.shCreates your project's milestones on the repo.
task-sync.shPrints a read-only snapshot of your task board, grouped by role.
note

Labels, milestones, and the board snapshot use the GitHub CLI (gh). If you didn't connect GitHub at setup, those scripts simply sit idle — nothing breaks.

How it works under the hood

  • init.sh — the scaffolder. scripts/init.sh --profile software --name "My App" substitutes {{VARS}} and resolves <!-- IF:FLAG --> blocks from a role profile into a fresh .claude/. Flags include --profile <software|content|research|minimal>, --target <dir>, --name, --slug, --repo, --memory <on|off>, --speckit <on|off>, --prepush "<command>", and --lang. Two important modes: --dry-run prints the plan and writes nothing, and --upgrade merges new kit features into an existing .claude/ while preserving your edits (this is what /kit-update runs). Requires jq and perl.

  • annotate-setup.sh — scripts/annotate-setup.sh [--target DIR] [--framework next|vite|react-router] [--dry-run]. Installs the third-party agentation dev dependency, registers the agentation-mcp MCP server for Claude, writes the react-annotate rule, and records the choice in kit.config.json. It prints the dev-only provider snippet for your app entry rather than editing source blindly — /kit-annotate applies that edit with your confirmation. Exits cleanly if no React app is detected.

  • kit-version-check.sh — kit-version-check.sh [--target DIR] [--plugin-root DIR] [--quiet]. Compares the project's recorded kitVersion (from kit.config.json) against the installed plugin's plugin.json version using a semver-aware sort -V. Prints a one-line "update available" notice only when the project is strictly behind; a safe no-op otherwise. The SessionStart hook and /kit-update both call it.

  • lib/react-detect.sh — source it, then call react_detect [dir]. Sets REACT_* variables, detecting framework in specificity order: Next.js → React Router v7 → Vite → generic React. (A flat "is Vite present?" check is unreliable, since Next/RR apps often carry Vite for tests.) Also infers the package manager from the lockfile. Safe to source — never aborts the caller.

  • lib/kit-config.sh — source scripts/lib/kit-config.sh && load_kit_config loads .claude/kit.config.json into KIT_* environment variables (project name, profile, repo, memory wing, plan format, and more). Per-folder .claudekit/config.json files are deep-merged over the project config, nearest-wins — the same cascade as .editorconfig.

  • setup-labels.sh — idempotent. Reads repo and roles from config, then creates the kind:, priority:, and role: label families on the repo via gh label create --force. Re-runs report (exists) rather than erroring.

  • setup-milestones.sh — idempotent. Reads the project's milestones from config and creates any that don't yet exist on the repo via gh api.

  • task-sync.sh — read-only board status. ./scripts/task-sync.sh [--role <Name>] [--milestone <label>] lists open issues grouped by role as Markdown tables, flagging blocked items. Pure gh + jq, bash 3.2 compatible.

See also​