Reference Library Manager

Manage the project reference/source library as durable research infrastructure. This skill answers: What sources do we have, and what is their processing state?

Do not use this skill for deep source understanding or project implications. Use reference-reading-summarizer for "what does this source say?" and reference-project-synthesizer for "what does this source mean for our project?"

Skill Directory Layout

<installed-skill-dir>/
├── SKILL.md
├── scripts/
│   └── scan_reference_library.py
├── references/
│   └── library-policy.md
└── templates/
    ├── reference-index.md
    └── reading-status.md

Core Contract

• Default project reference root is <project-root>/reference/.
• A source can be a paper PDF, collaborator PDF/Word doc, Markdown note, BibTeX file, script, spec/config, notebook, webpage snapshot, or hand-built folder bundle.
• Raw source files may be private, licensed, large, or collaborator-provided. Do not assume they should be committed to a public repo.
• Commit derived indexes, source cards, and project-use notes only when they are sanitized and useful.
• Prefer deterministic scanning for filenames, hashes, size, and modification time.
• Use cheap sidecars only for fuzzy title matching or metadata cleanup, not for raw source storage.

Expected Project Layout

reference/
├── sources/                 # non-paper sources and bundles, often ignored/private
│   ├── collaborator-docs/
│   ├── markdown/
│   ├── bundles/
│   └── misc/
├── papers/                  # backward-compatible paper/PDF location
├── cards/                   # stable source cards from reference-reading-summarizer
├── project-use/             # project implications from reference-project-synthesizer
├── summaries/               # optional summaries
├── notes/                   # human notes
└── .agent/
    ├── source-index.md
    ├── reference-index.md   # compatibility alias
    ├── processing-status.md
    ├── reading-status.md    # compatibility alias
    ├── metadata-gaps.md
    ├── duplicate-check.md
    └── runs/                # raw scan/read trajectories, usually ignored

Model Routing

• Tier 0 script: scan files/folders, hashes, size, mtime, missing cards, processing-status skeletons.
• Tier 1 cheap sidecar: fuzzy duplicate titles, filename-to-title cleanup, coarse source type and role tags.
• Tier 2/3 models: not needed here; route to the reading or project synthesis skills.

Workflow

1. Locate project root and reference/. Prefer reference/sources/ plus backward-compatible reference/papers/; if neither exists, scan supported source files recursively under reference/.
2. Read references/library-policy.md.
3. Run the scanner when indexing is needed:

python3 <installed-skill-dir>/scripts/scan_reference_library.py --project-root .

1. Review generated or updated files:

• reference/.agent/source-index.md
• reference/.agent/reference-index.md
• reference/.agent/processing-status.md
• reference/.agent/reading-status.md
• reference/.agent/metadata-gaps.md
• reference/.agent/duplicate-check.md

1. Mark each source's intended role when known:

• idea-seed
• writing-exemplar
• method-source
• theory-source
• benchmark-source
• implementation-source
• collaborator-feedback
• project-spec
• baseline
• citation-support
• closest-work
• reviewer-risk

1. Route next action:

• unread but important -> reference-reading-summarizer
• card exists and project decisions are needed -> reference-project-synthesizer
• missing citation coverage in a draft -> citation-coverage-audit
• broad field search -> literature-review-sprint

Output Rules

• Store raw scanner trajectories under reference/.agent/runs/ only when useful.
• Store durable index state under reference/.agent/.
• Store stable summaries as source cards under reference/cards/.
• Never paste long raw source text into memory or public docs.
• Report only counts, major gaps, duplicates, and recommended next sources unless the user asks for detail.
• Memory writeback: update reference/.agent/processing-status.md when sources are added, deduplicated, or change status. Project-level memory writeback (claim/evidence/risk boards) is handled by reference-project-synthesizer after synthesis, not by this skill.