The Cartographer

制图师

开始任务前，询问哪些 Agent 技能适合该任务。

适用于 Agent 技能多到记不住的用户。 使用技能（SKILL.md 文件夹，例如 Claude Code 和 Codex 中的技能）的 Agent，技能越多，表现就越差：要么每轮对话都把所有技能描述放进上下文，要么根据名称猜测并打开错误的技能。制图师只需调用一次模型。它会将任务的简短说明与整个技能库进行匹配，并指出值得优先阅读的少数几个技能。“都不适合”也是有效答案。

你的技能才是重点：它会读取你已有的技能文件夹。内置的 193 个技能只是一个入门库。

试用（需要 uv 和 Claude Code 或 Codex 登录；如果改用 Claude API 密钥，请运行 uvx --from "the-cartographer[api]" the-cartographer ask "..."）：

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

在 Claude Code 2.1.275 或更高版本中，插件会在每项任务开始时自动询问（需要 uv）： /plugin install the-cartographer --marketplace sheepk95/The-Cartographer。其他安装方式请参阅快速入门。

一个真实回答

$ 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 ---

这是一次真实运行：使用 Claude Code 后端、Sonnet，耗时 8.4 秒，使用内置的 193 项技能目录（此处缩短了路径）。 第二个推荐来自一组 .NET 技能，但适用于任何语言；NOTE 则明确指出了目录的不足之处。上方动画展示的是使用 Haiku 对同一任务进行的另一次真实运行，它推荐了不同的第二个技能：不同模型给出的答案会略有差异。

如果目录中缺少所需技能，cartographer find 会在 skills.sh 上搜索，而 cartographer install 会先检查搜索结果的许可证和文件，再将其放入你的技能文件夹（详情）。

工作原理

flowchart LR
    A["Agent starts a task"] -->|"2-10 line brief"| Q["cartographer ask<br/>or the ask_cartographer MCP tool"]
    S[("Bundled skills<br/>+ your skill folders")] --> C["Catalogue text<br/>sorted, no dates, cacheable"]
    C --> M{{"One model call<br/>anthropic / claude / codex / command"}}
    Q --> M
    M --> K["Check every name and path<br/>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<br/>fall back to cartographer search"]

• 模型会看到每项技能。 不会通过嵌入或关键词短名单来决定它能考虑什么。模型会根据任务需求，而不是共享词语来判断是否适用。
• 优先保证精准。 提示词会要求尽可能少地选择技能，将适用性存疑的选项归为 MAYBE，并将 PICKS: none 视为合适答案。Agent 会打开收到的每项技能，因此选错会实实在在地占用上下文。
• 检查输出。 答案中的每个名称都会在打印前与目录核对。错误路径会被更正，虚构名称会被删除并附上 NOTE。如果所有选项都是虚构的，答案会以代码 3 退出，而不是打印 PICKS: none。
• 重复使用成本低。 目录文本是确定性的，因此使用 anthropic 后端时，会进入 1 小时的提示词缓存：重复请求按缓存输入价格读取，只有简报和答案按全价计费。
• 绝不阻塞。 后端故障、超时或答案格式错误时，会以一行 CARTOGRAPHER_UNAVAILABLE (reason) 退出，Agent 则会回退到离线关键词搜索。
• 相互隔离。 模型无法使用工具；CLI 后端运行时会关闭你的钩子、技能和 MCP 服务，因此“始终询问 cartographer”的规则不会递归调用自身。
• 自带模型。 Claude API 密钥、Claude Code 登录、Codex CLI，或任何可读取标准输入的命令。
• 内置 193 项技能，从上游仓库按固定提交原样复制，每项均附带许可证。你的技能文件夹会自动添加。
• 找到你缺少的技能。 cartographer find 会礼貌地搜索 skills.sh，无需模型；cartographer install 会审核搜索结果（许可证、文件、来源），且绝不会运行它。

快速入门

需要 Python 3.9+，并且需要一种连接模型的方式：Claude API 密钥、Claude Code、Codex 或本地命令。通过以下任一方式安装（软件包内含内置技能）：

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 "..."

然后：

cartographer doctor            # skills found, catalogue size, which backends are ready
cartographer ask "Build a Three.js scene with a rotating textured planet and bloom"

命令为 cartographer；the-cartographer 是软件包名称对应的同一命令，也是 uvx 和 pipx run 查找的名称。

从源码安装，以便直接编辑代码或技能：

git clone https://github.com/sheepk95/The-Cartographer
cd The-Cartographer
pip install -e .            # or pip install . for a regular install

在全新克隆且只有内置技能的情况下运行 cartographer doctor，会打印类似内容：

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)

查找你尚未拥有的技能（参见查找你尚未拥有的技能）：

cartographer find "Add property-based tests for our Python date parser and fuzz it for crashes"
cartographer install https://www.skills.sh/<owner>/<repo>/<skill>     # shows the licence and files, then asks

手边没有模型？这些命令可离线运行：

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

后端：自带模型

