Michał Kopeć
0c06cb64ab
Commit all in-flight work — ckb-module and ckb-reset skills, the .agents/modules/ scaffold, OPENSPEC docs, decision records D-0001 and D-0002, graph edges and workload summaries — so the reset that follows is fully recoverable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.5 KiB
| type | tldr | status | decided_on | decided_by | affects | confidence | quality | last_updated | freshness_window_days | retention |
|---|---|---|---|---|---|---|---|---|---|---|
| decision | Optional KB capabilities ship as file-based modules under `.agents/modules/<name>/`, installed into the KB on request, rather than as native Claude Code plugins. | accepted | 2026-09-20 | Michał Kopeć | /wiki/index.md | 0.9 | 0.8 | 2026-09-20 | 365 | high |
D-0001 — Optional KB capabilities ship as file-based modules, not native plugins
Status: Accepted · Decided: 2026-09-20 · Deciders: Michał Kopeć
Context
The base KB ships fourteen ckb-* skills, all always loaded. Some capabilities
are only useful to some knowledge bases — the first concrete case being a KB
that documents software the user is building (see
D-0002 / D-0002). Adding
those skills unconditionally would grow the always-loaded skill-description
budget for every KB, including ones that will never need them.
Three mechanisms were on the table for making a capability opt-in. The KB is
deliberately agent-agnostic: AGENTS.md is the source of truth and CLAUDE.md
is a symlink to it (git mode 120000), as is .claude/skills → .agents/skills.
That symlink arrangement is a confirmed preference, and it means anything written
to .agents/skills/ is visible to Claude Code for free.
Decision
Optional capabilities are packaged as file-based modules stored in
.agents/modules/<name>/ and installed into the KB on explicit request. A
module may contribute skills (into .agents/skills/), directory scaffold, a
routing block appended to AGENTS.md, and .gitignore rules. Installation is
recorded in a root manifest listing the installed modules and their config;
uninstalling reverses it.
Rationale
A module is a property of the knowledge base, not of the machine or the agent
reading it. File-based modules travel with a clone, so a cloned KB stays
self-describing, and they work for any agent that reads AGENTS.md — not only
Claude Code. Shipping module content outside .agents/skills/ until install
keeps the always-loaded skill budget flat for KBs that don't opt in.
Consequences
- A
ckb-module-style install/uninstall path is needed. ckb-initshould offer modules at bootstrap;ckb-upgrademust not delete module-installed skills it doesn't recognise upstream, and must also upgrade.agents/modules/.ckb-lintgains validation of the module manifest.- Module skills are authored so they could also be published as a native Claude Code plugin later without a rewrite — this decision doesn't foreclose that, it just declines to make it the primary mechanism.
- Because
.claude/skillsis a symlink, an installer writes.agents/skills/only; no duplicate copy to keep in sync.
Alternatives considered
- Always-shipped skills that self-gate on a flag — no install step and trivially upgradeable, but every skill description stays in context for every KB regardless of relevance. Rejected: that budget degrades quietly.
- Native Claude Code plugin (
.claude-plugin/plugin.json+ marketplace) — real enable/disable and no file copying, but serves only Claude Code, breaking the dual-headedAGENTS.md/CLAUDE.mdcontract, and installs per-machine rather than per-KB. Rejected as the primary mechanism, not ruled out as an additional distribution channel.
Sources
Chat conversation, 2026-09-20 — design evaluation of a source-code/software KB
mode. See workload/2026-09-20_summary.md.