| name | shelf |
| description | Access code reference repositories managed by shelf. Repos are cached at ~/.agents/shelf/repos/{alias}/ and kept in sync. Use your native tools (Grep, Read, Glob) to explore them.
ALWAYS consult this skill before searching for code references, looking up how a library or framework works, grepping for implementations, reading source code from a reference repo, checking API signatures, finding usage examples in real codebases, or exploring how a dependency is structured.
Trigger this skill whenever the user mentions code references, reference repos, shelf, grepping a codebase, reading library source, "how does X implement Y", "find examples of Z in the codebase", looking up types or interfaces, checking an upstream project's code, comparing implementations, or any task that benefits from consulting real source code in a cached repository — even if the user doesn't mention "shelf" by name.
If the user asks you to look something up in a codebase, check an implementation, or find how something works in a library, this is the skill to use.
Do NOT use for the user's own project code (use normal file tools for that), web searches, documentation lookups on the internet, or package registry queries.
|
Shelf — Code Reference Repos
Shelf maintains a local cache of code reference repositories at
~/.agents/shelf/repos/{alias}/. These repos let you answer questions about
library internals, API surfaces, implementation patterns, and real-world
usage — without searching the web or relying on training data that may be stale.
Why this matters: cached reference repos are faster and more reliable than
web search for code questions. The code is local, complete, and version-pinned,
so you can grep, read, and explore freely. Whenever a task involves
understanding how a dependency, framework, or upstream project works, check
shelf first.
Quick Start
- Run
shelf list to see which repos are available and their local paths.
- Use your native tools on those paths:
- Search:
Grep or rg on ~/.agents/shelf/repos/{alias}/
- Read files:
Read on any file in the repo
- Find files:
Glob with patterns like ~/.agents/shelf/repos/{alias}/**/*.ts
- Explore structure:
ls ~/.agents/shelf/repos/{alias}/src/
Workflow
When the user asks about code in a reference repository:
- Discover — Run
shelf list to see available repos and their aliases. If the needed repo isn't there, ask the user if they'd like to add it with shelf add.
- Search — Use
rg (ripgrep) or Grep to find relevant code. Start broad (e.g., search for a function name, type name, or keyword), then narrow down.
- Read — Open the relevant files and read the specific sections that answer the question.
- Synthesize — Explain what you found, referencing file paths and line numbers so the user can verify.
Management Commands
| Command | Purpose |
|---|
shelf list | Show repos with local paths |
shelf update [alias] | Sync one or all repos |
shelf add <repo> [--alias name] [--pin ref] | Add a repo (accepts name, owner/repo, or URL) |
shelf remove <alias> | Remove a repo |
shelf detect [--apply] | Detect repos from project dependencies |
shelf install [--dir path] | Install repos from a shelffile |
shelf share [--filter aliases] [--stdout] | Generate a shelffile from current repos |
shelf prune [--dry-run] [--force] | Remove unreferenced repos |
shelf status | Show detailed status of all repos |
shelf info <alias> | Show detailed info for a single repo |
shelf pin <alias> <ref> | Pin a repo to a branch, tag, or commit |
shelf alias <old> <new> | Rename a repo alias |
shelf daemon start | Start background sync daemon |
shelf daemon stop | Stop the daemon |
shelf daemon status | Show daemon status |
Adding Repos
You can add repos by name — no full URL required:
shelf add react # resolves from built-in registry
shelf add Effect-TS/effect # resolves owner/repo to GitHub
shelf add https://github.com/org/repo.git # full URL
Shelffile
A shelffile is a per-project manifest declaring which reference repos the project needs:
# one repo per line: alias url [pin:type:value]
effect https://github.com/Effect-TS/effect.git pin:branch:main
react https://github.com/facebook/react.git pin:tag:v19.0.0
Run shelf install in a project directory to clone all repos from its shelffile. Run shelf share to generate a shelffile from your current repos. Run shelf detect --format shelffile to auto-generate from project dependencies.
Tips
- Pin versions for reproducibility. If the user's project depends on React 19, pin the reference repo to
v19.0.0 so the code you read matches what they're actually using.
- Update before deep dives. If you're about to do extensive research in a repo, run
shelf update {alias} first to make sure you're reading the latest code (unless pinned).
- Combine with project code. You can cross-reference between the user's project files and shelf repos to trace how dependencies are used — e.g., find a function signature in the shelf repo, then grep the user's project for call sites.
