kanbot-admin

Built-in skill. kanbot init installs it in .agents/skills/kanbot-admin/SKILL.md. See Skills. Source.

Frontmatter

Field	Value
name	kanbot-admin
description	Change this repo's kanbot setup with a human. Use to add or edit kanbot agents, skills or project memory, map capabilities, give workers MCP servers, change .kanbot/config.yml, switch identity mode, turn on merge on approval, run kanbot upgrade or merge .kanbot-new files. Not for board jobs. For setup walkthroughs and explaining options, use kanbot-guide.

---

kanbot admin

You are helping a human maintain kanbot, the board-driven agent team in this repo. Board agents (planner, implementer, reviewers, fixer) never use this skill. To explain options or set kanbot up from scratch, use kanbot-guide.

Map

Path	What	Edit?
.kanbot/agents/<name>.md	Agent definitions, the source of truth	Yes, then kanbot sync
.agents/skills/<name>/	Skills shared by all agents	Yes
.kanbot/config.yml	Daemon config; schema next to it	Yes, then restart the daemon
.mcp.json	MCP servers workers get	Yes, then commit
.kanbot/manifest.json	Template hashes from the last upgrade	Never by hand
.claude/, .codex/	Generated by kanbot sync	Never; edit the source and sync
~/.kanbot/apps/<id>.pem	Private key of the kanbot GitHub App	Never commit

kanbot <command> --help lists every flag. .kanbot/config.schema.json describes every config field. Docs: https://kanbot.mib.im.

Recipes

Finish every recipe with kanbot sync when agents changed, then kanbot doctor, then show the human the diff. The human commits and pushes; worktrees are made from the pushed base branch, so agents see nothing until then. Restart the daemon after config changes.

Switch to app mode

1. kanbot app create. The human clicks Create GitHub App on GitHub, then installs it on the repo.
2. Already have an app from another repo? kanbot app link --id <id> --slug <slug>, add the repo to its installation, and copy ~/.kanbot/apps/<id>.pem if on another machine.
3. kanbot doctor checks the app, its key and the install.

Back to user mode: set identity.mode: user.

Turn on merge on approval

1. Set merge.onApproval: true and pick merge.method (squash, merge or rebase).
2. Recommend app mode, so they can approve their own kanbot PRs.
3. Warn: never enable the branch rule "Require approval of the most recent reviewable push". It blocks their own approval.

Map a capability

kanbot's agents run the process; the repo's own skills and agents do the work on code. Capabilities tell them which to use.

1. Make sure the skill is in .agents/skills/<name>/ or the agent in .kanbot/agents/. A .claude/agents or .codex/agents agent works on one provider only.
2. Add it under capabilities in config: review: code-review, or { use, when, required } when it only applies sometimes or a miss should block acceptance review.
3. Reserved names: verify (prove acceptance criteria), review (technical review, pass 1), preview (something a human can try). Any other name is the human's.
4. kanbot doctor lists what's mapped, flags a missing use, and names reserved needs not yet mapped.

Don't add implementers or type:* labels. implementers in config is deprecated: replace it with capabilities and remove it.

Give workers an MCP server

Add it to .mcp.json (Claude's format) and commit. Workers get only these servers, never the human's own. Codex can't run sse servers; kanbot doctor lists what workers get.

Add or change an agent

1. Copy the closest existing agent. name must match the filename.
2. Column agents (tier: column) need an output schema; subagents (tier: sub) are reached through a column agent's subagents.
3. To have board agents use it, map it as a capability (above).
4. The body says how to work. The daemon's prompt carries the task.

Add a skill

1. Create .agents/skills/<name>/SKILL.md with name (matches the folder) and a description that says what it covers and when it applies.
2. For work on code, map it as a capability. For kanbot's own process, add the name to skills in each agent that should load it. kanbot doctor fails on skills that don't exist.

Add a memory

When the human says "remember that …" or corrects something agents keep getting wrong, add a fact per project-memory. Stack, commands and conventions go in project-conventions instead.

Upgrade kanbot

1. Run bunx kanbot@latest upgrade --dry-run and summarise it for the human.
2. Run bunx kanbot@latest upgrade.
3. Merge every .kanbot-new file (below).
4. Files kanbot no longer ships stay in place. If the repo had kanbot's old craft skills (verify-ui, code-review, tdd…) and no capabilities, upgrade maps them. Show the human the new capabilities block. Old implementer-* and reviewer-* agents are unused once the new ones exist; the human may delete them.

Merge .kanbot-new files

For each <file>.kanbot-new next to <file>:

1. Diff the two. Name each difference: the human's customisation, or kanbot's improvement.
2. Write the merged result into <file>: keep every customisation, take every improvement. Where they collide, ask the human.
3. Delete <file>.kanbot-new.

Done when kanbot doctor reports no unmerged .kanbot-new files and the human has seen a per-file summary of what was kept and taken.