agentsop-repo-map
Symbol-level code context for LLM coder-agents: tree-sitter extracts symbols, PageRank ranks them over the cross-file reference graph, and the top class/function signatures are fed to the LLM as a token-budgeted read-only map (not RAG, no vector index, human-auditable). Use when an agent must locate the right files in a large/multi-file repo, when builds/refreshes/scopes a repo-map, or when "model edits the wrong file" needs fixing.
npx skills add agentsope/SkillAlchemy --skill agentsop-repo-map --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# Repo-Map — 让 LLM 在大仓库里找到正确文件 > 一句话：**`tree-sitter` 抽取符号 → 在跨文件引用图上跑 PageRank → 按 token 预算把最重要的 class/function 签名作为只读地图塞进上下文**。它不是 RAG、不维护向量索引、可被人审。Aider 用同样的机制在 SWE-Bench Lite 上把"正确文件命中率"打到 **70.3%** [aider.chat/2024/05/22/swe-bench-lite.html]。 这是一个**工具技能**（tool skill），不绑定 Aider；任何 coder-agent harness 只要能给 LLM 喂上下文，都可以接入或自建 repo-map。 ## 1. 何时激活本技能 下列任一条件成立时，将"构建/刷新/使用 repo-map"作为该会话的标准动作： - 任务涉及 **多文件编辑** 或 **跨文件影响分析**（rename、抽函数、改 API 签名、加 hook 点）。 - 仓库 ≥ ~20 个源文件，或 LLM 无法靠记忆/猜测找到正确目标。 - 你不想（或不能）维护 embedding 索引：环境无 GPU、不允许出仓数据、PR 评审需可追溯证据。 - 你想给 LLM **可审计的导航地图**（vs. 黑盒向量检索）。`/map` 一样的 dump 必须能给人看。 - 多文件编辑后 LLM 反复改错文件、编造路径、SEARCH/REPLACE 找不到目标——典型的"没地图就乱走"信号。 - 你在写**自定义 coder agent**，需要一个"廉价、确定性、即时刷新"的代码 context 原语。 **不应激活的反面信号**：单文件改动且文件已知；任务是从零起项目；二进制资产仓库；非源代码（CSV/data lake）—— 详见 §6。 ## 2. 核心心智模型 ### 2.1 三个原语 + 两个不变量 ``` +----------------------+ +-----------------------+ +-----------------------+ | 1. tree-sitter | | 2. cross-file graph | | 3. token budget | | symbol extraction |-->| + PageRank-style |-->| (dynamic, shrink | | | | importance rank | | when files added) | | - parse, no execute | | - nodes = files | | - default ~1k tokens | | - class / fn / sig | | - edges = symbo
- 1. 何时激活本技能
- 2. 核心心智模型
- 2.1 三个原语 + 两个不变量
- 2.2 为什么不用 embeddings/RAG（设计决策）
- 2.3 LLM 看到的上下文分三层（优先级递减）
- 2.4 25k token 的稀释阈
- 2.5 Skeleton-over-snippets 的工程含义
- 3. SOP 工作流
- Phase 1 — Bootstrap：建图（每会话一次）
- Phase 2 — Use：让 LLM 用地图回答"改哪里"
- Phase 3 — Refresh：何时重建地图
- Phase 4 — Scope：地图也撑不住时
- Phase 5 — Audit：把地图当可审计文物
- 4. 操作模型（通用操作，去 Aider 化）
What does the agentsop-repo-map skill do?
Symbol-level code context for LLM coder-agents: tree-sitter extracts symbols, PageRank ranks them over the cross-file reference graph, and the top class/function signatures are fed to the LLM as a token-budgeted read-only map (not RAG, no vector index, human-auditable). Use when an agent must locate the right files in a large/multi-file repo, when builds/refreshes/scopes a repo-map, or when "model edits the wrong file" needs fixing.
How do I install it?
Run `npx skills add agentsope/SkillAlchemy --skill agentsop-repo-map --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From agentsope/SkillAlchemy, a repository with 255 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.