librarian

Files (1)

• SKILL.md

SKILL.md (first lines)

# Librarian

Answer questions about open-source libraries by finding evidence with GitHub permalinks. Every claim backed by actual code.

## Execution Model

Pi executes tool calls sequentially, even when you emit multiple calls in one turn. But batching independent calls in a single turn still saves LLM round-trips (~5-10s each). Use these patterns:

| Pattern | When | Actually parallel? |
|---------|------|-------------------|
| Batch tool calls in one turn | Independent ops (web_search + fetch_content + read) | No, but saves round-trips |
| `fetch_content({ urls: [...] })` | Multiple URLs to fetch | Yes (3 concurrent) |
| Bash with `&` + `wait` | Multiple git/gh commands | Yes (OS-level) |

## Step 1: Classify the Request

Before doing anything, classify the request to pick the right research strategy.

| Type | Trigger | Primary Approach |
|------|---------|-----------------|
| **Conceptual** | "How do I use X?", "Best practice for Y?" | web_search + fetch_content (README/docs) |
| **Implementation** | "How does X implement Y?", "Show me the source" | fetch_content (clone) + code search |
| **Context/History** | "Why was this changed?", "History of X?" | git log + git blame + issue/PR search |
| **Comprehensive** | Complex or ambiguous requests, "deep dive" | All of the above |

## Step 2: Research by Type

### Conceptual Questions

Batch these in one turn:

1. **web_search**: `"library-name topic"` via Perplexity for recent articles and discussions
2. **fetch_content**: the library's GitHub repo URL to clone and check README, docs, or examples

Synthesize web results + repo docs. Cite official documentation and link to relevant source files.

### Implementation Questions

The core workflow -- clone, find, permalink:

1. **fetch_content** the GitHub repo URL -- this clones it locally and returns the file tree
2. Use **bash** to search the cloned repo: `grep -rn "function_name"`, `find . -name "*.ts"`
3. Use **read** to examine specific files once you've located them
4. Get the commit SHA: `cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD`
5. Construct permalink: `https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20`

Batch the initial calls: fetch_content (clone) + web_search (recent discussions) in one turn. Then dig into the clone with grep/read once it's available.

### Context/History Questions

Use git operations on the cloned repo:

```bash
cd /tmp/pi-github-repos/owner/repo

# Recent changes to a specific file
git log --oneline -n 20 -- path/to/file.ts

# Who changed what and when
git blame -L 10,30 path/to/file.ts

# Full diff for a specific commit
git show <sha> -- path/to/file.ts

# Search commit messages
git log --oneline --grep="keyword" -n 10
```

For issues and PRs, use bash:

```bash
# Search issues
gh search issues "keyword" --repo owner/repo --state all --limit 10

# Search merged PRs
gh search prs "keyword" --repo owner/repo --state merged --limit 10

# View specific issue/PR with comments
gh issue view <number> --repo owner/repo --comments
gh pr view <number> --repo owner/repo --comments

# Release notes
gh api repos/owner/repo/releases --jq '.[0:5] | .[].tag_name'
```

### Comprehensive Research

Combine everything. Batch these in one turn:

1. **web_search**: recent articles and discussions
2. **fetch_content**: clone the repo (or multiple repos if comparing)
3. **bash**: `gh search issues "keyword" --repo owner/repo --limit 10 & gh search prs "keyword" --repo owner/repo --state merged --limit 10 & wait`

Then dig into the clone with grep, read, git blame, git log as needed.

## Step 3: Construct Permalinks

Permalinks are the whole point. They make your answers citable and verifiable.

```
https://github.com/<owner>/<repo>/blob/<commit-sha>/<filepath>#L<start>-L<end>
```

Getting the SHA from a cloned repo:

```bash
cd /tmp/pi-github-repos/owner/repo && git rev-parse HEAD
```

Getting the SHA from a tag:

```bash
gh api repos/owner/repo/git/refs/tags/v1.0.0 --jq '.object.sha'
```

Always use full commit SHAs, not branch names. Branch links break when code changes. Permalinks don't.

## Step 4: Cite Everything

From exoad/bibo-agent, Apache-2.0.

More from exoad/bibo-agent