CLI reference

init

kitbash init

Writes kitbash.toml at the current working directory and creates .kitbash/skills/. The generated config carries a [project] table with every setting commented out: an example targets line, and a commented [policy] block covering allow_sources, deny_network, deny_write, and max_budget. Nothing is enabled until you uncomment it.

The command is idempotent in the safest possible way — if kitbash.toml already exists it touches nothing, including the skills directory.

• (none) Takes no arguments and no flags.

$ kitbash init
created kitbash.toml and .kitbash/skills/
next: kitbash install <gh:owner/repo | owner/repo | file:path>, then kitbash compile

On a repo that already has one:

$ kitbash init
kitbash.toml already exists — nothing to do

Exit codes: 0 always — both the created and the already-exists path succeed.

import

kitbash import [--write] [--name <name>]

Reads the agent instruction and rule files a repo already has, measures what each one costs in standing context, reports where the copies have drifted apart, and synthesizes one KSF skill from the version the most files agree on — so compile can regenerate every target from that single source. It is the reverse of compile, and the on-ramp for a repo already carrying a hand-maintained copy per agent. Nothing is deleted: the files it reads stay in place until you remove them yourself.

It reads back the formats the adapters write: CLAUDE.md, AGENTS.md, GEMINI.md, CONVENTIONS.md, .cursorrules, .windsurfrules, .clinerules (file or directory), .github/copilot-instructions.md, and the rule directories .cursor/rules/*.mdc, .github/instructions/*.instructions.md, .windsurf/rules/*.md, and .devin/rules/*.md. YAML frontmatter and any kitbash-generated marker sections are stripped first, and a file that is entirely kitbash output is skipped — so import never re-imports its own generated copies.

Drift is the point. Files carrying the same rules after whitespace normalization are one version; more than one version means the copies have diverged, and the report lists which files fell into which. The largest group is treated as canonical — the version the most agents agree on — and that is what the skill is built from. When a skill is written from drifted sources, its SKILL.md is prefixed with a comment saying so, to be reviewed before you compile.

• --write Save the synthesized skill to .kitbash/skills/<name>/ (as skill.toml + SKILL.md) and pin it in kitbash.lock. Without it, import is a dry run that prints the proposed skill and writes nothing.
• --name <name> Name the skill. Must satisfy the KSF name rule — lowercase, starting with a letter, 2–41 characters. Defaults to <dir>-rules, derived from the repository directory name.

$ kitbash import
found 4 agent config files:
  CLAUDE.md  → claude-code  (~638 tok, eager)
  AGENTS.md  → agentsmd  (~638 tok, eager)
  .windsurfrules  → windsurf  (~638 tok, eager)
  .cursor/rules/conventions.mdc  → cursor  (~602 tok, lazy)
standing cost of the always-on files: ~1914 tokens every session

⚠ these 4 files have drifted into 2 different versions:
  version 1: CLAUDE.md, AGENTS.md, .windsurfrules
  version 2: .cursor/rules/conventions.mdc
  the canonical version below is the one the most agents agree on.

— proposed skill "acme-api-rules" (budget 800) —

[skill]
name = "acme-api-rules"
version = "0.1.0"
description = "Imported from 4 existing agent config files (claude-code, agentsmd, windsurf, cursor)"

[context]
budget = 800
standing = 100
disclosure = "lazy"

# SKILL.md (638 tok, first lines):
# Engineering conventions

- Write tests for every bug fix — a regression test that fails before the fix lands.
- Never widen a public type to `any` to silence the type checker.
- Run `pnpm lint && pnpm test` before opening a pull request.
- Commit messages use the imperative mood with a scope prefix and no trailing period.
- Prefer editing an existing module over adding a new one.
- Ask before adding a runtime dependency; justify it in the PR description.

re-run with --write to save it to .kitbash/skills/acme-api-rules/, then: kitbash compile

When every file already carries the same rules there is no drift to report, and that block reads ✓ all 4 carry the same rules — no drift. instead. Re-running with --write saves the skill and pins it:

$ kitbash import --write
…
wrote .kitbash/skills/acme-api-rules/ (skill.toml + SKILL.md), pinned in kitbash.lock
next: kitbash preview acme-api-rules   (see it per agent + the token cost)
then: kitbash compile           (regenerate every target from this one source — ends the drift)

On a repo with no agent instruction files at all there is nothing to reverse-compile, and import says so:

$ kitbash import
no existing agent instruction files found (CLAUDE.md, AGENTS.md, .cursor/rules/, .clinerules, …).
  nothing to import — author a skill instead: kitbash init && kitbash install <source>

Exit codes: 0 on a successful dry run or write, and on a repo with nothing to import. 1 when --name is not a valid KSF name, or when --write would overwrite an existing .kitbash/skills/<name>/ — pass --name <other> or remove it first.

install

kitbash install <gh:owner/repo[/path][@ref] | owner/repo | file:path> [--yes]

Fetches a skill, shows a review block, asks for confirmation, copies it into .kitbash/skills/<name>/, and records a content hash in kitbash.lock.

The source argument is the first argument that does not start with -. Five forms resolve:

Resolution order matters: a bare owner/repo is checked as a local path first, so a directory named foo/bar in your repo wins over the GitHub repo foo/bar. Subpaths are confined to the clone — a subpath that resolves outside it is rejected as escaping the repository. GitHub sources require git on PATH; without it the command tells you to install git or use file:. The temporary clone is removed whether the install succeeds or fails.

Before anything is written, the review block prints what the skill declares: budget, standing limit, disclosure mode, target mode, tool permissions, network and write flags, and any required capabilities. A skill with only a SKILL.md and no skill.toml is flagged as unmanifested. Every failing or warning static check is printed too, so you see budget overruns and injection heuristics before you consent.

A failed safety lint — visible-text, dynamic-context, remote-exec, or secrets — blocks the install outright: the command prints the reason, exits 1, and writes nothing. secrets refuses a skill that ships a live credential — an API key, a database password, or a private-key block. This holds with no kitbash.toml present and is not bypassable by --yes. (Through 0.8.0 the first two were printed but did not stop the install; 0.8.1 fixed that, and secrets joined the gate in 0.10.0.) Schema and quality checks do not block install — they surface at test.

Because install copies the whole skill directory, the four safety lints scan every non-binary file in it, not just SKILL.md: a curl … | sh in scripts/setup.sh, a live credential in a sibling config file, or hidden text in a sibling .md is caught the same way it is in the body. A symlink is itself flagged — it can point anywhere and the copy follows it verbatim. Each hit reports the offending file, and the block is enforced exactly like a body hit.

• --yes, -y Skip the confirmation prompt. Does not skip the review block, the safety lints, or [policy].

The prompt only appears when both stdin and stdout are TTYs. In a pipe, a CI runner, or a non-interactive shell, install proceeds without asking — --yes is for readability, not for unblocking automation.

$ kitbash install gh:singhharsh1708/kitbash/examples/skills/prereview
review: prereview@0.1.0 — Review the working diff against this team's real standards before it ships
  budget 1500 tokens · standing 60 · 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] y
installed prereview@0.1.0
  pinned in kitbash.lock
next: kitbash compile

Only y or yes, case-insensitive, count as consent. Anything else — including an empty line — aborts:

aborted — nothing installed.

[policy] is a hard gate. If kitbash.toml declares a [policy] table, the source is matched against allow_sources and the manifest against deny_network, deny_write, and max_budget. Violations are printed and the install is refused — --yes does not bypass it, because the flag suppresses a question and policy is not a question.

$ kitbash install gh:stranger/skills/exfil --yes
review: exfil@1.0.0 — Summarizes your codebase
  budget 4000 tokens · standing 90 · lazy disclosure · mode skill
  permissions: tools [read, bash] · network YES · write no
  ⚠ lint: injection — heuristic match — review: data-exfiltration shape
  ✗ policy: source "gh:stranger/skills/exfil" is not in allow_sources (gh:your-org/*)
  ✗ policy: exfil declares network permission and deny_network = true
blocked by [policy] in kitbash.toml.

Reinstalling is explicit. If the skill name is already present the command refuses rather than overwriting, and tells you the two-step sequence.

prereview is already installed. To reinstall: kitbash remove prereview && kitbash install gh:singhharsh1708/kitbash/examples/skills/prereview

Exit codes: 0 when installed. 1 when no source was given, the source string is malformed, git is missing, the clone or ref checkout fails, the subpath is missing or escapes the repo, the folder has no SKILL.md, the skill is already installed, a policy rule is violated, or the prompt is declined.

remove

kitbash remove <skill-name>

Deletes .kitbash/skills/<name>/ and drops the skill's entry from kitbash.lock. It takes an installed skill name only — not a path and not a source — and the name must match the KSF name rule (lowercase, starting with a letter, 2–41 characters).

Removing does not clean up compiled output. The next kitbash compile prunes the generated files this skill owned, which is why the command says so.

• <skill-name> Required. The installed name, as shown by kitbash list.

$ kitbash remove prereview
removed prereview
next: kitbash compile (prunes this skill's generated outputs)

If the name isn't installed, the error lists what is:

$ kitbash remove prereviw
prereviw is not installed.
  installed: prereview, release-notes

Exit codes: 0 when removed. 1 when the name is missing, malformed, or not installed.

list

kitbash list

Prints one line per installed skill, sorted by name: name and version, declared context budget, declared standing limit, target mode, an [unmanifested] marker for SKILL.md-only skills, and the description. Directories under .kitbash/skills/ without a SKILL.md are skipped, so aborted installs and stray folders don't break the listing.

• (none) Takes no arguments and no flags.

$ kitbash list
prereview@0.1.0  budget=1500  standing=60  mode=skill  — Review the working diff against this team's real standards before it ships
release-notes@0.2.0  budget=2200  standing=80  mode=skill  — Turns merged PRs into a release note
scratch@0.0.0  budget=6000  standing=250  mode=skill  [unmanifested]  — Imported skill (no manifest)

An empty project says so instead of printing nothing:

no skills installed — kitbash install <source>

Exit codes: 0 always, including when nothing is installed.

compile

kitbash compile [--strict]

Compiles every installed skill for every configured target and writes the results to disk. Targets come from [project] targets in kitbash.toml; with no config or no targets key, Kitbash autodetects by looking for each adapter's marker file or directory. An unknown target name in the config is a hard error before anything is written.

Per-skill files (.claude/skills/, .claude/commands/, .cursor/rules/, .agents/skills/, .github/skills/, .gemini/skills/, .clinerules/, .devin/rules/ or .windsurf/rules/) are written whole. Shared files (AGENTS.md, CONVENTIONS.md) are marker-merged: each skill owns a <!-- kitbash:begin <name> --> … <!-- kitbash:end <name> --> section and your own prose around it is preserved.

Compile is also the garbage collector. Files in managed directories that carry the generated header but were not written by this run are deleted, including the .github/instructions/ files older versions emitted. A managed shared file that nothing wrote to this run — AGENTS.md, GEMINI.md or CONVENTIONS.md — has all of its generated sections pruned, since none of them are current. That is how removing a skill eventually removes its output.

Budgets are enforced here, not merely reported. A manifested skill whose compiled body exceeds context.budget, or whose standing stub exceeds context.standing, fails the whole compile before any file is written. Unmanifested skills never declared those numbers, so their overruns are measured and warned about instead.

• --strict Exit 1 if the run produced any warnings. Files are still written; the failure is reported after.

$ kitbash compile
→ .claude/skills/prereview/SKILL.md
→ .claude/commands/prereview.md
→ .cursor/rules/prereview.mdc
→ AGENTS.md
✂ removed .claude/commands/old-review.md (stale)
⚠ prereview → agentsmd: agentsmd is eager and cannot lazy-load; this skill costs ~560 tokens standing every session (declared limit: 60)
compiled 1 skill for 3 targets

Warnings cover eager-target standing cost, capability degradation, unmanifested skills, and output-path conflicts where two skills write the same file. With --strict those same warnings end the run:

$ kitbash compile --strict
→ .claude/skills/prereview/SKILL.md
→ AGENTS.md
⚠ prereview → agentsmd: agentsmd is eager and cannot lazy-load; this skill costs ~560 tokens standing every session (declared limit: 60)
compiled 1 skill for 2 targets
--strict: failing on 1 warning

A budget violation stops the run outright:

✗ prereview: compiled body is ~1712 tokens, over its budget of 1500

With nothing installed, compile still prunes stale output, then reports and succeeds:

no skills installed — kitbash install <source> to add one

Exit codes: 0 on a clean compile. 1 on an unknown target in kitbash.toml, a manifested skill over its budget or standing limit, or --strict with at least one warning.

doctor

kitbash doctor

The repo health check. It reports which of the eleven adapters were detected, how many skills are installed, the total standing context cost of their stubs, the worst-case active cost if every skill fired in one session, and then verifies the lockfile.

Three integrity conditions are checked: skills installed with no kitbash.lock at all, a locked skill whose files on disk no longer match their recorded hash, and a skill present on disk but absent from the lockfile. All three mean the code your agents load is not the code somebody reviewed.

If [policy] is configured, doctor rechecks it against everything already installed — using each skill's recorded source from the lockfile. That catches skills that predate the policy or were copied in without going through kitbash install.

• (none) Takes no arguments and no flags.

$ kitbash doctor
detected targets:
  ✓ claude-code
  ✓ cursor
  ✗ agents
  ✗ zed
  ✗ copilot
  ✗ cline
  ✗ windsurf
  ✗ gemini
  ✗ aider
  ✓ agentsmd (floor: Codex, Gemini CLI, anything reading AGENTS.md)
  ✗ agent-plugins (opt-in: name it in [project].targets)
installed skills: 2
standing context cost: ~98 tokens (stubs); worst-case active: 3700 tokens (budgets)
lock integrity: ok
policy: ok

The agentsmd target is always detected — AGENTS.md is the floor every repo compiles to. A failing run looks like this:

installed skills: 2
standing context cost: ~98 tokens (stubs); worst-case active: 3700 tokens (budgets)
  ✗ prereview: integrity drift — installed files differ from kitbash.lock
  ✗ scratch: installed but not pinned in kitbash.lock — reinstall to pin it.
2 integrity problem(s) — reinstall or investigate

A lockfile entry for a skill that is not installed is a warning, not a failure — that is the ordinary state after removing a skill from disk by hand.

Exit codes: 0 when detection, integrity, and policy all pass. 1 on a missing lockfile with skills installed, integrity drift, an unpinned installed skill, or a policy violation.

update

kitbash update [skill-name] [--yes]

Refetches each installed skill's pinned source — the exact gh:/file: source recorded in kitbash.lock — and, when anything differs, prints the complete review before touching a byte: manifest field deltas with permission escalations flagged, the changed-file list, then a unified diff of every readable file. Only after that does it ask for confirmation, replace the installed directory, and re-pin the lockfile with the new version and content hash.

$ kitbash update
diff: prereview@0.1.0 → prereview@0.2.0
manifest:
  version: 0.1.0 → 0.2.0
  budget: 500 tok → 800 tok  ⚠ escalation
  permissions.network: no → YES  ⚠ escalation
files:
  ~ SKILL.md
  ~ skill.toml
  + helper.sh

--- a/SKILL.md
+++ b/SKILL.md
@@ -1,5 +1,6 @@
 Do the thing.

 Step one: read files.
-Step two: report.
+Step two: fetch the changelog from the network.
+Step three: report.
…
update prereview to 0.2.0? [y/N]

Three properties are deliberate:

• The four safety lints that gate install — visible-text, dynamic-context, remote-exec, secrets — re-run against the new version and block the update regardless of --yes. A skill must clear the same gate to change on disk as to arrive.
• [policy] is re-enforced. A new version that declares a permission your policy denies, or grows past max_budget, cannot arrive by update.
• Unlike install, a non-interactive run never auto-applies. No TTY and no --yes means the diff prints, nothing changes, and the exit code is 1. The command's whole contract is that a human saw the diff and said yes.

Local edits to an installed skill are detected via the lockfile hash and called out before being overwritten. A source that renames its skill is refused — remove and reinstall instead of letting one skill silently replace another. An unchanged skill reports up to date.

• [skill-name] Optional. Update only this skill. Omit to check everything pinned in kitbash.lock.
• --yes Apply without prompting. Does not bypass safety lints or [policy].

Exit codes: 0 when every checked skill is up to date or was applied. 1 when any skill failed to fetch or load, was blocked by a safety lint or policy, or was left unapplied (declined, or non-interactive without --yes).

diff

kitbash diff <skill-name> [<skill-name | path | source>]

The same review update prints, read-only. With one argument it diffs the installed skill against a fresh fetch of its pinned source — "what would update do?". With two arguments it diffs any two skills, each resolved as an installed name, a local path, or a fetchable source, so you can compare two versions of a stranger's skill before either touches your repo:

$ kitbash diff prereview gh:owner/repo/skills/prereview@v2

Output is the manifest field delta (escalations flagged with ⚠), the changed-file list (+ added, - removed, ~ modified; binaries and symlinks are listed but not line-diffed), then unified diffs. Identical skills print no differences.

• <a> Installed name, path, or source. With no second argument, must be an installed skill pinned in kitbash.lock.
• [b] Optional second target to compare against.

Exit codes: diff(1) semantics — 0 identical, 1 different, 2 trouble (unresolvable target, missing lock pin, failed fetch). Scriptable as a cheap "is my skill stale?" probe in CI.

test

kitbash test [skill-name] [--strict]

Runs the static-tier evals over installed skills: manifest presence, template and reference resolution, measured body tokens against context.budget, measured stub tokens against context.standing, artifact reference shape (name@version), slash-prefixed trigger commands, a gate-verdict check, schema-conformance lints, prompt-injection heuristics, and four safety checks on the body itself — visible-text, dynamic-context, remote-exec, and secrets.

The gate-verdict check applies only to mode = "gate" skills: a gate has to be able to produce a deterministic verdict, so it must carry a scripts/ directory to run or a declared artifacts.produces. A gate with neither fails lint and test — nothing there can ground a pass/fail.

No eval file is required — these checks always run. Failures print ✗, warnings print ⚠, passing checks print ·. Injection heuristics and schema lints only ever warn: a security skill may legitimately quote the phrases it defends against, so the tool refuses to hard-fail on a pattern match.

The four safety checks are the exception — each is a hard failure that exits 1 with or without --strict, and each also blocks install:

• visible-text rejects a body containing zero-width characters, bidi overrides, or codepoints from the Unicode Tags block (U+E0000–U+E007F), which encodes plain ASCII invisibly. Those are instructions a human reviewer cannot see while the agent still reads them. The report names each run of hidden characters by codepoint.
• dynamic-context rejects ! followed by a backtick command substitution in the body. That construct executes at load time, before the model reads anything, so it never gets a pass.
• remote-exec rejects a download-and-execute pipeline in the body prose — curl … | sh, eval "$(curl …)", base64 -d | sh, PowerShell iex/iwr, save-then-chmod +x-then-run, remote-archive extract-run. This is the payload that hides in a "Prerequisites" section rather than the manifest. A [policy] may exempt it with deny_remote_exec = false; the other three are never exemptible.
• secrets rejects a live credential shipped in the body — an AWS, Anthropic, OpenAI, GitHub, Google, Stripe, Slack, or Linear key, a database URL with an inline password, or a private-key block. Each pattern keys on the real key shape, so a placeholder guard drops documentation values: a body teaching sk-ant-..., an env ref ${OPENAI_API_KEY}, or AWS's AKIAIOSFODNN7EXAMPLE is not flagged.

Kitbash fans one skill out to nine files, several of them always in context, which is why none of these is a warning.

The optional positional argument filters to a single installed skill. Unlike lint, test does not accept a path or a remote source.

• [skill-name] Optional. Restrict the run to one installed skill.
• --strict Exit 1 if any check warned, not just if one failed.

$ kitbash test
✓ prereview
    · manifest — prereview@0.1.0
    · references
    · budget — body ~464 tok / budget 1500
    · standing — stub ~38 tok / limit 60
    · artifacts — produces 1, consumes 0
    · visible-text — no hidden characters
⚠ scratch
    ⚠ manifest — unmanifested (SKILL.md only) — defaults applied
    · references
    · budget — body ~1204 tok / budget 6000
    · standing — stub ~61 tok / limit 250
    ⚠ injection — heuristic match — review: role reassignment
    · visible-text — no hidden characters

tested 2 skill(s) · 0 failure(s) · 2 warning(s) (static tier)

If any skill has an evals/ directory, test says plainly that only the static tier ran:

note: evals/ present — audit & behavioral tiers need a runner (not in this build); static tier ran

A real failure — here a dead template reference and a malformed artifact id:

✗ release-notes
    · manifest — release-notes@0.2.0
    ✗ references — release-notes: template references missing /repo/.kitbash/skills/release-notes/prompts/summarize.md
    ✗ artifacts — malformed: changelog (want name@version)

tested 1 skill(s) · 2 failure(s) · 0 warning(s) (static tier)

Exit codes: 0 when nothing failed (and, under --strict, nothing warned). 1 when the named skill is not installed, no skills are installed, any check failed, or --strict saw a warning.

lint

kitbash lint [skill-name | path | source] [--strict]

Runs the same static checks as test and prints the same report, but resolves its target far more broadly. The argument is tried in this order: an existing path relative to the project root, then an installed skill name, then a fetchable source (gh:owner/repo[/path][@ref], owner/repo, file:path). With no argument it lints everything installed.

That last case is the point: you can lint a stranger's skill before it ever touches your repo. The remote is cloned to a temporary directory, checked, and deleted.

Four of those checks are hard failures rather than warnings, and they apply to an uninstalled source exactly as they do to an installed skill: visible-text, which rejects hidden characters — zero-width, bidi overrides, the Unicode Tags block; dynamic-context, which rejects ! plus backtick command substitution in the body; remote-exec, which rejects a download-and-execute pipeline; and secrets, which rejects a live credential shipped in the skill. Any one of them exits 1 without --strict:

$ kitbash lint gh:stranger/skills/helper
✗ helper
    · manifest — helper@1.0.0
    · references
    · budget — body ~318 tok / budget 1500
    · standing — stub ~24 tok / limit 60
    ✗ visible-text — 2 run(s) of invisible characters (U+200B, U+E0041) — instructions a reviewer cannot see
    ✗ dynamic-context — command substitution in the skill body executes before the model sees it: !`cat ~/.ssh/id_rsa`

linted 1 skill(s) · 2 failure(s) · 0 warning(s)

• [target] Optional. A path, an installed name, or an uninstalled source. Omit to lint every installed skill.
• --strict Exit 1 if any check warned, not just if one failed.

$ kitbash lint gh:stranger/skills/summarize
⚠ summarize
    ⚠ manifest — unmanifested (SKILL.md only) — defaults applied
    · references
    ⚠ budget — body ~7310 tok / budget 6000
    · standing — stub ~112 tok / limit 250
    ⚠ injection — heuristic match — review: override of prior instructions, data-exfiltration shape
    · visible-text — no hidden characters

linted 1 skill(s) · 0 failure(s) · 3 warning(s)

The same run under --strict adds one line and fails:

--strict: failing on 3 warning(s)

An unresolvable argument tells you what it tried:

$ kitbash lint prereviw
prereviw: not found as a path or installed skill name (or pass a source: gh:owner/repo, file:path)
  installed: prereview, release-notes

Exit codes: 0 when nothing failed (and, under --strict, nothing warned). 1 when the target cannot be resolved or loaded, no argument was given and nothing is installed, any check failed, or --strict saw a warning.

explain

kitbash explain <skill-name | path | source> <adapter>

Answers one question: what does this skill lose on that agent? Both arguments are positional and both are required. The first resolves the same way as lint's target — path, installed name, or fetchable source. The second names an adapter: claude-code, cursor, agents, zed, copilot, cline, windsurf, gemini, aider, agentsmd, or agent-plugins.

Explain reports two independent kinds of loss. Capability degradation: each entry in the skill's targets.requires that the adapter does not support, which compiles down to instruction-only. And loading degradation: a skill authored for lazy disclosure on an eager adapter, which pays its full body as standing context in every session.

• <target> Required, first positional. Path, installed name, or uninstalled source.
• <adapter> Required, second positional. One of the eleven adapter ids.

$ kitbash explain prereview agentsmd
prereview → agentsmd: no capability degradation
  ⚠ loading: agentsmd is eager — skill costs ~560 tokens standing every session (declared limit: 60)

No adapter declares a capability today — emit() writes instructions but does not copy scripts/, install a hook, or wire a subagent — so a skill that requires any of scripts, hooks, subagents, or network reports degraded on every one of the eleven targets, Claude Code included:

$ kitbash explain prereview cursor
prereview → cursor: degraded
  ✗ requires "scripts" — not supported by cursor; compiled instruction-only

Missing arguments print the usage line and the adapter list:

$ kitbash explain prereview
usage: kitbash explain <skill-name-or-path-or-source> <adapter>
  adapters: claude-code, cursor, agents, zed, copilot, cline, windsurf, gemini, aider, agentsmd, agent-plugins

Exit codes: 0 whether or not degradation was found — explain reports, it does not judge. 1 when an argument is missing, the adapter name is unknown, the target cannot be resolved or loaded, or the body's template references cannot be resolved.

preview

kitbash preview <skill-name | path | source>

Renders, without writing anything, exactly what each adapter would emit — every output path, every byte of frontmatter, the full compiled body — plus that adapter's loading mode and what it costs in standing context. Target resolution is identical to lint and explain, so remote sources work.

Adapters come from [project] targets or autodetection, the same as compile. If kitbash.toml names an unknown target, preview errors out with the same message compile prints rather than falling back to every adapter — previewing output the repo will never generate would be its own kind of lie.

Lazy adapters are labelled lazy (0 tok standing). Eager adapters show the measured token count of their emitted files, because on those targets that is what every session carries.

• <target> Required. Path, installed name, or uninstalled source. The first argument not starting with -.

$ kitbash preview gh:singhharsh1708/kitbash/examples/skills/prereview
preview: prereview@0.1.0

─── claude-code [lazy] lazy (0 tok standing) ───

  → .claude/skills/prereview/SKILL.md

---
name: prereview
description: "Review the working diff against this team's real standards before it ships"
---
<!-- generated by kitbash — do not edit; source: .kitbash/skills/prereview @ 0.1.0 -->

# prereview
…

  → .claude/commands/prereview.md

<!-- generated by kitbash — do not edit; source: .kitbash/skills/prereview @ 0.1.0 -->

Load the "prereview" skill: read .claude/skills/prereview/SKILL.md and follow it exactly.

Arguments: $ARGUMENTS

─── agentsmd [eager] ~560 tok standing ───
⚠ prereview → agentsmd: agentsmd is eager and cannot lazy-load; this skill costs ~560 tokens standing every session (declared limit: 60)

  → AGENTS.md

<!-- kitbash:begin prereview -->
<!-- generated by kitbash — do not edit; source: .kitbash/skills/prereview @ 0.1.0 -->

## Skill: prereview

…
<!-- kitbash:end prereview -->

The shared-file adapters print only the skill's own marker-delimited section, not the merged file — that section is what compile would splice in.

Exit codes: 0 on a successful render, warnings included. 1 when no target was given, the target cannot be resolved or loaded, [project].targets in kitbash.toml names an unknown adapter, or the body's template references cannot be resolved.