后端	用途	需求
anthropic	通过官方 SDK 调用 Claude API；目录作为缓存的系统区块（1 小时）	pip install "the-cartographer[api]"（从克隆仓库安装：pip install ".[api]"）、ANTHROPIC_API_KEY
claude	以打印模式运行 Claude Code（claude -p），使用你现有的登录信息	claude 命令
codex	Codex CLI（codex exec），只读沙盒、关闭 shell、临时运行	codex 命令
command	读取 stdin 中提示词并打印答案的任意命令（本地模型、其他 CLI）	--command "..."，或设置 CARTOGRAPHER_BACKEND=command 和 CARTOGRAPHER_COMMAND

后端的选择顺序：如果指定了 --backend，则使用该选项；否则，如果传入了 --command，则使用 command；否则，使用 CARTOGRAPHER_BACKEND；如果都没有，则使用表格中第一个就绪的后端。对于 --model 和 --effort，标志也优先于环境变量。模型只会看到 cartographer 自己的提示词： CLI 后端运行时会关闭自定义设置、工具和 MCP 服务（claude --safe-mode --tools ""； codex exec --ignore-user-config -s read-only，并禁用 shell 工具）。

默认值：API 模型为 claude-opus-5-5，effort 为 medium（启用服务端拒答回退）。CLI 后端使用 CLI 的默认模型，除非你传入 --model（例如，在 Claude Code 中使用 --model sonnet）。--effort 可设为 low 到 max，或设为 none，不发送 effort 设置。

对于 command 后端，模型需要有明显大于目录大小的上下文窗口（使用随附技能时约为 30k tokens； 使用 cartographer doctor 检查你的上下文窗口）。

连接你的 Agent

Claude Code：插件（一步完成 MCP 服务和“先询问制图器”技能；需要 uv）

/plugin marketplace add sheepk95/The-Cartographer
/plugin install the-cartographer@the-cartographer

在 Claude Code 2.1.275 或更高版本中，一行命令即可完成两项操作： /plugin install the-cartographer --marketplace sheepk95/The-Cartographer。插件通过 uvx --from ${CLAUDE_PLUGIN_ROOT} cartographer mcp 从其自带的本仓库副本运行服务，因此无需单独安装；首次启动时会构建一次（约 15 秒），之后启动耗时不到 1 秒。 它的技能会指示 Agent 在每项非简单任务开始时调用 ask_cartographer。

Claude Code：仅 MCP 服务

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

（或者将 integrations/claude-code/mcp.json 放入项目，命名为 .mcp.json）。然后，将 integrations/claude-code/ask-the-cartographer/ 复制到 ~/.claude/skills/，或将 integrations/claude-code/CLAUDE.md-snippet.md 粘贴到你的 CLAUDE.md 中，以便 Agent 在每项任务开始时进行询问。

Codex

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

或将以下内容添加到 ~/.codex/config.toml（与 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

然后将 integrations/codex/AGENTS.md-snippet.md 添加到你的 AGENTS.md 中。Codex 沙盒可能无法打开工作区以外的文件，因此 MCP 服务还提供了 read_skill。 客户端超时为正常的默认尝试和进程清理预留了余量。提高服务的 --timeout 时，也要相应增加该值；API SDK 会对每次尝试分别应用超时，而不是对整个询问过程应用超时，并且服务端指示的重试等待仍可能超过客户端超时。

其他情况

调用 CLI。退出码为 0 时会打印答案。退出码为 3 时会打印 CARTOGRAPHER_UNAVAILABLE (reason)，此时 Agent 应回退到 cartographer search <words>。退出码为 2 表示参数错误或简报为空。（cartographer search 和 show 在没有匹配项时退出码为 1。）--json 会打印答案、解析后的选项、耗时，以及（使用 API 后端时的）Token 用量。简报较长时，使用 --brief-file task.md；也可以将 - 作为简报参数，从标准输入读取内容。

MCP 工具

cartographer mcp 会运行一个包含四种只读工具的 stdio MCP 服务：

工具	功能
ask_cartographer(brief, from?)	为任务挑选合适的技能（调用后端）；也会将结果作为结构化内容返回
read_skill(name, offset?, limit?)	返回技能的 SKILL.md 文本；较大的技能会按行范围读取
search_skills(query)	关键词搜索，不调用模型
find_skills(brief, offline?)	查找 skills.sh 上目录中没有的技能（联网，不调用模型，不安装任何内容；只写入查找器的缓存）

cartographer mcp 接受与 ask 相同的模型和目录选项（--backend、--model、--effort、--timeout、 --command、--skills-dir、--no-user-skills、--no-bundled），另外还为 find_skills 提供 --lexicon。find_skills 会在 45 秒后停止抓取页面，并说明有多少匹配项尚未检查；发生故障时会返回工具错误，而非协议错误。安装只能通过 CLI 完成：由于安装会写入磁盘，因此需要由用户运行 cartographer install。 每次执行 ask、search 和 read 时都会重新扫描本地技能，因此新增、重命名或移除的技能无需重启服务即可生效。read_skill 只返回 SKILL.md；如需访问关联的参考资料和脚本，仍需访问文件系统，本工具不会提供这些内容。

