| name | kanna |
| description | Router and shared ground rules for ANY work in the Kanna repo — read this first to find the specialist skill for the task. Use whenever the work touches this codebase: adding a feature or a field, changing a type or contract shared between server and client, wiring a new event or read-model, a chat/session that got stuck or behaved wrong, metrics and performance questions, React or client UI edits, running tests or clearing lint and ast-grep gates, cutting a release, reviewing a PR, or "where does this live" and "what else do I have to update". Use it especially when the task spans several of those, when it starts with "what's the best way to…" or "how do I add…", or when you are unsure which Kanna skill applies — routing costs one short read and prevents guessing at conventions this repo enforces mechanically. |
Kanna — start here
Kanna is a local-first Bun + React agent host: an event-sourced server (src/server/),
a React client (src/client/), and shared contracts (src/shared/). Most of what
looks like a style preference here is actually enforced by a gate — ESLint,
ast-grep, or a test — so a change that "looks fine" can still fail CI. This skill
routes you to the specialist that knows the relevant gate, and holds the few rules
that apply to every task regardless of area.
Route by symptom
Match the task to a row and read that skill before you start. Paths are relative
to the repo root, so Read works even if the skill does not auto-trigger.
| The task involves | Read |
|---|
| A chat/session id, "why did this turn fail", stuck or hung turn, a tool that never returned, wrong model, billing to API instead of subscription | .claude/skills/kanna-debug/SKILL.md |
| Metrics, spans, traces, Grafana, "no telemetry arriving", the OTel collector, "why is it slow", memory growth, RSS, an OOM kill | .claude/skills/kanna-telemetry/SKILL.md |
Editing .tsx/.ts under src/client/** — components, hooks, formatting helpers, layout, tooltips | .claude/skills/kanna-react-style/SKILL.md |
| Running tests, a green-locally-red-on-CI failure, lint / ast-grep / design-gate errors, "how do I verify this" | .claude/skills/kanna-test/SKILL.md |
| Publishing a version, changelog, npm release | .claude/skills/release/SKILL.md |
| Reviewing a pull request for safety or correctness | .claude/skills/review-pr/SKILL.md |
| Filing a bug or feature request, writing up a defect found mid-task, handing a finding to another agent | .claude/skills/github-issue/SKILL.md |
| Adding a field the server sends and the client renders, or otherwise changing a contract across the WS boundary | src/shared/types.ts defines it once, both sides import it — never redeclare the shape on the client. Then .claude/skills/kanna-react-style/SKILL.md for the render, and c3 if it moves a boundary |
| "Where does X live", component boundaries, whether a change needs a doc update | the c3 skill (see below) |
| Visual design, spacing, color tokens, typography polish | the impeccable skill; DESIGN.md at the repo root is the source of truth |
| Deploying or debugging infra on the lowbit Dokploy host | the dokploy skill |
| Adding a shadcn/ui primitive | .claude/skills/shadcn/ |
Several rows can apply at once — a slow UI render is kanna-telemetry for the
measurement and kanna-react-style for the fix. Read both; they are short.
Rules that apply to every task
These hold no matter which specialist you land on.
Query C3 before you code. .c3/ holds this repo's architecture facts —
component boundaries, contracts, ADRs, and the rules each component must follow.
Run /c3 query <topic> (or c3x lookup <file>) before editing, even for a small
change. The facts record decisions whose reasons are not visible in the code, so
skipping the lookup means patching against assumptions the repo already discarded.
If your change moves a boundary, alters a public contract, or adds an
architecture-significant file, update .c3/ in the same PR — drift is treated as
a blocker.
Work in a git worktree. Land changes on a branch in a worktree rather than the
main checkout: several agents run against this repo concurrently, and a shared
checkout means they overwrite each other's edits.
Write the test first. New behavior is two commits — the failing test, then the
implementation. The split is what proves the test can actually fail; a test written
alongside its implementation can be a tautology that passes for the wrong reason.
Fix the root cause. Prefer the correct change over the quick one. A workaround
that leaves the underlying defect in place is not done, and "done" here means no
follow-up items left open.
Let the code explain itself. Default to zero comments: name things well and
extract helpers instead. Comment only to record why — an invariant, a constraint,
a workaround the code cannot express on its own.
One source of truth, flowing one direction. A value should be defined once and
derived everywhere else. When you find the same fact in two places, the fix is to
delete one, not to keep them in sync.
Design for the lowest total complexity (Ousterhout). Prefer deep modules — a
simple interface over substantial implementation — to a chain of shallow helpers.
Keep tightly related logic together and extract only when the extraction earns a
real abstraction. Design the interface before the implementation, and ask whether
the change leaves the system easier to understand, not merely whether it passes.
Look up unfamiliar libraries. Use Context7 for any library you are installing,
upgrading, or using in an unfamiliar way, rather than recalling an API that may
have shifted.
Verify before reporting. bun run test, bun run lint, and bun run typecheck
must pass — see .claude/skills/kanna-test/SKILL.md for the flags that matter and
the failures that only reproduce on CI. Report what actually happened: if a check
failed or you skipped one, say so plainly.
Diagrams
When explaining architecture or brainstorming a design, a Mermaid diagram usually
carries the shape better than prose. Kanna renders Mermaid inline, so a syntax
error reaches the reader as a broken diagram — validate every diagram with
mcp__kanna__validate_mermaid before you send it. Quote any label containing
[ ] ( ) { } | or ", or one starting with /; write dotted link ends in full
(-.-x, not -.x).
Working on the skills themselves
These files have two consumers: Claude Code auto-triggers on the description
frontmatter, and Kanna's own / picker parses the same files through
LocalCatalogService (src/server/local-catalog-io.adapter.ts, fact c3-231).
That parser is line-based, so a description must stay on one line — a folded
>- block silently reduces to an empty description in the picker. user-invocable: false hides a skill from the picker while leaving auto-triggering intact; use it
for skills only ever reached by routing.
