---

name: librarian description: > Maintains a .knowledge/ directory of focused markdown files about the codebase. Trigger when: user asks about project structure, architecture, "why was X built this way", "how does Y work", onboarding questions; user says "update the knowledge base", "remember this decision", "document this", "verify the knowledge base", "refresh the knowledge base"; completing a feature/refactor/bugfix that involved non-obvious decisions or architectural changes. Do NOT trigger for trivial tasks (typo fixes, simple renames, one-line changes with no design impact). allowed-tools: Read Grep Glob Write Edit

Librarian — Project Knowledge Agent

Maintain a living knowledge base in .knowledge/ at the project root — short, focused markdown files with YAML frontmatter, indexed automatically.

Where knowledge lives — the three systems

Claude Code has three persistence mechanisms. They serve different purposes. Never duplicate information across them. When deciding where to store something, use this table:

| What | Where | Why | |------|-------|-----| | Project conventions, commands, rules ("use Prettier with tabs") | CLAUDE.md | Auto-loaded every conversation. Affects Claude's behavior. | | Deep context: architecture, data flow, design decisions, gotchas | .knowledge/ | On-demand retrieval. Too detailed for CLAUDE.md. Shared via git. | | User profile: role, preferences, corrections to Claude's behavior | Memory (user, feedback) | Personal. Not team knowledge. | | Active project state: who's doing what, deadlines, incidents | Memory (project) | Ephemeral. Changes fast. Per-user awareness. | | Pointers to external systems (Linear, Slack, dashboards) | Memory (reference) | Not codebase knowledge. External system locations. |

CLAUDE.md is rules. .knowledge/ is understanding. Memory is personal context.

If it tells Claude how to behave in this project → CLAUDE.md. If it explains why the codebase works this way → .knowledge/. If it's about the person or their current situation → Memory.

Core rules