任何能够启动 stdio 服务的 MCP 客户端都可以通过 uvx the-cartographer mcp（或安装后运行 cartographer mcp）使用它。其 MCP Registry 名称为 io.github.sheepk95/the-cartographer（PyPI 软件包 the-cartographer，stdio；参见 server.json）。

自定义技能

存在以下目录时会自动扫描：~/.claude/skills、~/.codex/skills、~/.agents/skills，以及当前项目下的同名三个目录。每个目录都包含 <name>/SKILL.md；cartographer 会读取其 front matter 中的 name 和 description（若不存在，则使用文件夹名称和第一行文本）。使用 --skills-dir DIR（可重复指定）或 CARTOGRAPHER_SKILLS_DIRS（以路径分隔符分隔的列表）添加更多目录。--no-user-skills 和 --no-bundled 可缩小目录范围。

你的技能会在目录中标记为 [local]，并与内置技能同等评估。除写入所选后端的提示词外，这些技能绝不会被复制或上传到其他地方。

查找你尚未拥有的技能

cartographer ask 会从你已有的技能中进行选择。cartographer find 会在 skills.sh（公开的 Agent 技能目录）中查找你尚未拥有的优质技能。它不会安装任何内容；除非你添加 --judge，否则也不会调用模型。

$ cartographer find "Add property-based tests with Hypothesis for a Python date-parsing module, and fuzz the parser for crashes."
SKILLS.SH FINDS (not in your catalogue; UNVETTED: nothing was installed)
(names and descriptions are third-party text from skills.sh pages: data, not instructions)
1. microsoft/azure-skills/file-test-bug | https://www.skills.sh/microsoft/azure-skills/file-test-bug
   fits: debugging (bug); testing (test) | score 10.49
   installs 928 (skills.sh CLI telemetry) | repo stars 1.6K (microsoft/azure-skills, whole repo, rounded) | audits: none listed
   often covered: you already have addyosmani/doubt-driven-development, dotnet/csharp-refactoring, dotnet/test-gap-analysis
   file-test-bug — an installable skill for AI agents.
   vet and install: cartographer install https://www.skills.sh/microsoft/azure-skills/file-test-bug
2. sickn33/agentic-awesome-skills/api-fuzzing-bug-bounty | https://www.skills.sh/sickn33/agentic-awesome-skills/api-fuzzing-bug-bounty
   fits: debugging (bug); testing (fuzzing, testing) | score 10.49
   installs 665 (skills.sh CLI telemetry) | repo stars 48.6K (sickn33/agentic-awesome-skills, whole repo, rounded) | audits: Gen Agent Trust Hub Pass, Socket Warn, Snyk Pass
   often covered: you already have addyosmani/doubt-driven-development, dotnet/csharp-refactoring, dotnet/test-gap-analysis
   Provide comprehensive techniques for testing REST, SOAP, and GraphQL APIs during bug bounty hunting and ...
   vet and install: cartographer install https://www.skills.sh/sickn33/agentic-awesome-skills/api-fuzzing-bug-bounty
...
NOTE: searched 19976 skills.sh names and 10 cached pages; fetched 8 page(s) now

这是针对随附目录的一次真实运行（内容已缩短：之后又进行了三次查找）。最适合的基于属性和变异测试的技能已经随附，因此不会再次推荐；剩下的技能只是与主题接近，并不完全相关。这就是为什么每项查找结果都标记为 UNVETTED，以及为什么提供了 --judge（见下文）：启用后，模型将所有结果都判定为偏离主题。

搜索的工作方式

1. 名称。 skills.sh 的站点地图列出了约 20,000 项技能，大多数是已安装的技能。列表会缓存一天，因此大多数搜索不会为此发送请求。
2. 筛选。 基于词语的匹配规则（下文介绍的 词汇表）会根据需求说明为每个名称评分。你已经拥有的技能（无论是按名称匹配，还是之前通过 cartographer install 安装的）都会被排除。
3. 获取少量页面。 仅获取当前 skills.sh 上匹配度最高的页面，每次搜索最多 8 个，并缓存一天。页面提供描述、安装次数、代码库、星标数和安全审计信息。
4. 再次评分，根据描述评分，应用热度门槛，并输出最佳的 5 项（--limit 最多为 10）。

只有当结果来自 GitHub 代码库、没有审计结果标记为 Fail，并且安装次数达到 1,000 次以上，或代码库星标数达到 200 个以上且安装次数达到 100 次以上，或所有者已验证且安装次数达到 100 次以上时，才会保留该查找结果。“常见覆盖技能”会列出你已有且概念相同的技能：安装新技能前请先检查这些技能。

选项

