Skills — The Agent Runtime

Skills teach agents the coordination protocol. They're embedded in the kanban binary and scaffolded by kanban init. Protocol skills ship with the project; task skills (domain logic) are yours to add.

Architecture: binary + skills = agent runtime

layers
Kanban binary = the protocol engine (Go)
Kanban skills = the agent runtime (markdown, one per role)
Agent runtime = Claude Code, PI, Codex, Gemini, ...

Different agents (Claude Code, PI, Codex, Gemini) all read the same skill files. The agents change. The protocol stays.

Skill hierarchy

LayerContentsRole
Agent .md filesmanager.md · worker.md · reviewer.md

YAML frontmatter: tools, model, workflow steps, skill references

Protocol skills14 skill files + INDEX

Embedded in binary, teach coordination protocol. Written once, read by any agent.

Task skillsYour .md files

Domain logic: how to deploy, run tests, write documentation, etc.

kanban CLIGo binary

SQLite transactions, lease enforcement, WAL checkpointing

Protocol skills (shipped)

manager/ — Planning and oversight

SkillTeaches the agent
dispatch-task

Create individual tasks with title, role, priority, project, and dependencies

dispatch-plan

Read a spec or PRD, extract tasks via 3-pass LLM process, write proposal

approve-plan

Read user-approved proposal, dispatch each checked task

review-backlog

View board state, check blocked tasks, search by status/role/project

view-task

Read full task detail including notes, history, lease status

worker/ — Claim and complete

SkillTeaches the agent
claim-next-task

Claim highest-priority available task. Reclaims expired leases. Supports batch claim.

claim-task

Claim a specific task by ID. Transfer protocol for handoffs.

log-progress

Report progress, renew lease, attach typed notes (PROGRESS, ERROR, DECISION)

complete-task

Submit work for review. Always goes to IN_REVIEW (mandatory gate).

block-task

Mark task blocked with reason, drop lease

reviewer/ — Gatekeeper

SkillTeaches the agent
claim-review

Claim highest-priority IN_REVIEW task for review (alias for claim-next with role=reviewer)

approve-task

Accept completed work. Supports --note for review feedback and --all for batch approve.

reject-task

Send work back to TODO with detailed reason. --note attaches feedback.

Agent definition format

Each agent role gets a .md file that defines its tools, model, and workflow:

.kanban/agents/worker.md
---
name: worker
description: Kanban worker agent that claims and completes tasks
---

You are a kanban worker agent. Claim and complete tasks
from the kanban board.

Workflow:
1. Claim the next available task
2. Work on the task, logging progress periodically
3. Submit for review (complete always → IN_REVIEW)
4. If blocked, mark with reason

Long-running tasks:
For work >15 min, periodically run:
  kanban task extend-lease <task-id> --agent <name> --minutes 30

Use claim-next --count N to claim multiple tasks
for parallel execution.

Skills in .kanban/skills/ provide detailed usage
instructions for bash fallback.

Adding custom skills

Task skills teach agents how to do the work, not how to coordinate. Place them alongside protocol skills:

file structure
.kanban/skills/
├── manager/            # Protocol skills (embedded)
├── worker/             # Protocol skills (embedded)
├── reviewer/           # Protocol skills (embedded)
├── deploy-to-prod.md   # Your custom task skill
└── sprint-review.md    # Your custom task skill

Init → agent run cycle

lifecycle
1. Scaffold
$ kanban init --plan plan.md
→ .kanban/kanban.db created
→ .kanban/agents/{manager,worker,reviewer}.md
→ .kanban/skills/ (14 skill files + INDEX)

2. Agent loads the config
$ kanban init
→ kanban CLI ready, 14 skills available

3. Run agents (harness-specific, e.g. pi run worker)
$ pi run manager   # Plans and dispatches work
$ pi run worker    # Claims and completes tasks
$ pi run reviewer  # Reviews submissions