# Librarian

> Access the public Librarian research service for source-backed answers about GitHub repositories and public web pages. Use this skill whenever the user asks you to research a GitHub repo, inspect public source files, search commit history, compare repository diffs, read public docs/pages, or answer questions that need concise citations from repo/web evidence. This is especially useful when you do not have direct network access, when you want a dedicated research subagent, or when the user mentions Librarian.

- Skill: `pc-style/librarian` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add pc-style/librarian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pc-style/librarian/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: pc-style (https://skillmd.com/u/pc-style)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pc-style/librarian

---


# Librarian

Use the hosted Librarian service to get fast, source-backed findings about GitHub repositories and public web pages.

Service domain: `https://librarian.pcstyle.dev`

Librarian is modeled after Amp's `librarian` subagent: a constrained research worker with no local shell, filesystem, or secret access. In Amp, callers invoke `librarian({ query: string })`; this eve service accepts the same research task as the session `message` field.

The reverse-engineered Amp client exposes the Librarian tool names and client-side activity metadata, but not the server-side Librarian prompt text. Treat this service as a behavior-compatible research worker, not as a verbatim copy of Amp's private prompt.

## Research tools

The service exposes the same GitHub and web tool surface Amp's Librarian uses internally:

- GitHub: `read_github`, `search_github`, `commit_search`, `list_directory_github`, `list_repositories`, `glob_github`, `diff`
- Web: `web_search`, `read_web_page`

Librarian runs those tools silently and returns a concise, source-backed answer with citations.

## Authentication

Production requests require a valid, unexpired Vercel OIDC token authorized for
the Librarian deployment's project and environment. Arbitrary bearer strings are
rejected. Send the token on every request:

```http
Authorization: Bearer <token>
```

Use `LIBRARIAN_AUTH_TOKEN`:

```bash
export LIBRARIAN_AUTH_TOKEN="<short-lived-vercel-oidc-token>"
```

`LIBRARIAN_API_KEY` remains a deprecated alias in the script, but it must contain
the same valid OIDC token. The script fails closed when neither variable is set.

## Quick usage

Prefer the bundled script when shell access is available. Librarian performs live repo/web research, so the command may run for **5+ minutes** on broad or tool-heavy questions. Use a generous command timeout and do not assume it is stuck just because it is quiet while the remote agent works.

```bash
skills/librarian/scripts/ask-librarian.mjs "In the GitHub repo vercel/ai, where is createOpenAICompatible documented or implemented? Summarize with source paths."
```

Or from inside this skill directory:

```bash
./scripts/ask-librarian.mjs "What is Amp's TypeScript SDK for? Use https://ampcode.com/manual/sdk/typescript"
```

The script reads `LIBRARIAN_AUTH_TOKEN` (or the deprecated
`LIBRARIAN_API_KEY` alias) and fails when no token is configured.

## When to use Librarian

Use Librarian for:

- Questions about public GitHub repositories: files, directories, symbols, docs, package setup, examples, tests, commits, and diffs.
- Public web research where the answer should cite pages or docs.
- Repo-plus-web questions, such as whether a public SDK can plausibly integrate into a public project.
- Requests where a user wants a direct answer with evidence, not a browsing transcript.

Do not use Librarian for:

- Local filesystem inspection. Librarian cannot see your local checkout.
- Secret or environment-variable inspection.
- Private GitHub data unless the deployed service has been configured with an authorized connector for that user/session.
- Tasks that require making changes to a repository; Librarian researches and answers.

## How to ask good questions

Include exact identifiers when possible:

- GitHub repo: `owner/repo` or a GitHub repository URL.
- File paths, symbols, package names, error strings, branch/ref names, or docs URLs.
- The answer shape you want: “summarize with source paths,” “return concise evidence,” “compare these two refs,” etc.

Good examples:

```text
In the GitHub repo charmbracelet/skate, what is the project and where are the CLI entrypoint or main command files? Give source-backed paths.
```

```text
What is Amp's TypeScript SDK for, and what are the main integration surfaces? Use these sources: https://ampcode.com/manual/sdk/typescript https://ampcode.com/manual/sdk https://ampcode.com/news/typescript-sdk
```

```text
In vercel/next.js, what files at the repository root indicate package manager and TypeScript setup? Return concise evidence.
```

## API contract

The script uses eve's HTTP session API. Map Amp's `librarian({ query })` call to `{ "message": "<query>" }`:

1. `POST /eve/v1/session` with JSON `{ "message": "..." }`.
2. Read `sessionId` from the response.
3. `GET /eve/v1/session/:sessionId/stream` and collect `message.completed` events.

Set these headers:

```http
Content-Type: application/json
Authorization: Bearer ${LIBRARIAN_AUTH_TOKEN}
```

If implementing your own client, stream events are newline-delimited JSON. Return the last completed assistant message as Librarian's answer.