Documentation

What Kitbash is

Every coding assistant invented its own extension format: .claude/skills/, .cursor/rules/*.mdc, .github/skills/, .clinerules, .windsurfrules, .gemini/skills/, CONVENTIONS.md, AGENTS.md, and the vendor-neutral .agents/skills/ path. A skill written for one of them does nothing for the rest of the team. Kitbash defines a single format — KSF, a directory with a skill.toml manifest and a SKILL.md body — and compiles it into all nine of those native outputs. There is no runtime: your agent reads its own format and never knows Kitbash was involved.

The compiler is the part that matters. Because a skill declares its context budget and its disclosure mode, kitbash compile can measure the skill's standing token cost — what it adds to your context window on every single request — for each target, before you ever ship it. Kitbash compiles to the cheapest loading mode each target actually supports: Claude Code, Cursor, Copilot, Devin, Gemini CLI and the .agents/skills/ path load a skill only when it is invoked. Cline, Aider and the AGENTS.md floor have no deferred mode and carry the whole body every session. In the benchmark the same skill costs roughly 40 standing tokens on a lazy target and roughly 540 on an eager one: a 13× per-session tax that a team running four agents pays four times over. A converter would translate the format and stop there.

The KSF core is stabilized through RFC 0002: the manifest fields are frozen and evolve additive-only within the major version, so skills and third-party adapters can be written against a contract that will not shift. The ecosystem around the spec — more adapters, the index, first-party skills — is still early. Read current status before you plan around it.

Documentation map

New here? Install the CLI, then run through the quickstart — it is about two minutes end to end.

How the pieces fit

A skill is a directory. The manifest declares the contract; the Markdown body is the instructions the agent will read.

prereview/
  skill.toml        # budget, permissions, triggers, artifacts
  SKILL.md          # the instructions
  scripts/          # optional deterministic helpers
  evals/            # tests — yes, tests for a skill

The manifest is roughly fifteen lines of TOML, and every table in it is read by the tool — at install review, at compile, or both:

[skill]
name = "prereview"
version = "0.1.0"
description = "Review the working diff against this team's real standards before it ships"

[triggers]
commands = ["/prereview"]   # compiled to native slash commands where supported

[context]
budget = 1500                # hard cap on compiled size
standing = 60                # what it may cost every session
disclosure = "lazy"         # load on invocation, not on every request

[permissions]
tools = ["read", "grep", "bash:git diff *", "bash:git log *"]
network = false
write = false

kitbash compile reads every installed skill, detects which assistants the repo is set up for, and writes each one's native format:

kitbash compile

✓ compiled 1 skill → 3 targets
→ .claude/skills/prereview/SKILL.md
→ .cursor/rules/prereview.mdc
→ AGENTS.md §prereview
⚠ prereview → agentsmd: agentsmd is eager and cannot lazy-load;
  this skill costs ~517 tokens standing every session

Per-file targets get a file of their own. Shared-file targets — AGENTS.md and Aider's CONVENTIONS.md — get a marker-delimited section merged into whatever is already there, so hand-written content survives a recompile and removed skills get pruned on the next one. AGENTS.md is the floor: it is always emitted, because everything that reads it (Codex among them) then gets the skill for free.

Current status

The spec is stable; the tool is young. This is what the CLI does today versus what is still on the roadmap.

Working today

• init, install, remove, list, compile, doctor — the core loop, end-to-end tested in CI.
• lint, preview, explain, test — read-only inspection. The first three also accept an uninstalled source, so you can read a stranger's skill before it touches your disk.
• Sources: gh:owner/repo[/path][@ref], bare owner/repo, and file:path.
• Nine adapters: claude-code, cursor, agents, copilot, cline, windsurf, gemini, aider, and the agentsmd floor.
• Budget and standing enforcement at compile time, degradation warnings, and --strict.
• kitbash.lock with directory content hashes, drift detection in doctor, and stale-output pruning after remove.
• Pre-install review with --yes for scripts, and the [policy] allowlist as a hard gate that --yes does not bypass.
• SKILL.md-only interop: a plain skills.sh / Claude Skills folder installs directly and is flagged unmanifested.
• Declared trigger commands compiled to native slash commands where the host supports them.

Not built yet

These commands exist in the surface — kitbash help lists them — but running one prints where it lands and exits 2:

$ kitbash update
kitbash update: not implemented yet (lands in v0.2 — see docs/roadmap.md)

Also outstanding: skill-to-skill [dependencies] with a pinned transitive closure, behavioral eval tiers beyond the static one, permissions compiled down to Claude Code permission rules, and the community index. On skills, prereview is the one first-party skill that ships today; excavate, plan, verify, triage, migrate, and onboard are specified but not released — the catalog marks which is which.