librarian

name

librarian

description

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.

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

Send an auth token on every request:

Authorization: Bearer <token>

Use the environment variable LIBRARIAN_API_KEY. If it is not set, use test123 for now:

export LIBRARIAN_API_KEY="test123"

The service currently accepts any token, but callers should already use the bearer-token contract so future auth can be enabled without changing clients.

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.

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:

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

The script reads LIBRARIAN_API_KEY and falls back to test123.

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:

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

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

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:

Content-Type: application/json
Authorization: Bearer ${LIBRARIAN_API_KEY:-test123}

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