agentleFS
paslavskyipaslavskyi/llm-wiki/.claude/skills/kb-capture/SKILL.md

kb-capture

Skill1 starsChanged 32 days agoMITView on GitHub

Use to record a single piece of product knowledge as an atomic note in this repo — resolves whether to create new or update existing, assigns a stable id, writes valid frontmatter, and links it into the graph.

2 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. pfeff/claude-skills★ 4same name
    2. Slava-code/college-kb★ 0same 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

11 rules. About 0 are common, 1 is distinctive, and 10 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.

  • 10

    Very specific

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

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

    Before writing, use the kb-recall skill to check whether this concept already exists:

    line 13
  2. Very specific:

    If the update would ripple to other notes (their meaning depends on this change), stop and hand off to kb-evolve.

    line 19
  3. Very specific:

    When the knowledge comes FROM something — an interview, a document, a URL, survey or analytics data, research you ran, or the owner's …

    line 23
  4. Distinctive:

    Before writing a risk / assumption / trade-off / caveat into a note body, ask: "Have I already stated this same concern elsewhere?"

    line 36
  5. Very specific:

    If it recurs in ≥2 notes, it is cross-cutting: create ONE canonical note for it (RISK-/ASMP-/Q-.

    line 38
  6. Very specific:

    If the duplication already exists across notes, canonicalize + relink (use kb-evolve to replace inline restatements with a link).

    line 45
  7. Very specific:

    Write via the atomic write pipeline — npm run kb:write (JSON on stdin, wraps tools/write-note.mjs.

    line 66
  8. Very specific:

    Do NOT hand-edit index/.

    line 71
  9. Very specific:

    Never guess silently. Where a detail is unknown, write [NEEDS CLARIFICATION: …].

    line 95
  10. Very specific:

    Update STATE.md ONLY for non-derivable intent (current focus / next step).

    line 103
  11. Very specific:

    Never reuse or delete an id.

    line 114

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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-capture — write one atomic note

Goal: capture exactly one concept correctly, without creating duplicates. Field-level formats per type live in formats.md — read the section for the type you are writing before Step 3.

Step 1 — RESOLVE (always first)

Before writing, use the kb-recall skill to check whether this concept already exists:

  • Same concept already noted → update that note.
  • Related but distinct → create a new note and connect it: a typed relation (relations: {mitigates|refines|addresses|serves|measures|answers|depends_on|conflicts_with: [ids]}, allowed pairs in formats.md) when one fits, otherwise a plain links entry.
  • Nothing found → create a new note. If the update would ripple to other notes (their meaning depends on this change), stop and hand off to kb-evolve.

Evidence check (provenance)

When the knowledge comes FROM something — an interview, a document, a URL, survey or analytics data, research you ran, or the owner's first-hand account — capture that origin as a source note (SRC-, folder sources, kind + origin; body = the verbatim quote/excerpt, never a paraphrase) and cite it from the claim note via sources: [SRC-…]. Numbers, dates and quotes in the claim must match the source exactly. Reuse an existing SRC- note when the same source backs several claims.

Recurring-concern check (avoid duplicating a thought across note bodies)

resolve above catches duplicate NOTES. This catches a duplicate THOUGHT — the same risk / assumption / trade-off / caveat re-stated inside the bodies of several otherwise-different notes (the dup-detection heuristic can't see this, because the titles differ).

Before writing a risk / assumption / trade-off / caveat into a note body, ask: "Have I already stated this same concern elsewhere?"

  • If it recurs in ≥2 notes, it is cross-cutting: create ONE canonical note for it (RISK-/ASMP-/Q-; status: accepted if it's a decided/accepted risk), and have the other notes link to it instead of restating it. Each note's body then describes only what is specific to it; the shared concern lives in the canon.
  • Threshold matters (avoid over-splitting): only canonicalize a concern that genuinely repeats as its own unit — not every passing mention of a word. One real second occurrence is the trigger.
  • If the duplication already exists across notes, canonicalize + relink (use kb-evolve to replace inline restatements with a link).

Step 2 — IDENTIFY

  • Pick the type from the vocabulary in CLAUDE.md.
  • Choose the matching domain folder (topic and risk/assumption/question may sit in any domain; every other type has exactly one — lib/vocabulary.mjs).
  • For a NEW note, omit id: the write pipeline assigns the next free one for the type's prefix (npm run kb:write prints it, e.g. created FR-007). For an update, pass the existing id. Type, id prefix and folder are enforced — a mismatch fails the write and validate.

Step 3 — WRITE (through the write pipeline)

  • Filename target: knowledge/<domain>/<ID>-<slug>.md (slug = kebab of title; the write pipeline derives it).
  • Build the note "intent" (frontmatter required fields: type, title, status, summary (+ id when updating) + priority, category for requirement/nfr; parent for topic; plus links, body). Status of a NEW note reflects how settled the knowledge is: draft = tentative/unconfirmed; proposed = awaiting the owner's verdict; accepted = the owner confirmed/decided it in this dialogue (approved decisions, goals, reached stages). Don't default to draft for owner-approved facts.
  • Write via the atomic write pipeline — npm run kb:write (JSON on stdin, wraps tools/write-note.mjs; NOT a raw Write): it reconstructs the note to a healthy state (rule_set: sets updated, preserves created, resolves any deprecated refs to live ids, dedupes links, removes self-refs, keeps unknown fields verbatim) and writes atomically.
  • Do NOT hand-edit index/.

Acceptance criteria (requirement / nfr / story)

State how we'll know it's done as acceptance: — one testable criterion per item, EARS (WHEN <trigger> THE SYSTEM SHALL <response>) or Given/When/Then, in the KB language. Pass plain strings; the pipeline numbers them <ID>.<n>. Make quality words measurable ("under 2 s at p95", not "fast"). Add verify: when the check isn't obvious.

Assumptions (ASMP-)

New assumptions start validation: open. When evidence arrives (an interview, data, an experiment) record it as a source note and set validation: validated or invalidated with sources: [SRC-…]. On invalidated, check health's "Invalidated assumptions still relied on" and revise those notes (kb-evolve).

Decision notes (DEC-, MADR)

Frontmatter: decided, deciders, consulted, informed, optional revisit (when to re-check). Body, in this order: ## Context (the problem and forces) → ## Considered Options (each with pros/cons) → ## Decision (the chosen option + why) → ## Consequences (good and bad) → ## Confirmation (how we'll know it still holds). Link what it decides via relations (e.g. answers: [Q-…], mitigates: [RISK-…]).

Uncertainty inside the note

Never guess silently. Where a detail is unknown, write [NEEDS CLARIFICATION: …]; where you filled a gap with a guess, write [ASSUMPTION: …]. A note with markers cannot be accepted (the pipeline refuses) — resolve them with the owner first. Promote a marker to a Q-/ASMP- note only when it spans several notes.

Step 4 — VERIFY

  • The PostToolUse hook runs node tools/validate.mjs automatically. If it reports an error, fix the note until validation passes.
  • Update STATE.md ONLY for non-derivable intent (current focus / next step). NEVER put note counts, per-domain progress, or open-question lists there — those are generated in index/MAP.md + index/health.md (an open question is captured as a Q- note, which health.md surfaces). Copying derived facts into STATE is what makes it drift. (See CLAUDE.md → "STATE.md scope".)

Output (per mode)

  • debug: state which note you created/updated, its id, and links added.
  • autonomous: a short human acknowledgement (e.g., "Занотував.").

Rules

  • One concept per note. If you're writing two ideas, make two notes.
  • Never reuse or delete an id. To retire a note, deprecate it (kb-evolve).
  • Never hand-edit index/.

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.