The Cartographer

The Cartographer

Ask which agent skills fit a task before you start it.

For people whose agent has more skills than it can keep in mind. Agents that use skills (SKILL.md folders, as in Claude Code and Codex) get worse as the pile grows: either every description sits in the context on every turn, or the agent guesses from names and opens the wrong ones. The Cartographer is one model call instead. It maps a short brief of the task against your whole skill library and points to the few skills worth reading first. "None" is a valid answer.

Your own skills are the point: it reads the skill folders you already have. The 193 bundled skills are a starter library.

Try it (needs uv, plus a Claude Code or Codex login; with a Claude API key instead, run uvx --from "the-cartographer[api]" the-cartographer ask "..."):

uvx the-cartographer ask "Add property-based tests for our Python date-parsing module"

In Claude Code 2.1.275 or later, the plugin asks it for you at the start of each task (needs uv): /plugin install the-cartographer --marketplace sheepk95/The-Cartographer. Other installs: Quick start.

A real answer

$ cartographer ask "Add property-based tests for our Python date-parsing module, and check the existing tests actually catch bugs."

PICKS:

• trailofbits/property-based-testing | .../skills/trailofbits/property-based-testing/SKILL.md | Hypothesis property tests for parsers, round-trips (parse/format) in Python | read: whole
• dotnet/test-gap-analysis | .../skills/dotnet/test-gap-analysis/SKILL.md | Polyglot check of whether existing tests would catch caller-visible bugs via pseudo-mutation | read: whole

MAYBE:

• trailofbits/mutation-testing | .../skills/trailofbits/mutation-testing/SKILL.md | Real mutation campaigns (mewt/muton) if actual mutant tooling is wanted, though those tools may not support Python | read: whole

ALSO GREP: python mutmut hypothesis NOTE: No Python-specific mutation tool skill in catalogue; test-gap-analysis covers the "do tests catch bugs" part by manual pseudo-mutation. --- end of cartographer answer ---

That is a real run: Claude Code backend, Sonnet, 8.4 seconds, the 193-skill bundled catalogue (paths shortened here). The second pick comes from a .NET skill set but is written for any language, and the NOTE says plainly what the catalogue lacks. The animation above is a separate real run of the same task with Haiku, which picked a different second skill: answers vary a little by model.

When the catalogue lacks something, cartographer find looks for it on skills.sh, and cartographer install checks a find's licence and files before it goes into your skills folder (details).

How it works

flowchart LR

