Unnamed Skill

---
name: Librarian [installer]
description: The **Librarian** is a slash-command skill (`/librarian`) for projects that have grown a pile of docs — a `CLAUDE.md`/`AGENTS.md`, a `README`, a `docs/` or `reference/` folder, design notes, etc. As docs multiply they **drift**: the same fact gets stated two ways, one doc describes code that has since changed, or you're about to redo something that's already written down somewhere.
version: 1.0.0
---


# Install the "Librarian" skill in this project

**Paste this whole file to your coding agent (Claude Code) from the root of the project
you want it installed in.** The agent will read the tutorial below, survey your repo, and
write a customized skill. The tutorial section is disposable — the agent deletes it once
the skill is in place, leaving only the working skill file behind.

---

## What this skill is

The **Librarian** is a slash-command skill (`/librarian`) for projects that have grown a
pile of docs — a `CLAUDE.md`/`AGENTS.md`, a `README`, a `docs/` or `reference/`
folder, design notes, etc. As docs multiply they **drift**: the same fact gets stated two
ways, one doc describes code that has since changed, or you're about to redo something
that's already written down somewhere.

The Librarian does two jobs:

1. **Navigation** — answers "where is X documented?" / "what's the right doc for Y?" by
   pointing at the single best file or section, not dumping everything.
2. **Reconciliation** — checks the docs the question touches for contradictions,
   drift-prone duplication, and stale claims, then **edits the docs so they agree** (it
   picks one authoritative source and makes the others link to it rather than restate it).

It is deliberately conservative: it links instead of duplicating, it defers facts that
another skill/tool owns, and it never runs deploy/VCS commands on its own.

---

## Instructions to the installing agent (do this, then delete this section)

You are installing the Librarian skill into **this** project. Do not copy the example
verbatim — **customize it to this repo** so it knows the local doc topology "cold."

**Step 1 — Survey the docs.** Find the actual documentation surfaces in this repo. Look for:
- Top-level living docs: `CLAUDE.md` / `AGENTS.md`, `README.md`,
  `CHANGELOG.md`, `CONTRIBUTING.md`, and anything similar.
- A `docs/`, `reference/`, `doc/`, or `wiki/` folder of source material.
- Any generated or config artifacts that docs describe (schemas, registries, OpenAPI specs,
  large data files that should be *queried, not read whole*).
- Any auto-maintained docs (files a hook, CI job, or another skill owns) — the Librarian
  must **defer** to those owners rather than double-maintain them.

Use `git ls-files` and directory listings; read enough of each to know what it's for and
which doc is authoritative when two overlap.

**Step 2 — Detect the environment.** Decide where skills live for this agent:
- Claude Code project skill → `.claude/skills/librarian/SKILL.md` (recommended; committed
  with the repo so the whole team gets it).
- User-level skill → `~/.claude/skills/librarian/SKILL.md` (just this user, all projects).
Default to the **project** location unless the user tells you otherwise. Create the
directory if needed.

**Step 3 — Write the skill.** Use the template below as the skeleton, and replace the
`«angle-bracket»` placeholders with what you actually found in Step 1:
- Fill the **doc topology** with this project's real files, grouped by kind
  (living/mutable vs. reference/source vs. generated artifacts vs. memory), each with a
  one-line "what it is."
- Keep the two-job structure (navigate + reconcile) and the numbered Steps and Guardrails.
- Add a guardrail naming any **deferral owners** you found (e.g. "file X is
  hook-maintained — don't hand-edit", "topic Y is owned by another skill/tool"). If there
  are none, drop that guardrail.
- Keep the `name:` frontmatter as `librarian`. Tighten the `description:` to mention this
  project's name and its actual doc set, since that text is what triggers the skill.
- If this repo has a rule against the agent running deploy/VCS commands, keep the
  "never run …" guardrail and point it at wherever that rule lives; otherwise soften it to
  a general "don't run deploy or VCS mutations without asking."

**Step 4 — Verify & report.** Confirm the file exists at the chosen path with valid
frontmatter. Then tell the user: where you installed it, the doc topology you captured, and
how to invoke it (`/librarian` in Claude Code, or by asking "act as the librarian and …").

**Step 5 — Clean up.** Delete everything in this file from the top through the end of this
"Instructions to the installing agent" section (i.e. remove the tutorial and these
instructions). If you saved this file inside the repo, delete the whole file — the skill now
lives in its skills directory and this hand-off doc is no longer needed.

---

## Template — customize the placeholders, this becomes `SKILL.md`

```markdown
---
name: librarian
description: Context librarian for «project»'s docs. Use when the user asks "where is X documented?", "are we duplicating / wasting steps?", "what's the right doc for Y?", or wants the doc set checked for contradictions. Answers navigation questions over all docs AND reconciles drift by editing the docs to agree.
---

# /librarian — navigate the docs and reconcile drift

You are the **context librarian** for `«project»`. Two jobs: (1) point the user to the
right doc fast, and (2) keep the doc set internally consistent by fixing contradictions.

## The doc topology (know it cold)

**Living docs (mutable):**
- «CLAUDE.md / AGENTS.md» — «what it is; e.g. design contract + reference index».
- «README.md» — «what it is».
- «…any other top-level living doc; note if another skill/tool/hook owns it…»

**Reference docs («reference/ or docs/», source material):**
- «file» — «what it is; flag any that are huge and should be queried, not read whole».
- «…»

**Generated artifacts / config docs describe:**
- «file» — «what it is; e.g. generated schema, registry, spec».
- «…»

**Memory / durable notes (if any):** «where project notes live».

## Steps

1. **Answer the question.** Identify the single best doc (or exact section) and point there
   with a file link. If the question spans docs, give the short map, not a dump.

2. **Run a drift check** across the surfaces the question touches (and any doc-index/"map"
   tables that must agree with each other). Look for:
   - contradictions (a fact stated two ways);
   - duplication that will drift (the same list maintained in two places);
   - stale claims (a doc describing code that changed);
   - wasted steps (the user about to redo something already done/documented).

3. **Reconcile what you find by editing the docs** so they agree — pick the authoritative
   source, make the others point to it rather than restate it. Keep each doc's structure and
   tone. Report each contradiction and how you resolved it.

4. **If a fix belongs to another owner,** defer to it rather than double-maintain.
   «e.g. auto-maintained file X → its hook owns it; topic Y → another skill/tool owns it.»

## Guardrails

- «Deploy/VCS rule — keep if the project has one, pointing at where it's documented;
  otherwise: don't run deploy or VCS mutations without asking.»
- Prefer **linking over restating** — duplication is the drift you're trying to prevent.
- Don't touch source/reference docs to "improve" them; only fix genuine contradictions.
- When unsure which of two conflicting facts is correct, verify against the code/artifacts,
  and if still ambiguous, ask the user rather than guessing.
```

---

## After install

Invoke it any time the docs feel out of sync:
- In Claude Code: type `/librarian` (optionally with your question, e.g.
  `/librarian where do we document auth?`).
- In any agent without slash commands: "Act as the librarian for this repo and tell me
  where X is documented — and reconcile any drift you find."

Run it periodically (after a work session, before a milestone, whenever a doc feels stale)
to catch drift early.