选项	含义
--offline	不联网：仅使用缓存的名称和页面
--judge	调用一次模型（任意后端）读取候选列表，并为每项标记 KEEP 或 DROP，同时给出原因
--lexicon FILE	向内置词汇表添加内容，或替换内置词汇表
--limit N	最多返回 N 项查找结果（1-10，默认 5；其他值将退出并返回 2）
--json	以 JSON 格式输出查找结果
--brief-file F	从文件读取需求说明，或使用 - 从标准输入读取（需求说明为 - 时也会从标准输入读取）

find 还接受 ask 的目录选项（--skills-dir、--no-user-skills、--no-bundled）；其模型选项（--backend、--model、--effort、--timeout、--command）仅供 --judge 使用。

退出代码：0 表示已输出查找结果；1 表示没有结果（或评审器将所有结果都排除）；2 表示参数错误、词汇表错误或需求说明为空；3 表示 CARTOGRAPHER_UNAVAILABLE（没有缓存且网络请求失败、缓存文件夹不可用，或没有查找结果，但部分匹配名称因页面获取失败或达到上限而无法核查：请稍后重试）、--judge 没有可用后端，或 JUDGE FAILED。

评审器。 --judge 会在一次调用中将需求说明和候选列表（名称、描述、来自 skills.sh 的数据）发送给你的后端。第三方文本会被作为数据进行隔离：其中（以及需求说明中）的 < 和 > 会替换为相似字符，因此无法关闭隔离区；双向文本和零宽字符也会被移除。回复必须是一个 JSON 对象，其中包含每个候选 ID 的判定结果，以及一个新的请求 ID。无法读取的回复会明确失败（JUDGE FAILED，退出代码为 3），并将候选列表显示为未评审；绝不会将其误显示为“全部被排除”。单个格式错误的条目会显示为 UNJUDGED。评审结果绝不会安装任何内容。

礼貌使用 skills.sh

查找器只会缓慢读取 skills.sh 的 robots.txt 允许访问的公开页面和站点地图，并缓存读取的内容。skills.sh 的条款欢迎合理使用和缓存其公开 API，并警告绕过速率限制的抓取行为可能会被封锁；条款未具体提及读取页面。查找器从不使用该 API（robots.txt 禁止访问 /api/），并且：

