Code Indexers
A code Indexer teaches the Agent how to read one technology: where its features are declared, how to find them cheaply during planning, and what to read in full before explaining them. It exposes the module's skeleton and guides source-grounded writing; it does not recreate the workflow's routing. This page covers what to put in one, following the shipped context-code-indexer.
flowchart LR
sig["Signals<br/>manifests, entries, registrations"] --> skel["Skeleton<br/>names, counts, locations"]
skel --> topics["Reader topics<br/>and writing batches"]
topics -->|"report confirmed"| read["Read the code each<br/>article needs"]
read --> art["Article with<br/>real references"]What the Skill is responsible for
Describe the supported technology, the signals that activate it, the reader questions it can help answer and how to investigate an authorized module. A module may use several Skills for different concerns — say, one for the web framework and another for its message consumers. There is no exclusive primary owner, version pin, integrity receipt or registration step before production; Skill names and usage choices are temporary planning guidance, not article metadata.
Keep SKILL.md focused on discovery and decisions. Put detailed writing guidance and reusable scripts beside it, linked by relative path with a clear note on when to read them.
Skeleton first
During planning the Indexer should point the Agent at directories, manifests, registration points and bounded search — either for direct inspection or through a fast helper suited to the stack — and report matching names, known counts and file locations. It must not require complete symbol extraction, call graphs or reading every implementation before articles are proposed.
Typical signals and the questions they suggest:
| Signal | Suggests |
|---|---|
| Public exports or component declarations | How to consume a capability |
| Inbound registrations or interface definitions | Which operations are served |
| Event or scheduled registrations | What triggers work and how it completes |
| Storage interfaces | Data ownership and transaction boundaries |
| Adapters and generated clients | Contracts at an external handoff |
| Package and workspace entry points | Responsibility and consumption boundaries |
Signals suggest topics; they do not prove meaning. A route registration can suggest an API topic, but not its error behavior. File counts are not feature counts, and a stopped scan is never a full total.
Bounded helpers
Scripts are optional and serve one concrete, repeated task. A good helper takes explicit authorized paths and bounded options, keeps source files read-only, returns concise output or writes a file in the supplied temporary area, and stops within its budget. It reports inspected and uninspected scope, returns a continuation when it can, and labels partial counts.
It must not execute repository code, read credentials, traverse unrelated directories or contact external services. Unsupported syntax and incomplete traversal are reported separately from zero matches. Full parsing belongs to selected writing tasks; where a structural fact needs a real parser, use the built-in extractors described in Code Extraction.
Writing guidance
Once the work-start report is confirmed, the Agent reads the source each article needs. Guide it to explain contracts, state changes, failure behavior and integration points — what the module is responsible for, how to enter it, what it hands off. Parsing can locate declarations; it is not proof of runtime behavior. Preserve expressions without executing project code, keep declared defaults apart from implemented defaults, and state unknowns.
An Indexer may suggest a recurring outline for a feature family such as route groups or components, but not a fixed page count: a component manual may need component-by-component reading, while one page per symbol or a catch-all page for a large module are both wrong. Each section cites at most three real source locations; split an explanation when it needs separate evidence.
Example outline
A minimal Indexer for a hypothetical Acme RPC framework:
acme-rpc-indexer/
SKILL.md
references/
investigate.md # where services, methods and middleware are declared
writing.md # integration and maintenance guide outlines
scripts/
list-services.mjs # bounded: given paths, prints service and method names with locations
tests/fixtures/
orders-service/ # anonymous sample module---
name: acme-rpc-indexer
description: Investigate services built on Acme RPC and write integration and maintenance articles. Use when selected for a Context planning or writing task on such a module.
---
# Acme RPC Indexer
During planning, read `service.yaml` files and `@Method` registrations in the
authorized module. Report service names, method counts and file locations;
mark partial counts as partial. For large modules run
`scripts/list-services.mjs <paths> --max-files 2000`.
During writing, read [writing guidance](references/writing.md). For each
method, explain the request contract, errors and middleware actually applied.
A generated client is outbound, not proof that this module serves the method.Testing
Test the supported technology with anonymous fixtures: feature discovery, bounded stopping, unsupported input, repeated names in different paths, and the references in the final article. For generated API explanations, check defaults, shared types and unresolved cross-file links in the final page as well as the helper output. Use fixtures relevant to the technology, not a matrix of unrelated stacks.
Verify packaged relative links and executable helpers, and keep community examples free of company-specific services; organization knowledge belongs in its own Skills. See Creating an Indexer for the creation flow and Providers and Customization for combining Skills.
代码类 Indexer
代码 Indexer 教 Agent 如何阅读某一种技术：它的功能声明在哪里，规划期间如何低成本地找到它们，以及在讲解之前需要完整阅读什么。它展示模块的骨架并指导基于来源的撰写；它不会重新实现工作流的路由。本页参照自带的 context-code-indexer，介绍其中应包含的内容。
flowchart LR
sig["信号<br/>清单、入口、注册"] --> skel["骨架<br/>名称、计数、位置"]
skel --> topics["读者主题<br/>与撰写批次"]
topics -->|"报告已确认"| read["阅读每篇文章<br/>所需的代码"]
read --> art["带有真实<br/>引用的文章"]Skill 负责什么
描述所支持的技术、激活它的信号、它能帮助回答的读者问题，以及如何调研一个已授权的模块。一个模块可以针对不同关注点使用多个 Skill——比如一个用于 Web 框架，另一个用于消息消费者。生产之前不存在独占的主负责方、版本锁定、完整性回执或注册步骤；Skill 名称和使用选择是临时的规划指引，而不是文章元数据。
让 SKILL.md 专注于发现和决策。把详细的撰写指引和可复用脚本放在它旁边，用相对路径链接，并清楚说明何时阅读它们。
骨架优先
在规划期间，Indexer 应当引导 Agent 查看目录、清单文件、注册点并进行有限的搜索——可以直接查看，也可以借助适合该技术栈的快速辅助工具——并报告匹配的名称、已知计数和文件位置。在提出文章之前，它不得要求完整提取符号、构建调用图或阅读每一处实现。
典型信号及其引出的问题：
| 信号 | 引出的问题 |
|---|---|
| 公开导出或组件声明 | 如何使用某项能力 |
| 入站注册或接口定义 | 提供了哪些操作 |
| 事件或定时任务注册 | 什么触发了工作，工作如何完成 |
| 存储接口 | 数据归属和事务边界 |
| 适配器和生成的客户端 | 外部交接处的契约 |
| 包和工作区入口 | 职责与使用边界 |
信号只是提示主题，并不能证明含义。路由注册可以提示一个 API 主题，但不能说明它的错误行为。文件数不是功能数，中途停止的扫描也绝不是完整总数。
有限的辅助工具
脚本是可选的，只服务于一个具体的、重复的任务。好的辅助工具接受明确的已授权路径和有限的选项，保持源文件只读，返回简洁的输出或把文件写到提供的临时区域，并在预算内停止。它报告已检查和未检查的范围，能继续时返回续接点，并为不完整的计数加上标注。
它不得执行仓库代码、读取凭据、遍历无关目录或联系外部服务。不支持的语法和未完成的遍历要与零匹配分开报告。完整解析属于选定的撰写任务；如果某个结构性事实需要真正的解析器，请使用代码抽取中介绍的内置抽取器。
撰写指引
开工报告确认后，Agent 会阅读每篇文章所需的源码。引导它讲解契约、状态变化、失败行为和集成点——模块负责什么、如何进入、交出什么。解析可以定位声明，但不能证明运行时行为。保留表达式原样而不执行项目代码，把声明的默认值与实现的默认值分开，并写明未知之处。
Indexer 可以为路由组或组件这类功能类别建议一套重复使用的大纲，但不能规定固定的页数：组件手册可能需要逐个组件阅读，而每个符号一页或为大模块写一个大杂烩页面都是错误的。每个小节最多引用三个真实的源码位置；如果一段讲解需要不同的证据，就把它拆开。
示例结构
一个针对假想的 Acme RPC 框架的最小 Indexer：
acme-rpc-indexer/
SKILL.md
references/
investigate.md # where services, methods and middleware are declared
writing.md # integration and maintenance guide outlines
scripts/
list-services.mjs # bounded: given paths, prints service and method names with locations
tests/fixtures/
orders-service/ # anonymous sample module---
name: acme-rpc-indexer
description: Investigate services built on Acme RPC and write integration and maintenance articles. Use when selected for a Context planning or writing task on such a module.
---
# Acme RPC Indexer
During planning, read `service.yaml` files and `@Method` registrations in the
authorized module. Report service names, method counts and file locations;
mark partial counts as partial. For large modules run
`scripts/list-services.mjs <paths> --max-files 2000`.
During writing, read [writing guidance](references/writing.md). For each
method, explain the request contract, errors and middleware actually applied.
A generated client is outbound, not proof that this module serves the method.测试
用匿名测试夹具测试所支持的技术：功能发现、有限停止、不支持的输入、不同路径中的重名，以及最终文章中的引用。对于生成的 API 讲解，除了辅助工具的输出，还要在最终页面中检查默认值、共享类型和未解析的跨文件链接。使用与该技术相关的测试夹具，而不是一组互不相关的技术栈矩阵。
验证打包后的相对链接和可执行的辅助工具，并确保社区示例不包含公司特定的服务；组织知识应放在它们自己的 Skill 中。创建流程参见创建 Indexer，组合 Skill 参见 Provider 与定制。