kitbash
/kitbash
Set up Claude Code subagents for this project from Kitbash's catalog of tested parts. Writes the project map in .kitbash/, validates it, runs each agent's evals (billed, only on the user's go-ahead) and deploys only the agents whose evals passed. Use when the user wants project subagents, mentions Kitbash or a .kitbash/ folder, or asks to check, evaluate or deploy agents.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Set up Claude Code subagents for this project from Kitbash's catalog of tested parts. Writes the project map in .kitbash/, validates it, runs each agent's evals (billed, only on the user's go-ahead) and deploys only the agents whose evals passed. Use when the user wants project subagents, mentions Kitbash or a .kitbash/ folder, or asks to check, evaluate or deploy agents.
Triggers from the description
Arguments
/kitbash [what you want, e.g. set up agents for this repo]
Original author description
Set up Claude Code subagents for this project from Kitbash's catalog of tested parts. Writes the project map in .kitbash/, validates it, runs each agent's evals (billed, only on the user's go-ahead) and deploys only the agents whose evals passed. Use when the user wants project subagents, mentions Kitbash or a .kitbash/ folder, or asks to check, evaluate or deploy agents.
How it works
- Commands
- Rules
- Workflow
- Project agents
SKILL.md preview
---
name: kitbash
description: Set up Claude Code subagents for this project from Kitbash's catalog of tested parts. Writes the project map in .kitbash/, validates it, runs each agent's evals (billed, only on the user's go-ahead) and deploys only the agents whose evals passed. Use when the user wants project subagents, mentions Kitbash or a .kitbash/ folder, or asks to check, evaluate or deploy agents.
argument-hint: "[what you want, e.g. set up agents for this repo]"
allowed-tools:
- Read(/${CLAUDE_PLUGIN_ROOT}/**)
- Bash(python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/validate.py")
- Bash(python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/validate.py" *)
- Bash(python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/run_evals.py" --dry-run *)
- Bash(python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/run_playbook.py" --dry-run *)
- Bash(python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/deploy.py" --dry-run)
- Bash(python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/registry.py" search *)
---
# Kitbash
Kitbash builds a project's subagents from a catalog of parts (traits, skills, tools, agents), checks the result
with a validator, proves each agent with evals, and writes `.claude/agents/` only for agents that passed.
The user asked: $ARGUMENTS
The catalog ships with this plugin at `${CLAUDE_PLUGIN_ROOT}/catalog/`. Treat it as read-only: it is replaced on
every plugin update. Everything that belongs to the project goes in its `.kitbash/` folder:
```
.kitbash/
project-map.yaml aspects of the project, the tools bound to each, the agents routed to each
playbooks/ optional multi-agent sequences
catalog/ optional project agents, traits, skills, tools, hooks, fixtures (same layout as the catalog)
evals.lock.json eval results, written by run_evals.py; deploy.py reads it
work/ eval workspaces, ignored by git
```
## Commands
Run every command from the project, so the scripts find `.kitbash/`. They need Python 3.9 or later.
Free (no model call):
```sh
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/validate.py" # the project's map and catalog
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/run_evals.py" --dry-run AGENT --aspect ASPECT # composed prompt, no run
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/run_playbook.py" --dry-run .kitbash/playbooks/NAME.yaml
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/deploy.py" --dry-run # files it would write, and refusals
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/deploy.py" # write .claude/agents/
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/registry.py" search "TERMS" # imported skills and servers
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/registry.py" sync # builds that index; network, a few minutes
```
The first validation fetches the map's pack from GitHub into `~/.cache/kitbash/`, so it needs the network once.
Billed to the user's Claude account, each only after the user says yes to that run:
```sh
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/run_evals.py" AGENT --aspect ASPECT # one agent, one aspect
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/run_playbook.py" .kitbash/playbooks/NAME.yaml
python3 "${CLAUDE_PLUGIN_ROOT}/catalog/scripts/make_agent.py" "REQUEST" --aspect ASPECT # designs a project agent
```
Keep `--dry-run` directly after the script name, as written above.
## Rules
- **Ask before every billed run.** Name the agent, the aspect and how many evals it has, and give the ceiling:
each eval may spend up to `--budget` (default 1.00 USD) on the agent plus 0.20 USD on the judge. Say which local
tools the evals need (see below). Wait for a clear yes. `make_agent.py` bills even with `--dry-run`.
- **Say once how evals run.** Each eval runs `claude -p` on the user's account in a throwaway copy of the fixtures
under `.kitbash/work/`, with permissions bypassed inside that copy only.
- **Never get around the deploy gate.** Do not edit `.kitbash/evals.lock.json`, and do not change an agent's evals
or pass conditions to make them pass. If the user wants to deploy without an agent that has not passed, remove
it from the map with their agreement and say so.
- **Never edit files under `${CLAUDE_PLUGIN_ROOT}`.** To change a catalog agent for this project, copy it into
`.kitbash/catalog/` under a new name.
- **Report outcomes as they are.** Quote validator errors and failed evals' reasons; do not summarise a failure as
a pass.
- `release.py` is the maintainer's release flow for another repository. Do not offer it.
## Workflow
### 1. Look
Find the project root (`git rev-parse --show-toplevel`, else the current directory). If
`.kitbash/project-map.yaml` exists, run the validator and the deploy dry run and report where things stand: which
agents are routed, which have a current pass, and what is refused and why. Then do what the user asked.
### 2. Write the map
Only when there is none, or the user asks to change it.
1. Inventory the project: top-level folders, languages, build and test files, design or hardware files, docs.
A project often spans several repositories; you will ask whether there are others in step 3.
2. Read the catalog: every file in `${CLAUDE_PLUGIN_ROOT}/catalog/agents/` and `${CLAUDE_PLUGIN_ROOT}/catalog/tools/`,
and the one-line description at the top of each file in `${CLAUDE_PLUGIN_ROOT}/catalog/packs/`. Write the
plugin path out in full in each command: a shell variable can't be checked in advance, so it needs approval.
An agent lists the capabilities it `requires`; a tool lists the ones it `provides`. Some catalog agents were
written for one project's stack (their description says which); route them only where that stack matches.
3. Propose aspects: one per part of the project that needs different tools or agents, each with path globs
relative to the project root, the tools whose capabilities its agents require, and the agents. Then ask, in a
single AskUserQuestion call: which pack to attach (one, or none; each pack's base is composed before every
agent in the map), whether the project spans other repositories, and whether the proposed aspects are right.
Ask with the tool, not in a reply: this skill's command permissions last only for the turn it was invoked in,
and the answers to the tool arrive within that turn. Write nothing before the answers. If the tool is not
available, ask in your reply and say that the validator will then need approval.
4. Write `.kitbash/project-map.yaml`. Leave out `catalog:`: the map then uses this plugin's catalog.
```yaml
project: acme
pack: superpowers # optional, at most one
aspects:
api:
paths: ["services/api/**"]
tools: [python-toolchain] # must provide every capability its agents require
agents: [security-reviewer]
firmware:
paths: ["firmware/**"]
tools: [stm32-toolchain]
agents: [firmware-engineer]
preferred_llm: claude-opus-5-5 # optional; must be in each routed agent's llms
shared_tools: [github] # optional, bound to every aspect
```
An aspect may also drop part of the pack base for its agents:
`pack_exclude: {skills: [NAME], reason: "..."}`. `${CLAUDE_PLUGIN_ROOT}/catalog/README.md` has every field and
validator rule, and `${CLAUDE_PLUGIN_ROOT}/examples/smart-thermostat/` is a complete example with playbooks.
### 3. Validate
Run the validator. It must end with `0 error(s)`. Three warnings, that the gstack, gsd and super-board packs list
no base, are expected. So is "registry not synced" until `registry.py sync` has run; offer it only if the user wants
imported skills or servers. Fix each error in the project's files, explaining the rule it broke.
### 4. Evals
For each routed agent, run its dry run first, then check that the tools its aspect binds are installed on this
machine (for example `kicad-cli`, `xcodebuild`, the STM32 toolchain, or the Pen or FreeCAD desktop app for MCP
tools). `${CLAUDE_PLUGIN_ROOT}/catalog/README.md` lists what each fixture set needs. Paths to these tools can be
set with environment variables such as `KICAD_CLI`, `ANDROID_HOME`, `JAVA_HOME` or `DEVELOPER_DIR`. Then ask, and
run one agent at a time. Each run records its results in `.kitbash/evals.lock.json`. On a failure, quote the
judge's reason and let the user decide what to change.
### 5. Deploy
Run the deploy dry run. While any routed agent has no record, a failed eval, or has changed since its evals ran,
it lists them with the command to run, and the deploy itself is refused. When it is clean, run the deploy, list
the files it wrote, and tell the user to commit `.kitbash/` (its `work/` folder is ignored) and the written
`.claude/` files. The agents are available in new Claude Code sessions.
## Project agents
To add an agent the catalog does not have, write it under `.kitbash/catalog/` in the catalog's layout
(`agents/NAME.yaml`, `skills/NAME/SKILL.md`, `fixtures/NAME/...`), using a catalog agent as the model. Its name
must not match a catalog name. It may use catalog traits, skills, tools and hooks by name. Its evals reference
fixtures by `fixtures/...` paths that exist in either catalog. Or, with the user's go-ahead, `make_agent.py`
designs one and writes it there. Validate, then run its evals like any other agent.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · manasXP/kitbash | 100 | MIT |
| open-dev-society/kitbash | 100 | LGPL |
Database snapshot: 13.11.2026 · package version 79be10e3a6db (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 92create-subagents
Expert guidance for creating, building, and using Claude Code subagents and the Task tool. Use when working with subagents, setting up agent configurations, understanding how agents work, or using the Task tool to launch specialized agents. - 100ask-pmai
Entry point for a PM who wants evals for an AI agent. Sets up the evals/ folder, finds the agent and its conversation logs, and routes to the next skill. Use when the user says they want to evaluate, test, measure or improve an agent, asks "where do I start with evals", or has… - 100use-claude-code-subagents
Use when Cursor subagents run on the parent model instead of the model in their agent file, or the user asks: "use claude code subagents", "run scout on haiku", "why are my subagents all Opus?". Runs custom subagents through headless Claude Code. Skip for Cursor's built-in subagents or Cloud Agents. - 90using-subagents
指导如何可靠使用 subagents、多个 Agents、并行 Agent 审查、集群搜索和项目分片处理。当用户要求使用 Agents/SubAgents、并行 Agent、对抗审查、多角色审查、集群搜索、项目分片处理,或明确说出“进入agents approve迭代模式”时使用。 - 100coding-evals
Use to build evals for the coding agent a team uses (Claude Code, Codex, OpenHands, or the team's own setup of one) from real coding sessions, pull requests and git history, and to run them to measure how that agent does on the team's code, check whether a change helps (a model,… - 100subagent-authoring
Create, review, refactor or slim down Claude Code subagents (`.claude/agents/*.md`). Use whenever the user mentions subagents, agent definitions, agent frontmatter (tools, model, skills, memory, hooks), a bloated or overlapping agent, splitting or merging agents, delegation not…