Curation write-back

kcap curate apply writes the guidelines promoted for a repo into that repo’s CLAUDE.md / AGENTS.md, inside a managed block. It’s the file-based counterpart to session-start injection: instead of guidance appearing in the agent’s context automatically, it lives in your instruction files, in version control, visible in code review.

For the usual workflow of reviewing accumulated lessons, prefer Docs and skills. Use write-back when a short, stable rule specifically belongs in the repository’s version-controlled instruction files.

Write-back vs. injection

In Knowledge → Queue, promoting a lesson can select independent delivery targets. Two targets deliver individual guidelines to agents:

• Injection — automatic and ephemeral. Applicable promoted guidelines are fed into the agent’s context at session start; nothing touches disk. (See Evaluations.)
• Write-back (claude_md) — explicit and durable. kcap curate apply edits CLAUDE.md / AGENTS.md so the guidance survives outside Capacitor, ships in the repo, and shows up in git history.

Use either, both, or neither per cluster. This page is about write-back.

Prerequisites

• Run it inside the git repo you want to update — the repo is inferred from your working directory and its git remote, so there are no scope flags.
• At least one cluster must have been promoted with Write to CLAUDE.md / AGENTS.md for that repo. Clusters promoted only for injection aren’t written.

Usage

kcap curate apply            # show the diff, then confirm (Apply? [y/N])
kcap curate apply --dry-run  # print the planned changes and exit, writing nothing
kcap curate apply --yes      # apply without the prompt (CI / scripting); -y for short

apply previews exactly what it will change and waits for confirmation, so the default run is safe to try.

The managed block

Guidelines are written into a single block bounded by HTML-comment markers:

<!-- kcap:curated:start -->
## Curated guidelines

_Managed by `kcap curate apply` — do not edit; changes are overwritten._

- <guideline text>
<!-- kcap:curated:end -->

Everything outside the markers is left untouched. Re-running reconciles the block against the currently-promoted set: guidelines are added, updated, or removed, and if nothing is promoted any more the block is deleted. Because the block is regenerated each time, don’t hand-edit inside the markers — put your own guidance above or below them.

Which files it writes

kcap curate apply targets the instruction files at the repo root:

• Both exist → both CLAUDE.md and AGENTS.md are updated.
• One exists → that file is updated.
• Neither exists → AGENTS.md is created (the cross-harness default).

Safe to re-run

Applying is idempotent — run it as often as you like. It fails closed: if the managed block in a file has been hand-mangled (a missing or duplicated marker), the command aborts with a message to fix that file by hand rather than guessing. Nothing else in the file is rewritten.

Guidance documents as skills

Longer guidance approved in Knowledge → Docs has a separate delivery path. Choose Skill when approving the document, then run kcap skills sync inside the repository. This installs the approved document into supported agents’ user skill directories, rather than the managed instruction-file block. See Docs and skills.

Related

• Facts & curation — how clusters are promoted (and the CLAUDE.md target this command reads).
• Evaluations — where the findings that become clusters come from.
• Commands — the CLI reference.