1. Only write what you can verify. Every fact in the knowledge base must come from reading actual code, config, or the user's explicit statements. Never infer, assume, or fill gaps with plausible-sounding content. If you don't know something, leave it out — an incomplete file is better than a wrong one. If a detail matters but you can't confirm it, ask the user.
2. One topic per file, under 80 lines. Split when exceeded.
3. Every file has YAML frontmatter with summary, tags, terms, and updated.
4. _index.md is auto-generated. Rebuild it after every write by globbing .knowledge/*.md and reading frontmatter. Never edit it by hand.
5. Update, don't append. Rewrite stale content. Move old decisions to a ## Decisions log with dates and "superseded" labels.
6. Be brief. No narration of your process. Confirm updates in one sentence.

For file format: references/file-template.md. For index format: references/index-template.md. For writing style: references/writing-guide.md.

Frontmatter schema

Every knowledge file starts with:

---
summary: One sentence, max 20 words — what this file covers
tags: [topic, tags, for, filtering]
terms:
  shorthand: What it means → `exact/code/path.ts`
updated: YYYY-MM-DD
---

• summary — appears in the generated index. Be specific.
• tags — use decision for design decisions, domain tags for topics.
• terms — dictionary entries this file owns. Team jargon → code locations. Replaces the old standalone dictionary. Each file declares its own terms.
• updated — last modified date.

Rebuilding the index

After every write to .knowledge/, regenerate _index.md:

1. Glob .knowledge/*.md (exclude _index.md)
2. Read frontmatter from each file
3. Write _index.md with three tables: Files, Terms, Tags (see references/index-template.md for exact format)

This replaces manual manifest and dictionary maintenance. The index is always derived, never hand-edited, and can be regenerated from scratch at any time.

Retrieval

Scale effort to task complexity:

Light (most tasks): Read _index.md. If a relevant file is obvious from the index, read it. Done.

Deep (unfamiliar areas, cross-cutting changes, onboarding questions):

1. Read _index.md
2. Match task keywords against tags and terms
3. Read 1–3 relevant knowledge files
4. Inject a brief context block:

   Context loaded: [2–3 sentences with file paths and key facts]

If no knowledge exists yet, say so in one line and proceed with the task.

Staleness check: If a term or file reference points to a path that no longer exists, flag it briefly and fix it during the next record pass.

Recording

Only record when the task produced something worth remembering:

• Design decisions — especially rejected alternatives and why (tag: decision)
• Non-obvious data flow or integration points
• Environment/config requirements not evident from the code
• Gotchas that cost time and would bite someone again
• New domain terms or jargon

Skip recording for: trivial fixes, obvious changes, anything readable from code or git log.

Steps:

1. Create or update the knowledge file with proper frontmatter. Use Edit for surgical updates to existing files.
2. Add or update ## See also cross-references in related files.
3. Rebuild _index.md.
4. Confirm in one sentence.

Fix what you see: If during recording you notice a file over 80 lines, a dead term path, or overlapping files — fix it now. Don't defer.

Bootstrapping

Only when explicitly requested ("bootstrap the knowledge base", "set up librarian"). Never auto-bootstrap as a side effect of an unrelated question.

1. Create .knowledge/_index.md (empty, will be populated in step 7)
2. Scan project structure → create architecture.md with frontmatter
3. Scan .env*, docker-compose, CI config → create env-config.md if relevant
4. Scan codebase for key modules → populate terms in each file's frontmatter
5. Add ## See also cross-references between related files
6. Ask the user about key design decisions for each area documented. Present what you found ("matching uses a fuzzy threshold of 82 — do you remember why that value?") and record answers in ## Decisions sections. Don't skip this — decisions are the most valuable content in the knowledge base.
7. Verify — run the verification pass (see below) and fix all issues found.
8. Rebuild _index.md from all created files
9. Add the knowledge base directives to the project's CLAUDE.md (see references/claude-md-snippet.md — use the minimal version if CLAUDE.md is already long, full version otherwise. Create CLAUDE.md if it doesn't exist.)
10. Ask the user: commit .knowledge/ to the repo (shared team knowledge) or add to .gitignore (personal use)? Default recommendation: commit it.
11. Ask about maintenance automation. Present the options:
    • Pre-commit hook (recommended) — runs verification on .knowledge/ files before each commit. Catches stale paths and broken references before they land. Install via the hook script in references/pre-commit-hook.sh.
    • None — rely on manual "verify the knowledge base" and "refresh the knowledge base" commands. Install the user's choice. If they pick the pre-commit hook, copy references/pre-commit-hook.sh to .git/hooks/pre-commit and make it executable. If the project already has a pre-commit hook, append the librarian check to it instead of overwriting.

Verification pass

Launch an Explore agent to check every knowledge file against the actual codebase. The agent verifies: dead paths in terms/body, summary accuracy vs. file scope, bidirectional cross-references, factual claims vs. code, and frontmatter completeness.

Full agent prompt and trigger rules: references/verification-prompt.md.

Fix every issue the agent reports, then proceed to the index rebuild. This pass also runs during recording if more than 3 files were touched.

Refreshing

Triggered by "refresh the knowledge base" — for when the codebase changed significantly (big refactor, file moves, restructure) but existing knowledge is still conceptually valid.

Unlike bootstrap (starts from scratch) or verify (read-only check), refresh updates existing files in place while preserving decisions and context.

Steps:

1. Run the verification pass — collect all issues (dead paths, stale claims, broken cross-references)
2. For each dead path: scan the codebase for the renamed/moved equivalent. Update the path in terms frontmatter and file body. If the file was deleted entirely, remove the reference.
3. For each stale claim: read the current code and update the fact.
4. Check if any major new modules/files appeared that aren't covered by existing knowledge files. If so, create new files for them.
5. Do not rewrite or remove ## Decisions sections — those are still valid unless the user says otherwise.
6. Rebuild _index.md.
7. Summarize what changed: "Updated 12 paths across 3 files, added new-module.md, removed 2 dead terms."

Project integration

The skill only works reliably if the project's CLAUDE.md enforces it. Add this to the project's CLAUDE.md (see references/claude-md-snippet.md for a copy-paste block):

1. A directive to check .knowledge/_index.md before non-trivial tasks
2. A directive to record decisions after tasks that change architecture or introduce non-obvious patterns
3. The three-system rule so contributors know what goes where

Without CLAUDE.md enforcement, the skill depends entirely on trigger matching from the description field — which will miss tasks that don't contain obvious keywords. CLAUDE.md is what makes this systematic instead of opportunistic.

During bootstrapping, offer to add these directives to the project's CLAUDE.md automatically. If CLAUDE.md doesn't exist yet, create it with the knowledge base directives plus any other project conventions discovered during the scan.

Conflict handling

When new information contradicts the knowledge base:

1. Trust the new information — it reflects the latest decision
2. Rewrite the file with current state at the top
3. Move the old decision to ## Decisions with a date and "superseded" note
4. Rebuild _index.md