Quickstart — Kitbash docs

Already have agent config files? If your repo already carries CLAUDE.md, .cursor/rules/, AGENTS.md and their kin, you don't have to author or install a skill to start — kitbash import reads the files you already have into one skill and shows you where the copies have drifted apart, ready for kitbash compile. See import.

kitbash import

1. Install the CLI

Kitbash is a zero-dependency CLI. The npm route needs Node 20 or newer; the Homebrew route brings its own.

# npm
npm install -g kitbash

# or Homebrew
brew install singhharsh1708/tap/kitbash

Check it landed:

kitbash --version

Full install, update, and uninstall instructions live on the installation page.

2. Set up a repo

From the root of any project:

kitbash init

That writes kitbash.toml (project config) and creates .kitbash/skills/, where installed skills live. Both belong in version control — your team gets the same skills the same way they get the same dependencies.

3. Install a skill

Skills come from a GitHub repo, a subfolder of one, or a local path:

kitbash install gh:singhharsh1708/kitbash/examples/skills/prereview

Before anything is written to disk, Kitbash shows you what the skill declares and asks for confirmation:

review: prereview@0.1.0 — Review the working diff against this team's real standards before it ships
  budget 1500 tok · standing 60 tok/session · lazy disclosure · mode skill
  permissions: tools [read, grep, bash:git diff *, bash:git log *] · network no · write no
install prereview@0.1.0? [y/N]

This is the point. Installing a skill means letting someone else's instructions run with your agent's permissions. Read the review block before you answer. In scripts and CI, pass --yes to skip the prompt — see trust & review.

Kitbash records a content hash in kitbash.lock so the skill you reviewed is the skill you keep getting.

4. Compile

kitbash compile

Kitbash detects which agents your repo is set up for and writes each one's native format:

✓ compiled 1 skill for 2 targets
→ .claude/skills/prereview/SKILL.md
→ .claude/commands/prereview.md
→ AGENTS.md §prereview
⚠ prereview → agentsmd: agentsmd is eager and cannot lazy-load;
  this skill costs ~560 tokens standing every session

That last warning is the part other tools don't give you. Kitbash compiles to the cheapest loading mode each target supports, so lazy targets (Claude Code, Cursor, Devin, the .agents/skills/ path) load a skill only when it's invoked. Targets with no deferred mode carry the whole body in context every single session — a standing tax measured at 14×–47× in the benchmark.

5. Inspect before you trust

Three read-only commands work on installed skills and on sources you haven't installed:

Command	Answers
`kitbash preview <source>`	What exactly does each agent receive, and what does it cost there?
`kitbash lint <source>`	Is the manifest valid, are refs dead, does the body smell like prompt injection?
`kitbash explain <source> <adapter>`	Why did this compilation degrade on that agent?

All three accept a remote source, so you can read a stranger's skill without installing it:

kitbash preview gh:singhharsh1708/kitbash/examples/skills/prereview

6. Check the repo's health

kitbash doctor

Reports which agents were detected, the total standing context cost of everything installed, whether every skill is pinned, and whether any file on disk has drifted from its hash in the lockfile.

Where to go next

Write your first skill — the manifest, the body, budgets, and templates.
CLI reference — every command, flag, and exit code.
Adapters & targets — all eleven targets and what each one supports.
Trust & review — org allowlists with [policy].