A["Agent starts a task"] -->|"2-10 line brief"| Q["cartographer ask or the ask_cartographer MCP tool"] S[("Bundled skills

• your skill folders")] --> C["Catalogue text

sorted, no dates, cacheable"] C --> M{{"One model call anthropic / claude / codex / command"}} Q --> M M --> K["Check every name and path against the catalogue"] K --> R["PICKS / MAYBE / ALSO GREP / NOTE"] R --> A2["Agent reads the picked SKILL.md files"] M -.->|"no backend, timeout, bad answer"| U["exit 3: CARTOGRAPHER_UNAVAILABLE fall back to cartographer search"]

• The model sees every skill. No embedding or keyword shortlist decides what it gets to consider. It judges fit by what the task needs, not by shared words.
• Precision first. The prompt asks for as few picks as do the job, sends doubtful fits to MAYBE, and treats PICKS: none as a good answer. Agents open every skill they are given, so a wrong pick costs real context.
• Checked output. Every name in the answer is matched to the catalogue before it is printed. Wrong paths are corrected and invented names are dropped with a NOTE. If every pick is invented, the answer exits 3 rather than printing PICKS: none.
• Cheap on repeat. The catalogue text is deterministic, so with the anthropic backend it sits in a 1-hour prompt cache: repeat asks read it at the cached-input price and pay full price only for the brief and the answer.
• Never blocking. A backend failure, timeout or malformed answer exits 3 with one line, CARTOGRAPHER_UNAVAILABLE (reason), and the agent falls back to offline keyword search.
• Isolated. The model gets no tools, and the CLI backends run with your hooks, skills and MCP servers switched off, so an "always ask the cartographer" rule cannot call itself.
• Bring your own model. Claude API key, Claude Code login, Codex CLI, or any command that reads stdin.
• 193 bundled skills, copied unchanged from their upstream repositories at pinned commits, each with its licence. Your own skill folders are added automatically.
• Finds what you lack. cartographer find searches skills.sh politely and without a model; cartographer install vets a find (licence, files, provenance) and never runs it.

Quick start

Needs Python 3.9+ and one way to reach a model: a Claude API key, Claude Code, Codex, or a local command. Install it one of these ways (the bundled skills come with the package):

pipx install the-cartographer          # or: uv tool install the-cartographer

pip install the-cartographer # into the current environment; with a Claude API key: pip install "the-cartographer[api]" uvx the-cartographer doctor # run it once without installing (uv); any command works: uvx the-cartographer ask "..."

Then:

cartographer doctor            # skills found, catalogue size, which backends are ready

cartographer ask "Build a Three.js scene with a rotating textured planet and bloom"

The command is cartographer; the-cartographer is the same command under the package's name, which is what uvx and pipx run look for.

From source, to edit the code or the skills in place:

git clone https://github.com/sheepk95/The-Cartographer

cd The-Cartographer pip install -e . # or pip install . for a regular install

cartographer doctor on a fresh clone with only the bundled skills prints something like:

the-cartographer 0.1.1

bundled home: /path/to/The-Cartographer skills: 193 (193 bundled, 0 local) catalogue: 101163 bytes, about 28k tokens, id 3726e799ee4a backend anthropic not ready: pip install anthropic backend claude ready backend codex ready backend command not ready: set CARTOGRAPHER_COMMAND default backend: claude installed by cartographer install: 0 finder cache: /home/you/.cache/the-cartographer/finder names list: none yet (the first cartographer find builds it from robots.txt and the sitemaps: about 4 requests) skill pages cached: 0 (0 KB)

To look for skills you do not have yet (see Find skills you don't have):

cartographer find "Add property-based tests for our Python date parser and fuzz it for crashes"

cartographer install https://www.skills.sh/ / / # shows the licence and files, then asks

No model handy? These commands work offline:

cartographer search react performance      # keyword search over names and descriptions

cartographer list --origin local # only your own skills cartographer show obra/systematic-debugging cartographer catalogue # the exact text the model reads

Backends: bring your own model

Which backend runs: --backend if given, else command if you passed --command, else CARTOGRAPHER_BACKEND, else the first ready one in the table's order. Flags also beat environment variables for --model and --effort. The model only ever sees the cartographer's own prompt: the CLI backends run with customisations, tools and MCP servers switched off (claude --safe-mode --tools ""; codex exec --ignore-user-config -s read-only with the shell tool disabled).

Defaults: API model claude-opus-5-5 at effort medium (with server-side refusal fallbacks on). The CLI backends use your CLI's default model unless you pass --model (for example --model sonnet with Claude Code). --effort takes low to max, or none to send no effort setting.

For the command backend, the model needs a context window comfortably above the catalogue size (about 30k tokens with the bundled skills; check yours with cartographer doctor).

Connect your agent

Claude Code: the plugin (MCP server and an "ask the cartographer first" skill in one step; needs uv)

/plugin marketplace add sheepk95/The-Cartographer

/plugin install the-cartographer@the-cartographer

On Claude Code 2.1.275 or later, one line does both: /plugin install the-cartographer --marketplace sheepk95/The-Cartographer. The plugin runs the server from its own copy of this repository with uvx --from ${CLAUDE_PLUGIN_ROOT} cartographer mcp, so it needs no separate install; the first start builds it once (about 15 seconds), later starts take under a second. Its skill tells the agent to call ask_cartographer at the start of each non-trivial task.

Claude Code: the MCP server only

claude mcp add the-cartographer -- uvx the-cartographer mcp      # or, after pipx/pip install: -- cartographer mcp

(or put integrations/claude-code/mcp.json in a project as .mcp.json). Then either copy integrations/claude-code/ask-the-cartographer/ into ~/.claude/skills/, or paste integrations/claude-code/CLAUDE.md-snippet.md into your CLAUDE.md, so the agent asks at the start of each task.

Codex

codex mcp add the-cartographer -- uvx the-cartographer mcp      # or, after pipx/pip install: -- cartographer mcp

or add this to ~/.codex/config.toml (the same as integrations/codex/config.toml):

[mcp_servers.the-cartographer]

command = "uvx" args = ["the-cartographer", "mcp"] startup_timeout_sec = 60 # the first uvx start downloads the package tool_timeout_sec = 600 # headroom for normal default attempts and process cleanup

Then add [integrations/codex/AGENTS.md-snippet.md](https://github.com/sheepk95/The-Cartographer/blob/main/integrations/co