- Rule E resolves git user.name/user.email once per session; OS user as stated fallback. - Rule D: one workload file per person per day, YYYY-MM-DD_<author>_summary.md with type: session frontmatter; older files read as before. - Rule B log format gains an optional, lint-neutral **Author:** line; wiki/log.md header and ckb-upgrade example updated. - save_conversation.py records an author row (--author override); smoke fixture passes a fixed author. - ckb-project-summary and ckb-module cite the new workload name. - D-0004 records the decision; manual, READMEs and changelogs in English and Polish. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
6.8 KiB
| name | description |
|---|---|
| ckb-module | Install, list, or uninstall an optional Cascade KB module from .agents/modules/<name>/. Use for "install the <name> module", "what modules are available", "which modules are installed", "uninstall the <name> module", or a request for a capability the base KB lacks, such as handling source code. |
Module skill
Purpose
The base KB ships every skill always-loaded. Some capabilities are only useful to some knowledge bases, and their skill descriptions would otherwise sit in context for every KB that will never need them.
Optional capabilities therefore live in .agents/modules/<name>/ — present in the
repo, inert until installed. This skill is the install/uninstall path. See
D-0001 for why this is
files-in-the-repo rather than a native agent plugin: a module is a property of the
knowledge base, so it must travel with a clone and work for any agent that reads
AGENTS.md.
The manifest
Installed modules are recorded in ckb.yaml at the repo root:
template: # written by ckb-init, read and updated by ckb-upgrade
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main # main | test | experimental, or any branch of a fork
kb_modules:
- name: software
version: 1.0.0
installed_on: 2026-09-20
config:
src_repos: []
ckb.yaml holds repo-level configuration — what's installed, what it's
configured with. It is not the wiki's content contract: kb_schema_version
stays in wiki/index.md where it has always been. Two different things, two
different homes.
The template: block records which upstream repo and branch this KB takes
its tooling from. It belongs to ckb-init (writes it) and ckb-upgrade (reads
it as the default source, updates it when the user switches channel). This
skill must never drop or rewrite it: a module install that silently reset a
KB from the experimental channel back to main would change what its next
upgrade pulls, which is not a module's business. Read ckb.yaml, edit the
kb_modules: list, write it back with everything else intact.
If ckb.yaml doesn't exist, no modules are installed and no template source is
recorded; create it on first install, carrying forward any template: block
that a later ckb-upgrade may add.
Installing
Step 1 — Resolve and read the module
Find .agents/modules/<name>/module.yaml. If the name doesn't match, list what's
actually in .agents/modules/ rather than guessing at a near-miss.
Read the manifest: skills, scaffold, agents_fragment, gitignore_fragment,
schema_additions, depends_on, requires_kb_schema.
Step 2 — Check preconditions, and report them before writing anything
- Already installed? If
ckb.yamllists it, say so and offer to reinstall (refresh the files) or stop. Don't silently re-copy. - Schema. If
requires_kb_schemais abovewiki/index.md'skb_schema_version, the bump is part of this install (Step 4) — additive only. If the module needs a major version above the KB's, stop and hand it tockb-upgrade. - Dependencies. Run each
check. A failing optional dependency is a warning, not a blocker — report it plainly and continue. A failing required one stops the install. - Collisions. If a skill name in
skills:already exists in.agents/skills/, or a scaffold path exists with unrelated content, stop and ask. Never overwrite a skill the user may have edited.
Report all findings before the first write, then proceed (or ask, if anything needs a decision). A half-installed module is worse than an uninstalled one.
Step 3 — Copy the payload
cp -r .agents/modules/<name>/skills/<skill> .agents/skills/<skill>
.claude/skills is a symlink to .agents/skills (git mode 120000), so the
skills appear under .claude/ automatically. Do not create a second copy
there — that symlink is a deliberate choice, and duplicating it creates two
things to keep in sync.
Create each scaffold path, copying any from template to its as destination.
Never overwrite an existing scaffold file — skip it and note the skip.
Step 4 — Patch the shared files
Both patches are wrapped in markers so uninstall is exact:
<!-- ckb-module:<name> START -->
...fragment...
<!-- ckb-module:<name> END -->
AGENTS.md— appendagents_fragmentat the end of the file, inside markers.CLAUDE.mdis a symlink toAGENTS.md, so it updates for free; never writeCLAUDE.mddirectly..gitignore— appendgitignore_fragment, inside markers (#-commented).wiki/index.md— bumpkb_schema_versiontorequires_kb_schemaif the module's additions raise it. Additive only, perckb-upgrade's versioning policy.
Step 5 — Record, log, report
- Add the module to
ckb.yamlwith its version and today's date. - Log to
wiki/log.mdper Rule B only for thewiki/index.mdchange — the rest is template layer, not wiki content. - Append to
workload/YYYY-MM-DD_<author>_summary.mdper Rule D. - Report: skills now available and what they do, directories created, files patched, dependency warnings, schema bump if any. Then the standard reminder — on disk, not committed.
Offer to record a decision (ckb-decide) if installing the module was a real
choice for this KB rather than following a prior one.
Uninstalling
Reverse Step 3 and 4, in this order, and be conservative about data:
- Remove
.agents/skills/<skill>for each skill the manifest lists — but first diff it against.agents/modules/<name>/skills/<skill>. If the installed copy was edited, show the diff and ask before deleting. Offer to copy the edits back into the module folder so they survive. - Strip the marked blocks from
AGENTS.mdand.gitignore. - Remove the module's entry from
ckb.yaml.
Never remove scaffold directories or any content under them. src/ may hold
the user's clones, openspec/ their specs. Say explicitly what was left behind
and why, so nothing looks like an oversight.
Never remove wiki pages the module's skills created, and never lower
kb_schema_version. Those pages are knowledge; the module produced them but does
not own them, and they must stay readable without it. Say which page types
(repository, component, spec) will now have no skill maintaining them.
Listing
On "what modules are available": list .agents/modules/*/module.yaml with each
title and summary, marking which are installed per ckb.yaml. Keep it short
— name, one line, installed or not.
Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
references/edge-cases.md. Read that file when a
run hits something the steps above don't cover; don't load it otherwise.