ckb/.agents/skills/ckb-module/SKILL.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

155 lines
6.6 KiB
Markdown

---
name: ckb-module
description: 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
Modules are present in the repo but inert, so their skill descriptions cost
no context in a KB that never needs them. See
[D-0001](/docs/decisions/0001-opt-in-file-based-kb-modules.md) for why they
are files in the repo rather than an 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:
```yaml
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.yaml` lists it, say so and offer to reinstall
(refresh the files) or stop. Don't silently re-copy.
- **Schema.** If `requires_kb_schema` is above `wiki/index.md`'s
`kb_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 to
`ckb-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
```bash
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`** — append `agents_fragment` at the end of the file, inside
markers. `CLAUDE.md` is a symlink to `AGENTS.md`, so it updates for free;
never write `CLAUDE.md` directly.
- **`.gitignore`** — append `gitignore_fragment`, inside markers (`#`-commented).
- **`wiki/index.md`** — bump `kb_schema_version` to `requires_kb_schema` if the
module's additions raise it. Additive only, per `ckb-upgrade`'s versioning
policy.
### Step 5 — Record, log, report
- Add the module to `ckb.yaml` with its version and today's date.
- Log to `wiki/log.md` per Rule B **only** for the `wiki/index.md` change — the
rest is template layer, not wiki content.
- Append to `workload/YYYY-MM-DD_<author>_summary.md` per 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:
1. 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.
2. Strip the marked blocks from `AGENTS.md` and `.gitignore`.
3. 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`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.