A Claude Code skill that maintains a living knowledge base about your codebase as short, focused markdown files.

Librarian manages a .knowledge/ directory in your project root. Each file covers one topic (architecture, auth, data flow, a design decision) in under 80 lines with YAML frontmatter. An auto-generated index makes retrieval fast — Claude reads one file to know what context exists, then pulls in what's relevant.

Before a task: checks the knowledge base for relevant context. After a task: records decisions, gotchas, and non-obvious patterns worth remembering.

Claude Code has three persistence systems. Librarian occupies a specific niche:

CLAUDE.md enforces that the knowledge base gets checked. The skill handles the rest.

From your project root:

git clone https://github.com/gokuito/librarian .claude/skills/librarian

Or copy manually:

mkdir -p .claude/skills/librarian
cp -r <path-to-librarian>/* .claude/skills/librarian/

Your project should look like:

your-project/
├── .claude/
│   └── skills/
│       └── librarian/
│           ├── skill.md
│           └── references/
│               ├── claude-md-snippet.md
│               ├── file-template.md
│               ├── index-template.md
│               ├── verification-prompt.md
│               └── writing-guide.md

After installing, tell Claude Code:

bootstrap the knowledge base

This will:

1. Create .knowledge/ with initial files based on a project scan
2. Ask you about key design decisions for each area documented
3. Verify everything — an agent checks all paths, summaries, cross-references, and factual claims against the actual code, then fixes issues
4. Generate _index.md from file frontmatter
5. Add knowledge base directives to your CLAUDE.md (creates one if needed)
6. Ask whether to commit .knowledge/ or gitignore it
7. Ask about maintenance automation — pre-commit hook (recommended) or manual only

You can re-run verification anytime with "verify the knowledge base".

After a big refactor or restructure, use "refresh the knowledge base" — it updates stale paths and facts in place while preserving your decisions and context.

The skill triggers automatically for non-trivial tasks when CLAUDE.md enforcement is in place. You can also invoke it directly:

• /librarian — check for relevant context
• "update the knowledge base" — record what just happened
• "document this decision" — capture a design decision
• "how does auth work?" — retrieve and summarize relevant knowledge
• "verify the knowledge base" — check accuracy against current code
• "refresh the knowledge base" — update stale paths/facts after a refactor

The bootstrap offers to install a pre-commit hook that checks .knowledge/ files before each commit. It catches:

• Dead file paths in frontmatter terms and file body
• Broken ## See also cross-references
• Missing YAML frontmatter

The hook warns but does not block — stale knowledge shouldn't prevent shipping code. Output tells you what's stale and suggests running "refresh the knowledge base" to fix it.

If you skipped the hook during bootstrap or need to reinstall:

cp .claude/skills/librarian/references/pre-commit-hook.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

If you already have a pre-commit hook, append the librarian checks to it instead of overwriting.

After pulling updates to the librarian skill, recopy the hook:

cp .claude/skills/librarian/references/pre-commit-hook.sh .git/hooks/pre-commit

• Design decisions (especially rejected alternatives and why)
• Non-obvious data flow or integration points
• Environment/config that isn't self-documenting
• Gotchas that cost time

What doesn't get recorded: trivial fixes, things obvious from the code, anything already in git log.

Every file has YAML frontmatter with summary, tags, terms, and updated. The terms field acts as a distributed dictionary — team jargon mapped to exact code paths, owned by the file that covers that topic.

---
summary: JWT access + refresh tokens, RBAC via Casbin
tags: [auth, security, middleware]
terms:
  perms: RBAC permission checks → `src/middleware/authorize.ts`
  auth: JWT authentication layer
updated: 2025-06-15
---

# Authentication

Auth uses JWT access tokens (15min TTL) + refresh tokens (7d, stored in
httpOnly cookie). Issued by `src/services/auth/token.ts`. Validated by
`src/middleware/auth.ts` on every protected route.

## Decisions
- **2025-03-10: Chose Casbin over Cedar for RBAC** — Cedar wasn't stable
  enough for production use at the time

The index (_index.md) is auto-generated from frontmatter after every write. It aggregates all files, terms, and tags into a single read.

librarian/
├── skill.md                          # The skill prompt
├── README.md
└── references/
    ├── claude-md-snippet.md          # CLAUDE.md directives to copy into projects
    ├── file-template.md              # Knowledge file + decision file templates
    ├── index-template.md             # Auto-generated index format
    ├── pre-commit-hook.sh            # Git hook for catching stale knowledge files
    ├── verification-prompt.md        # Agent prompt for verifying knowledge base accuracy
    └── writing-guide.md              # Writing style rules and examples