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
- pfeff/claude-skillstheir own version, first seen Nov 1, 2026
- Slava-code/college-kbtheir own version, first seen Oct 15, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- pfeff/claude-skills★ 4same name
- 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.
- CLAUDE.mdCLAUDE.md
- kb-dashboardSkill
- kb-elicitSkill
- kb-evolveSkill
- kb-goalSkill
- kb-orientSkill
- kb-planSkill
- kb-recallSkill
- kb-recapSkill
- kb-sanitizeSkill
- kb-visualizeSkill
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
- Very specific: line 13
Before writing, use the kb-recall skill to check whether this concept already exists:
- Very specific: line 19
If the update would ripple to other notes (their meaning depends on this change), stop and hand off to kb-evolve.
- Very specific: line 23
When the knowledge comes FROM something — an interview, a document, a URL, survey or analytics data, research you ran, or the owner's …
- Distinctive: line 36
Before writing a risk / assumption / trade-off / caveat into a note body, ask: "Have I already stated this same concern elsewhere?"
- Very specific: line 38
If it recurs in ≥2 notes, it is cross-cutting: create ONE canonical note for it (RISK-/ASMP-/Q-.
- Very specific: line 45
If the duplication already exists across notes, canonicalize + relink (use kb-evolve to replace inline restatements with a link).
- Very specific: line 66
Write via the atomic write pipeline — npm run kb:write (JSON on stdin, wraps tools/write-note.mjs.
- Very specific: line 71
Do NOT hand-edit index/.
- Very specific: line 95
Never guess silently. Where a detail is unknown, write [NEEDS CLARIFICATION: …].
- Very specific: line 103
Update STATE.md ONLY for non-derivable intent (current focus / next step).
- Very specific: line 114
Never reuse or delete an id.
≈ “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.
Files
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 plainlinksentry. - 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: acceptedif 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-evolveto replace inline restatements with a link).
Step 2 — IDENTIFY
- Pick the
typefrom the vocabulary inCLAUDE.md. - Choose the matching domain folder (
topicandrisk/assumption/questionmay 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:writeprints 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 andvalidate.
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(+idwhen updating) +priority, categoryfor requirement/nfr;parentfor topic; pluslinks, 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 todraftfor owner-approved facts. - Write via the atomic write pipeline —
npm run kb:write(JSON on stdin, wrapstools/write-note.mjs; NOT a raw Write): it reconstructs the note to a healthy state (rule_set: setsupdated, preservescreated, 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.mjsautomatically. If it reports an error, fix the note until validation passes. - Update
STATE.mdONLY for non-derivable intent (current focus / next step). NEVER put note counts, per-domain progress, or open-question lists there — those are generated inindex/MAP.md+index/health.md(an open question is captured as aQ-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/.
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
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.

