| name | librarian |
| description | Multi-repository codebase exploration. Research library internals, find code patterns, understand architecture, compare implementations across GitHub/npm/PyPI/crates. Use when needing deep understanding of how libraries work, finding implementations across open source, or exploring remote repository structure. |
| references | ["references/tool-routing.md","references/opensrc-api.md","references/opensrc-examples.md","references/linking.md","references/diagrams.md"] |
Librarian Skill
Deep codebase exploration across remote repositories.
How to Use This Skill
Reference Structure
| File | Purpose | When to Read |
|---|
tool-routing.md | Tool selection decision trees | Always read first |
opensrc-api.md | API reference, types | Writing opensrc code |
opensrc-examples.md | JavaScript patterns, workflows | Implementation examples |
linking.md | GitHub URL patterns | Formatting responses |
diagrams.md | Mermaid patterns | Visualizing architecture |
Reading Order
- Start with
tool-routing.md → choose tool strategy
- If using opensrc:
- Read
opensrc-api.md for API details
- Read
opensrc-examples.md for patterns
- Before responding:
linking.md + diagrams.md for output formatting
Tool Arsenal
| Tool | Best For | Limitations |
|---|
| grep_app | Find patterns across ALL public GitHub | Literal search only |
| opensrc | Fetch full source for deep exploration | Must fetch before read |
| WebFetch | Official docs, API references, usage guides | External to source |
Quick Decision Trees
"How does X work?"
Known library?
├─ Yes → Has official docs site?
│ ├─ Yes → WebFetch (target official domain)
│ └─ No → opensrc.fetch → read README + source
│ └─ Need internals? → opensrc.fetch → read source
└─ No → grep_app search → opensrc.fetch top result
"Find pattern X"
Specific repo?
├─ Yes → opensrc.fetch → opensrc.grep → read matches
└─ No → grep_app (broad) → opensrc.fetch interesting repos
"Explore repo structure"
1. opensrc.fetch(target)
2. opensrc.tree(source.name) → quick overview
3. opensrc.files(source.name, "**/*.ts") → detailed listing
4. Read: README, package.json, src/index.*
5. Create architecture diagram (see diagrams.md)
"Compare X vs Y"
1. opensrc.fetch(["X", "Y"])
2. Use source.name from results for subsequent calls
3. opensrc.grep(pattern, { sources: [nameX, nameY] })
4. Read comparable files, synthesize differences
Critical: Source Naming Convention
After fetching, always use source.name for subsequent calls:
const [{ source }] = await opensrc.fetch("vercel/ai");
const files = await opensrc.files(source.name, "**/*.ts");
| Type | Fetch Spec | Source Name |
|---|
| npm | "zod" | "zod" |
| npm scoped | "@tanstack/react-query" | "@tanstack/react-query" |
| pypi | "pypi:requests" | "requests" |
| crates | "crates:serde" | "serde" |
| GitHub | "vercel/ai" | "github.com/vercel/ai" |
| GitLab | "gitlab:org/repo" | "gitlab.com/org/repo" |
WebFetch Best Practices
Target official sources first:
- Search:
"[library] official documentation site:[domain]" (e.g., zod site:zod.dev)
- Known domains:
docs.rs (Rust), pkg.go.dev (Go), docs.python.org, npmjs.com
- Prefer: GitHub README → official docs → blog posts
Skip WebFetch when:
- Library is obscure/undocumented → go straight to
opensrc.fetch
- Question is about internals → source code is authoritative
- You already know the repo →
opensrc directly
Fallback chain:
WebFetch fails/irrelevant?
├─ Try GitHub README: opensrc.fetch → read README.md
└─ Search source: opensrc.grep for patterns
When NOT to Use opensrc
| Scenario | Use Instead |
|---|
| Simple library API questions | WebFetch |
| Finding examples across many repos | grep_app |
| Very large monorepos (>10GB) | Clone locally |
| Private repositories | Direct access |
Output Guidelines
- Comprehensive final message - only last message returns to main agent
- Parallel tool calls - maximize efficiency
- Link every file reference - see
linking.md
- Diagram complex relationships - see
diagrams.md
- Never mention tool names - say "I'll search" not "I'll use opensrc"
References
