librarian · mitsuhiko — Claude Code skill: cache Git repos, install
librarian caches remote Git repositories locally and refreshes them when referenced again. Useful when an agent needs to inspect external source code.
Apache-2.0 170 installs ★ 3,224 updated 2026-09-27
npx skills add mitsuhiko/agent-stuff --skill librarian -a claude-codeWhat librarian does
This skill accepts remote repository references such as owner/repo, GitHub, GitLab, and Bitbucket URLs, or git@... addresses. It resolves each reference to ~/.cache/checkouts/<host>/<org>/<repo>, giving the agent a stable local checkout for later searches and reading.
The workflow runs through checkout.sh. A missing repository is cloned with --filter=blob:none; an existing checkout is reused and refreshed from origin after 300 seconds. Add --force-update when an immediate refresh is required.
Keep edits out of the shared cache by using a separate worktree or copy. A dirty checkout cannot be fast-forwarded, so local uncommitted changes affect whether the refresh succeeds.
What it helps with
- cache a remote Git repository
- resolve a repository reference to a local path
- refresh an existing checkout from
origin - reuse a local copy for code analysis
Example prompts for the agent
- Inspect
mitsuhiko/minijinjaand use its local checkout to search the source. - Resolve
https://github.com/mitsuhiko/minijinja, then read the files from the cached path. - Force-refresh
github.com/mitsuhiko/minijinjabefore analysing the repository.
How to install librarian
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill librarian -a claude-code2Manually: put the files in place
~/.claude/skills/librarian/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/librarian/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill librarian -a codex2Manually: put the files in place
.agents/skills/librarian/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill librarian -a cursor2Manually: put the files in place
.cursor/skills/librarian/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install mitsuhiko/agent-stuff skills/librarian2Manually: put the files in place
.github/skills/librarian/SKILL.md1Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill librarian -a gemini-cli2Platform CLI
gemini skills install https://github.com/mitsuhiko/agent-stuff --path skills/librarianManually: put the files in place
.devin/skills/librarian/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add mitsuhiko/agent-stuff --skill librarian -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about librarian
How do I install librarian in Claude Code?
Run npx skills add mitsuhiko/agent-stuff --skill librarian -a claude-code, then use ~/.claude/skills/librarian/SKILL.md.
What does librarian do?
It clones remote Git repositories into ~/.cache/checkouts/<host>/<org>/<repo> and reuses those checkouts later. Stale copies are refreshed from origin.
How can I force a repository refresh?
Run bash checkout.sh <repo> --force-update --path-only. Regular refreshes use a 300-second interval.
Source text
SKILL.md · Apache-2.0
--- name: librarian description: "Cache and refresh remote git repositories under ~/.cache/checkouts/<host>/<org>/<repo> so future references can reuse a local copy. Use this skill when the user points you to a remote git repository as reference or you encountered a remote git repo through other means." --- Use this skill when the user points you to a remote git repository (GitHub/GitLab/Bitbucket URLs, `git@...`, or `owner/repo` shorthand). The goal is to keep a reusable local checkout that is: - **stable** (predictable path) - **up to date** (periodic fetch + fast-forward when safe) - **efficient** (partial clone with `--filter=blob:none`, no repeated full clones) ## Cache location Repositories are stored at: `~/.cache/checkouts/<host>/<org>/<repo>` Example: `github.com/mitsuhiko/minijinja` → `~/.cache/checkouts/github.com/mitsuhiko/minijinja` ## Command ```bash bash checkout.sh <repo> --path-only ``` Examples: ```bash bash checkout.sh mitsuhiko/minijinja --path-only bash checkout.sh github.com/mitsuhiko/minijinja --path-only bash checkout.sh https://github.com/mitsuhiko/minijinja --path-only ``` The script will: 1. Parse the repo reference into host/org/repo. 2. Clone if missing. 3. Reuse existing checkout if present. 4. Fetch from `origin` when stale (default interval: 300s). 5. Attempt a fast-forward merge if the checkout is clean and has an upstream. ## Update strategy - Default behavior is **throttled refresh** (every 5 minutes) to avoid unnecessary network calls. - Force immediate refresh with: ```bash bash checkout.sh <repo> --force-update --path-only ``` ## Recommended workflow 1. Resolve repository path via `checkout.sh --path-only`. 2. Use that path for searching, reading, and analysis. 3. On later references to the same repo, call `checkout.sh` again; it will find and update the cached checkout. ## If edits are needed Prefer not to edit directly in the shared cache. Create a separate worktree or copy from the cached checkout for task-specific modifications. ## Notes - `owner/repo` defaults to `github.com`.
© mitsuhiko · Apache-2.0 · mitsuhiko/agent-stuff
Similar skills
SKILL.md skills catalog →librarian by other authors comes first.