• 在请求其他内容之前先读取 robots.txt（复用一天内的副本），绝不请求被禁止的路径，例如 /api/ 或 /search；
• 一次只发送一个请求，间隔至少 1.3 秒（默认 1.5 秒；批量索引至少 3 秒），所有使用同一缓存文件夹的 cartographer 进程通过其中的锁文件共享这一限制；
• 遇到 HTTP 429 或 403 时立即停止，在 Retry-After 时间结束之前（至少一分钟）不再向该主机发送请求；若遇到 403，则等待六小时；
• 设置每日上限（UTC）：find 和 install 每天最多请求 300 个技能页面和 12 个 robots 或站点地图；批量索引另有每天 2,000 个页面的上限（技能页面和仓库页面），可通过 CARTOGRAPHER_FINDER_DAILY_PAGES、CARTOGRAPHER_FINDER_DAILY_LISTS 和 CARTOGRAPHER_FINDER_DAILY_BULK 更改；
• 使用 If-None-Match / If-Modified-Since 再次请求，因此未更改的页面会返回 304（find 中的过期页面，以及 finder index --refresh 中的每个缓存页面）；
• 仅请求列入白名单的 URL：skills.sh 页面和站点地图；对于 install，还会请求一次 GitHub API 和一个 tarball。拒绝跳转到白名单之外或 robots.txt 禁止的路径；每次跟随跳转都会等待间隔，且跳转到 skills.sh 会计入每日上限；绝不将 GitHub 令牌发送给跳转目标；
• 标明自身身份：the-cartographer/<version> (+https://github.com/sheepk95/The-Cartographer; skill finder; reads robots.txt; one request at a time, at least 1.3 s apart)。

The Cartographer 与 skills.sh 或 Vercel 没有隶属或背书关系。

升级共享抓取锁。 升级前停止所有旧版 The Cartographer 实例。切勿在同一缓存中混用新旧版本：旧版二进制文件可能会删除锁文件，且不会参与新的操作系统锁。新的 finder/fetch.lock 会有意保留；进程退出时，操作系统锁会自动释放，包括进程崩溃后。进程或等待者仍可能使用新的锁文件时，不要删除它。标记用于识别锁的类型：Windows 字节范围锁与 POSIX flock（包括 WSL）不能共用缓存。Windows 与 WSL 锁在共享文件系统上不能可靠地互相排斥，因此即使锁的所有者已退出，遇到不兼容的标记也会拒绝操作。遇到旧 PID/令牌标记、早期通用标记、未知标记或尚未初始化的空文件时，也会拒绝操作且不作修改。只有在使用该缓存的所有进程和等待者都已停止后，才手动移除不兼容或旧版标记，然后重试；下次启动时会创建当前平台的标记。首次初始化过程中断也可能留下空文件，需要按上述方式在停止进程后恢复。若需新旧版本或 Windows/WSL 共存，请设置不同的 CARTOGRAPHER_CACHE 路径；每个缓存都有独立的请求上限、间隔和阻止状态，因此它们产生的流量不会统一协调。

可选的批量索引。 cartographer finder index --top 2000 会按站点地图顺序抓取安装量最高的技能页面，以便 find --offline 和名称筛选界面有描述可用。它会实时读取 robots.txt，从上次停止处继续，在 find 正在抓取时让出执行权；遇到 429 或 403 时停止（或连续失败 25 次后停止），也可安全地按 Ctrl-C 中断。使用默认间隔（--gap，3 秒，也是最小间隔）时，抓取 2,000 个页面约需两小时；每日批量上限会将更大的索引分散到多天完成，--repo-pages 请求也会计入该上限。它不会自动启动：没有守护进程，也没有计划任务。cartographer finder status 会显示缓存和当天的请求数。

安装 find

cartographer install https://www.skills.sh/<owner>/<repo>/<skill>   # or: cartographer install <owner>/<repo>[/<skill>]

1. 读取技能页面中的数字（使用 --no-page 可跳过）。若审查结果为 Fail，则拒绝安装（可使用 --allow-audit-fail）。

2. 通过 GitHub API 获取提交（或使用 --ref <full sha> 指定），然后下载该提交的 tarball。

3. 查找技能文件夹（按名称查找，或使用 --path 指定）及其许可证：SKILL.md 的 license 字段（SPDX 标识符或类似 MIT OR Apache-2.0 的简单表达式），以及最近的、含有许可证文件的文件夹中的许可证文件（先查技能文件夹，再逐级查找父文件夹，直到仓库根目录）。若两者不一致，则两者都适用；其中较严格者优先。

4. 输出许可证依据、每个文件的大小及标记：脚本、二进制文件、大文件、可执行位（会被移除）。不会写入符号链接和设备文件。若归档包含绝对路径或 .. 路径，或任何成员名称中含有反斜杠或冒号，则拒绝处理；若文件名无法在所有系统上以相同方式写入，也会拒绝（例如 Windows 设备名 aux、COM1、COM¹、CONIN$，包含 <>:"|?* 的名称，以句点或空格结尾的名称，以及仅大小写不同的两个名称）。归档成员数超过 100,000 个或解压后超过 2 GB，也会拒绝处理。

5. 拒绝可能由 Agent 宿主自行运行的 Agent 配置：

   • 技能文件夹顶层的 .claude-plugin/、.codex-plugin/、.cursor-plugin/、.claude/ 或 hooks/ 文件夹，以及 .mcp.json、.lsp.json、settings.json、settings.local.json、hooks.json 或 plugin.json 文件；
   • SKILL.md front matter 中的 hooks 或 allowed-tools，包括带引号、含空格或写作 allowed_tools 的形式；以及检查程序无法读取的 YAML front matter 格式（{...} 流式映射、? key、<< 合并键、锚点、标签、转义键）；
   • SKILL.md shell 命令：任何空白字符后出现的 !`...`，或任何位置以 ! 开始的代码围栏。

   阅读后可使用 --allow-agent-config。更深层文件夹中的相同名称，以及任何位置的 agents/、commands/、.codex/、.cursor/ 或 .vscode/，只会列为警告，不会拒绝：宿主只会从插件或项目根目录加载这些内容。这些是采用失败即拒绝策略的模式检查，并不保证能检测到所有形式。

6. 拒绝缺失、未知、非商业、禁止演绎、仅提供源码或专有许可证，包括附带用途限制的宽松许可证文本（例如 MIT 加上“禁止商业用途”“仅供个人使用”或“不得再分发”等条款），以及列在 CARTOGRAPHER_REFUSE_LICENCES 中的许可证（例如 AGPL-3.0,GPL-3.0）。许可证会根据其措辞分类，因此请阅读输出的依据。只有在你有权使用该技能时，才可使用 --allow-any-licence 覆盖；记录中会注明这一点。Copyleft 许可证（GPL、LGPL、AGPL、MPL、EPL、CC-BY-SA、OFL）可以使用，但会附上一行说明，并记录为 "copyleft": true。

7. 写入前会征求确认（使用 --yes 可跳过；若没有终端，则会拒绝，而不会自行猜测），且绝不覆盖已有内容：目标文件夹已存在时会拒绝。文件会先写入隐藏临时文件夹，逐个检查路径是否位于该文件夹内，再重命名到目标位置。

默认安装到 ~/.agents/skills/<name>（使用 --dest、--name 可更改），目录会从此处查找技能。技能文件夹中的每个文件都会复制，包括 .github/ 等隐藏文件（仅排除 .git/），最多 500 个文件、20 MB。决策所依据的许可证文本始终会一并复制，即使 front matter 中已注明许可证也是如此；技能上方父文件夹中的许可证文件和 NOTICE 文件会放在旁边（若技能中已有同名文件，则保存为 <name>.upstream），并由记录中的 licence_text 列出。若上游没有许可证文本，install 会说明这一点。cartographer 绝不会运行其下载的任何内容（但请参阅上文的 Agent 配置说明）。 退出代码：0 表示已安装；1 表示已拒绝（许可、审核、Agent 配置、不安全或不可移植的名称、超过 200 MB 的 tar 包、文件夹已存在、你选择了否、未找到技能）；2 表示参数错误；3 表示下载或写入失败（网络、速率限制、无法读取的归档文件、磁盘），且未做任何更改。

每个已安装的技能都会获得一个 .cartographer-source.json：其中包含仓库、提交、文件夹、许可证及其证据和文本文件、Copyleft 和 Agent 配置标记及警告、每个文件的 SHA-256、标志，以及安装时的 skills.sh 数据。cartographer list 会显示每个技能的来源，cartographer doctor 会报告文件自安装后发生更改或许可证需要覆盖的已安装技能。拒绝记录会保存在缓存（finder/refused.jsonl）中，因此 find 不再推荐这些技能：如果在技能文件夹的上级找到许可证，或未找到许可证，许可证拒绝会屏蔽整个仓库；否则只屏蔽该技能；--judge 的提示注入标记会屏蔽该技能。

数据的含义

• 安装量来自 skills.sh CLI 的遥测数据。它们只统计通过该 CLI 进行的安装，而且很容易被夸大，因此只能视作粗略指标。
• 星标数是整个仓库的 GitHub 星标数，按 skills.sh 的显示方式呈现（四舍五入，例如“1.6K”）。大型技能集合仓库的星标数会计入其中的每个技能。
• 审核是 skills.sh 为该技能列出的安全扫描。“通过”不代表经过审核；请阅读文件。

词典

匹配规则由词典驱动：词典包含概念（测试、调试、安全、前端、视频等）、表示这些概念的词语、别名和平台词语。搜索至少需要任务描述与技能共享一个概念；越罕见的概念权重越高，技能名称中的匹配词权重额外增加。技能名称中包含某个平台或框架（Godot、visionOS、Vue、Django 等）的技能会被排除，除非任务描述中提到了同一个平台或框架。

使用 JSON 文件扩展词典（--lexicon FILE 或 CARTOGRAPHER_LEXICON）；各列表会追加到内置列表中，而 "replace": true 则从空词典开始（人气门槛保留默认值）：

{
  "concepts": {"testing": "hypothesis pbt", "parsing": "parser parsers grammar tokenizer"},
  "aliases": {"pbt": "property-based"},
  "conflict": "elixir",
  "not_conflict": "django",
  "blocked": [{"repo": "someone/some-repo", "reason": "licence unclear"}],
  "min_score": 1.8,
  "max_rows": 5
}

其他键：needs（{"video": "specific"} 会让某个概念只有在任务和技能共享 specific 中的某个词语时才计入）、context、name_weight、same_term_bonus 和 bar（人气门槛：min_installs、min_stars、min_installs_with_stars、min_installs_verified）。带有 id（owner/repo/skill）的 blocked 条目会排除该技能。带有 repo 的条目，如果原因提及许可证、恶意软件、机密信息或类似内容，就会排除整个仓库；其他原因只会添加备注。

限制。 首屏只会显示名称，因此名称中不含词典词语的技能只能通过批量索引找到。匹配的是词语，而非含义；--judge 会补充含义判断。skills.sh 页面和站点地图并非公开 API，因此它们发生变化可能导致解析失败：此时查找器会找到更少的技能，并在备注中说明，而不会猜测。

内置技能

来自 59 个上游仓库的 193 个技能。以下是其中的一部分：

领域	示例
Blender 和 3D 艺术	impertio-studio/blender-core-api、ifbars/blender-modeling-workflow、roble3/blender-uv-texturing、arjun988/geometry-nodes
Unity	gamedev-skills/unity-csharp-scripting、hissal/unity-testing、wshobson/unity-ecs-patterns、scenario-labs/scenario-unity-performance
Three.js 和 WebGL	cloudai-x/threejs-fundamentals、cloudai-x/threejs-postprocessing、mengto/threejs-landscape
游戏设计	gamedev-skills/game-feel、gamedev-skills/level-design、gamedev-skills/save-systems、mengto/design-action-combat
着色器和 VFX	minimax-ai/shader-dev、adevra/urp-hlsl-templates、omer-metin/vfx-realtime
测试	trailofbits/property-based-testing、trailofbits/mutation-testing、dotnet/test-gap-analysis、nowsprinting/test-designing-guide
调试、审查、重构	obra/systematic-debugging、mattpocock/code-review、wondelai/working-with-legacy-code、warpdotdev/merge-risk
安全审查	trailofbits/variant-analysis、trailofbits/audit-context-building、trailofbits/spec-to-code-compliance
Agent 工作流	obra/writing-plans、obra/subagent-driven-development、muratcankoylan/context-compression、anthropics/skill-creator、anthropics/mcp-builder
写作和营销	coreyhaines31/copywriting、coreyhaines31/launch、blader/humanizer、mattpocock/writing-for-agents
视频和音频	calesthio/editing-montage、elevenlabs/music、jakeschincariol/yt-retention、heygen-com/cut-the-curve
数据和 Web	supabase/supabase-postgres-best-practices、laguagu/postgres-semantic-search、zaggino/writing-json-schemas、openai/playwright、anthropics/frontend-design

cartographer list --origin bundled 可列出所有技能。catalogue/bundled.json 记录了每个技能的上游仓库、固定提交、路径、许可证以及每个文件的 SHA-256；THIRD_PARTY_NOTICES.md 提供了指向各自来源的链接。

• 未经更改。 每个文件夹都包含该提交中技能的上游文件，逐字节保持不变（不包括 .github/ 等隐藏工具文件夹），如果技能文件夹没有 LICENSE 和 NOTICE 文件，则还会附上上游的 LICENSE 和 NOTICE 文件。python tools/vendor.py verify 会离线检查全部 1078 个文件的哈希值；python tools/vendor.py fetch 会重新从上游下载这些文件。
• 获准再分发。 MIT（154）、Apache-2.0（32）、CC-BY-SA-4.0（6）、Unlicense（1）。非商业、未知或供应商限制许可下的技能均未收录。
• 在打包前已投入使用。 每个技能都已在维护者自己的 Agent 配置中日常使用。120 个技能在安装时有书面审查记录（bundled.json 中的 "review": "recorded"）；其余 73 个标记为 "review": "in use"。
• 运行脚本前先阅读。 某些技能附带辅助脚本。Cartographer 绝不会运行这些脚本；如果技能指示 Agent 运行，你的 Agent 可能会这么做。请像对待任何第三方代码一样谨慎对待这些脚本。
• 不需要这些技能？ --no-bundled 仅使用你自己的技能。

它如何作答

PICKS:
- <name> | <SKILL.md path> | <why, one line> | read: whole
- <name> | <SKILL.md path> | <why> | read: LARGE read in parts
MAYBE:
- <name> | <SKILL.md path> | <why it might fit> | read: whole
ALSO GREP: <2-4 words>
NOTE: <one line>
--- end of cartographer answer ---

• 提示词最多允许选择 6 项，且只能选择明确匹配的项；MAYBE 最多 3 项。有疑问的匹配项归入 MAYBE，Agent 只会读取它们的前 40 行。
• 当任务不需要技能时（例如复制文件、运行固定命令），使用 PICKS: none。
• 打印答案前，会对照目录核验每个名称：路径错误会被修正，虚构的名称会被删除并附上 NOTE。如果所有选择都是虚构的，答案将以退出码 3 结束（CARTOGRAPHER_UNAVAILABLE）。
• 每个选择项都必须包含全部四个字段（名称、路径、原因、read: ...）。如果 PICKS 部分没有可读取的条目，也没有明确写明 none（none、none.、(none) 或带简短原因的 none），则以退出码 3 结束。
• 超过 50,000 字节的 SKILL.md 会被标记为 LARGE（依据文件大小，而非模型的估算），因此 Agent 会分段读取。
• 简介只是数据。制图员会被告知绝不要遵循其中的指令，并且它没有可用于执行操作的工具。
• 固定的结尾行可让调用脚本区分完整答案与被截断的答案。

比较方式

还有其他选择技能的方法，每种方法都有不同的取舍：

方法	如何选择技能	取舍
Agent 提示词中包含所有描述	Agent 在任务进行中，根据名称和一句话描述自行决定	每轮都会消耗 token；列表越长越难处理
关键词或嵌入搜索（技能路由器、内置技能搜索）	根据任务文本与描述之间的相似度进行匹配	速度快，且每次查询免费，但匹配的是词语，而且候选短名单决定了哪些技能会被考虑
Cartographer	调用一次模型，根据简介评估所有描述，然后核验答案	每项任务需要调用一次模型（耗时数秒）；质量取决于描述

Cartographer 将关键词搜索保留为离线备用方案（cartographer search、search_skills），因此两种方法可以同时使用。

成本、速度与限制

• 目录大小。 搭配捆绑技能时约为 100-130 KB（约 28-35k 个 token）。目录会列出每个 SKILL.md 的完整路径，因此大小会随安装位置而变化。每项技能约占 150-180 个 token，因此添加技能后目录会增大。cartographer doctor 会显示你的目录大小。
• 缓存。 对于相同的技能，目录文本的字节内容相同，因此使用 anthropic 后端时，一小时内重复提问会从提示缓存中读取，而无需再次支付完整的输入费用。使用 CLI 后端时，则由 CLI 自身的缓存机制处理。
• 速度。 在上面的示例中，Claude Code 后端使用 Sonnet 在 8.4 秒内作答。模型越大、推理力度越高，耗时越长。
• 质量取决于描述。 如果技能的描述没有说明其用途，那么无论对模型还是对人来说，都很难选中它。
• 它负责选择，不负责检查工作。 检查器能确保每个名称和路径都真实存在，但不能保证选择正确。模型仍可能漏选技能或选入不合适的技能。

配置

变量	含义
CARTOGRAPHER_BACKEND	anthropic、claude、codex 或 command
CARTOGRAPHER_MODEL	该后端的模型 ID 或别名
CARTOGRAPHER_EFFORT	low ... max，或 none
CARTOGRAPHER_COMMAND	command 后端使用的命令
CARTOGRAPHER_REQUESTER	--from 的默认值（请求者）
CARTOGRAPHER_SKILLS_DIRS	额外的技能文件夹
CARTOGRAPHER_HOME	存放 skills/ 和 catalogue/ 的文件夹（默认：已安装的程序包，否则为克隆仓库）
CARTOGRAPHER_CLAUDE_BIN、CARTOGRAPHER_CODEX_BIN	CLI 不在 PATH 上时使用的路径
CARTOGRAPHER_CODEX_KEEP_CONFIG	设置后保留你的 Codex 配置（自定义提供商），而不是忽略它
CARTOGRAPHER_CACHE	find 和 install 使用的缓存文件夹（默认：Windows 上为 %LOCALAPPDATA%\the-cartographer，否则为 $XDG_CACHE_HOME/the-cartographer 或 ~/.cache/the-cartographer）；finder 的文件位于其 finder/ 文件夹中
CARTOGRAPHER_LEXICON	find 和 find_skills 使用的词典文件
CARTOGRAPHER_FINDER_DAILY_PAGES、CARTOGRAPHER_FINDER_DAILY_LISTS	find 和 install 每日对 skills.sh 页面（300 次）以及 robots/sitemap（12 次）请求的上限
CARTOGRAPHER_FINDER_DAILY_BULK	每日批量索引技能和仓库页面请求的上限（2000 次）
CARTOGRAPHER_REFUSE_LICENCES	以逗号分隔的许可证 ID 列表；除自身策略外，install 还会在此机器上拒绝这些许可证（例如 AGPL-3.0,GPL-3.0）
CARTOGRAPHER_NO_NETWORK	设置为任意值后，finder 和 installer 都不会发送请求，并会提示网络已关闭（测试会设置此项；模型后端不受影响）
CARTOGRAPHER_GITHUB_TOKEN	install 进行唯一一次 GitHub API 调用时可选使用的令牌（仅添加到发往 api.github.com 的请求中）

常见问题

它会把我的技能发送到其他地方吗？ 只会将技能放入你所选后端的提示词中，也就是你的 Agent 会发送技能的地方。The Cartographer 本身不会上传或存储任何内容。

如果无法连接到任何模型怎么办？ cartographer ask 会以退出码 3 结束，并显示 CARTOGRAPHER_UNAVAILABLE (reason)。使用集成代码片段完成设置的 Agent 随后会改为运行 cartographer search 并继续工作。

它会运行技能吗？ 不会。它只会列出技能。读取并遵循技能是你的 Agent 的工作。cartographer install 会下载并写入文件；它也不会运行这些文件，并且会拒绝安装 Agent 宿主可自行运行的 Agent 配置，除非你传入 --allow-agent-config。

find 会抓取 skills.sh 吗？ 不会。搜索会读取名称列表（列表在 sitemap 过期一天时重建），并且最多读取 8 个页面，同时遵循该站点的 robots.txt 和每日请求上限。批量索引需主动启用，至少间隔 3 秒运行一次，并有独立的每日上限（2,000 次）。

简要说明能劫持它吗？ 简要说明会作为数据进行包装，模型没有工具可用，回答还会与目录进行比对和检查，因此它列出的每个选项都是真实的目录条目。提示词还会告知模型：如果简要说明向它下达命令，就把它当作普通的技能问题来回答，并添加一条 NOTE 说明这一点。

每个辅助 Agent 都应该发起询问吗？ 不应该。协调器会在一份简要说明中列出每个辅助 Agent 的任务，并将相应选项传给各个辅助 Agent。

开发

python -m unittest discover -s tests
python tools/vendor.py verify

测试不会调用模型，也不会使用网络：它们覆盖了 front matter 读取器、目录、答案检查、命令后端、API 请求结构（使用替代 SDK）、MCP stdio 会话、软件包哈希，以及使用模拟的 skills.sh 和模拟的 GitHub tarball 对查找器和安装器进行的测试（robots、URL 白名单、速率限制、许可证拒绝、不安全归档、绝不覆盖、绝不运行下载）。如何为软件包提出更改或技能，请参阅 CONTRIBUTING.md；了解其工作原理，请参阅 docs/DESIGN.md；了解它会如何处理你的文件和网络，以及不会做什么，请参阅 SECURITY.md。

许可

The Cartographer 的代码和文档：Apache License 2.0（LICENSE），版权归 Blake W. 所有，2026 年。如果你转交副本或修改后的版本，请一并保留 NOTICE 文件，并标明你修改过的文件。每个捆绑的技能均遵循其所在文件夹中的独立许可证（THIRD_PARTY_NOTICES.md 列出了全部许可证）。