agentleFS
Sign inStart free
paslavskyipaslavskyi/llm-wiki/.claude/skills/kb-evolve/SKILL.md

kb-evolve

Skill1 starsChanged 31 days agoMITView on GitHub

Use to change existing knowledge safely — rename, deprecate, merge, or split notes — without breaking the graph. Computes blast radius first; never reuses or deletes an id (tombstone via superseded_by).

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. SterlingJF/knowledge-bus★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository11 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run node tools/impact.mjs <ID> (optionally --depth N) and show the blast radius (who links to this note, what it links to).

    line 12
  2. Distinctive:

    Create the new note with a fresh id via the write pipeline.

    line 30
  3. Very specific:

    Do NOT mass-rewrite backlinks.

    line 32
  4. Very specific:

    Never reuse or delete an id.

    line 50
  5. Very specific:

    All writes go through the write pipeline (tools/write-note.mjs) so the rule_set (heal) and atomic write apply.

    line 51
  6. Very specific:

    Never hand-edit index/. After writes, the Stop hook reindexes.

    line 53

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

kb-evolve — safe evolution of notes

Goal: change already-captured knowledge without breaking links or violating the stable-id invariant.

Before any change with ripple

Run node tools/impact.mjs <ID> (optionally --depth N) and show the blast radius (who links to this note, what it links to). Decide WITH the user. Note: edges include ALL reference fields — links, body [[..]], goal scope, plan active/queue/backlog, timeline sequence — so membership in a goal, the operational plan, or the product timeline shows up in the radius. When deprecating a note that a plan/timeline references, validate will demand the reference be re-pointed (plan/timeline must hold live ids; use npm run plan for plan lists).

Operations

rename-in-place — SAME id prefix (cosmetic)

The change stays within the same category (better slug / title / wording). Keep the id; update title (and thus filename) by writing through the write pipeline (tools/write-note.mjs). Backlinks untouched (they point at the id).

tombstone migration — DIFFERENT id prefix (meaning changed)

AB-123 should become CD-xxx (e.g. a requirement was really an NFR):

  1. Create the new note with a fresh id via the write pipeline.
  2. Mark the old note status: deprecated + superseded_by: CD-xxx (write pipeline).
  3. Do NOT mass-rewrite backlinks. They remain valid (validate allows links to a deprecated note) and surface as Tier-1 "migration debt" in index/health.md. Debt heals passively (each note's next write reconstructs it to the live id) or in bulk via kb-sanitize.

deprecate

Set status: deprecated (+ superseded_by if there is a successor) via the write pipeline.

merge

N notes → one target. The others become deprecated + superseded_by: <target>. Move any unique content into the target first.

split

One note → several. Original becomes deprecated + superseded_by (to the main heir) OR is repurposed as an umbrella topic (judgment call). New notes get fresh ids.

Invariants

  • Never reuse or delete an id. Retire via deprecated + superseded_by (tombstone).
  • All writes go through the write pipeline (tools/write-note.mjs) so the rule_set (heal) and atomic write apply. Never hand-edit notes for evolution.
  • Never hand-edit index/. After writes, the Stop hook reindexes; graph.mjs refreshes health.md (or run npm run graph).

Output (per mode)

  • debug: show the blast radius, which notes changed, ids, and the resulting debt.
  • autonomous: short human acknowledgement; hide ids/mechanics.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free