知识索引工具Skill：一键为代码库生成层次化 AGENTS.md 知识库
- 它做什么：自动扫描代码库，在根目录和复杂度达标的关键子目录生成层次化的
AGENTS.md知识文档，让 AI 编码助手和人类开发者都能快速读懂项目。 - 它怎么判断：不是"每个目录都塞一份文档"，而是通过文件数、子目录数、符号密度、引用中心性等指标打分，只有分数够高的目录才生成文件。
- 它有多快：通过并行探索智能体 + 主会话并发分析（bash 结构扫描、LSP 代码映射、读取已有文档）同时推进，且会根据项目规模动态增加智能体数量。
- 它可控吗：提供"更新模式"（默认，增量修改）与
--create-new（读取现有内容后全部重建）两种策略，还能用--max-depth限制目录深度。 - 它靠谱吗：内建审查与去重环节，明确禁止通用建议、父目录内容重复和冗长文风，最终输出一份结构清晰的完成报告。
1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？
技能基本信息
| 项目 | 内容 |
|---|---|
| 中文名 | 知识索引工具Skill |
| 英文名 | index-knowledge |
| 技能ID | 13738 |
| 一句话定位 | 为代码库生成层次化的 AGENTS.md 知识库，根目录 + 复杂度评分的子目录文档 |
它到底解决什么问题？
在真实项目里，文档往往处于两个极端：要么只有一份几万字的根目录 README，翻半天找不到"鉴权逻辑在哪"；要么干脆没有文档，新人只能靠"读代码猜意图"。对 AI 编码助手来说更麻烦——它看不到项目的隐含约定（哪些目录是核心、哪些写法被明令禁止、构建命令是什么），于是给出的代码总是"能跑但不像这个项目的人写的"。
知识索引工具Skill 要解决的就是这件事：它把"项目知识"从人脑和散落的注释里抽出来，变成一组分层的、有等级的、可被 AI 直接读取的 AGENTS.md 文件。根目录那份讲全局（项目是什么、结构长什么样、任务该去哪个目录找），子目录那几份讲局部（这个模块的独特约定和反模式），层级之间不重复。
一键安装的思路与步骤
AI 技能类工具的通用安装逻辑通常是"获取技能 → 挂载到你的 AI 编码环境 → 验证可用"，具体如下：
- 确认安装前提：你需要在具备技能（Skill）机制的 AI 编码助手环境中使用，例如支持 Task 子智能体、TodoWrite 任务清单、LSP 能力的客户端；同时你的项目需要有本地可读的代码目录。具体支持的客户端版本、运行环境要求，以官方说明为准。
- 获取并安装技能：通过官方技能市场或技能管理入口，按技能 ID
13738或英文名index-knowledge检索并安装。若你的环境提供命令行安装入口，请按官方文档给出的命令执行——具体命令与地址以官方说明为准。 - 启用与授权：安装后在技能列表中确认
index-knowledge处于启用状态，并保证该技能对你的工作区目录具备读取与写入权限（它需要读取代码结构、写入AGENTS.md）。 - 验证是否生效：在项目根目录发起一次最简单的调用（例如"用知识索引工具为当前项目生成 AGENTS.md"），观察是否出现四阶段任务清单（发现 → 评分 → 生成 → 审查）与最终的完成报告。能看到形如
./AGENTS.md的生成结果，即说明技能已正常工作。 - 回归检查：确认生成的
AGENTS.md内容贴合你的项目（提到的是你的真实目录和真实命令），而不是放之四海皆准的套话——这类通用内容恰恰是该技能明确要求剔除的。
提示：具体安装命令、下载链接、是否收费与授权方式，本技能详情中未提供，请一律以官方说明为准。
2. 该技能的主要功能和特点
- 层次化知识库生成：不只生成根目录一份文档，而是"根目录 + 子目录"两级（或多级）结构。根目录
AGENTS.md控制在 50–150 行，子目录控制在 30–80 行，体量被刻意压小，方便 AI 一次性读完。 - 基于复杂度评分的选址决策：这是它区别于普通文档生成工具的核心。它对每个候选目录按权重打分——文件计数（3x，>20 触发）、引用中心性（3x，>20 触发）、子目录数（2x）、代码占比（2x）、模块边界（2x）、符号密度（2x）、导出数（2x）、独特模式（1x）。总分 >15 必建，8–15 视是否独特领域而定，<8 直接跳过，交由父目录覆盖。
- 并行探索智能体：在一条消息中同时发起多个
Task探索调用（项目结构、入口点、约定配置、反模式注释、构建/CI、测试模式），而不是一个个排队执行。技能明确把"顺序执行"列为反模式。 - 动态智能体扩容：先跑 bash 统计项目规模，再按阈值追加智能体——文件数 >100 时每 100 文件 +1，总行数 >10k 时每 1 万行 +1，目录深度 ≥4 时 +2，大文件（>500 行）超过 10 个时 +1，检测到单体仓库时按包/工作空间追加，多语言项目按语言追加。项目越大，探查越细。
- LSP 代码映射：可用时通过
lsp_document_symbols、lsp_workspace_symbols、lsp_find_references获取入口点、关键符号和"被引用最多"的中心性信息，生成"代码映射"表格；LSP 不可用时自动回退到探索智能体 + AST-grep。 - 两种运行模式：默认"更新模式"（在现有内容基础上修改，并在合适位置新建）；
--create-new则是"先读取全部现有内容保留上下文 → 删除所有 → 从头重建"，避免丢失历史洞察。 - 深度可裁剪：
--max-depth参数限制目录深度，默认 5，可按需收紧到 2 等更浅的层级，适合中小项目。 - 强制审查与去重：生成后统一执行去重、修剪、验证——删除通用建议、删除与父目录重复的内容、把文风压成"电报体"。
- 任务透明可追踪：全程用 TodoWrite 维护四个阶段（discovery / scoring / generate / review）的待办状态，实时从"进行中"切到"已完成"，用户随时知道跑到哪一步了。
- 明确的"不要做什么"：为了避免产物变成"文档垃圾场"，它内置一份反模式清单：静态智能体数量、顺序执行、忽略现有文档、过度文档化、父子冗余、通用内容、冗长风格——七条红线全被点名。
3. 如何使用该技能？
整体使用路径可以概括为"一句话发起 → 四阶段自动执行 → 拿到分层文档 → 人工微调"。
步骤 1：在项目根目录发起调用
在已安装该技能的 AI 编码助手中，站在你的项目根目录下，用自然语言描述需求即可，例如：
步骤 2：按需选择运行参数
技能提供两种写法：
--create-new # 读取现有 → 删除所有 → 从头重新生成
--max-depth=2 # 限制目录深度（默认：5）
不传参数即为默认的更新模式：修改已有文档、在合适处创建新文档。首次在成熟仓库上使用时建议先跑默认模式；如果你对现有文档质量不满意、想彻底重来，再用 --create-new（注意它仍会先读取现有内容以保留上下文）。
步骤 3：观察四阶段执行
技能会自动建立任务清单并推进：
- 发现 + 分析（并发）：一条消息内并行发起多个
Task探索调用（项目结构、入口点、约定、反模式、构建/CI、测试模式）；与此同时主会话并行做 bash 结构分析（目录深度分布、每目录文件数 Top30、按扩展名统计代码集中度、查找现有AGENTS.md/CLAUDE.md）、读取现有文档、执行 LSP 代码映射。三者结果合并。 - 评分与决策：套用评分矩阵，输出类似下面的定位清单：
AGENTS_LOCATIONS = [
{ path: ".", type: "root" },
{ path: "src/hooks", score: 18, reason: "高复杂度" },
{ path: "src/api", score: 12, reason: "独特领域" }
]
- 生成：先写根目录
AGENTS.md，再为每个子目录位置并行启动生成任务，直接写入对应路径。 - 审查：去除通用建议、去除父目录重复内容、裁剪到行数上限、校验文风。
步骤 4：阅读生成结果
根目录 AGENTS.md 的标准骨架包含：生成时间/提交/分支元信息、概述（1–2 句）、结构（目录树，仅标注非显而易见的用途）、查找位置表（任务 → 位置 → 备注）、代码映射表（符号、类型、位置、引用数、角色）、约定（只写偏离标准的部分）、反模式（本项目明确禁止的写法）、独特风格、命令（开发/测试/构建）、备注。
步骤 5：确认最终报告
执行结束会输出一份汇总，形如：
=== 索引知识完成 ===
模式：更新 | 创建新
文件：
✓ ./AGENTS.md（根目录，N 行）
✓ ./src/hooks/AGENTS.md（N 行）
分析目录数：N
创建 AGENTS.md 数：N
更新 AGENTS.md 数：N
层次结构：
./AGENTS.md
└── src/hooks/AGENTS.md
步骤 6：人工复核与提交
建议把生成的 AGENTS.md 纳入版本管理，之后每次架构有较大变动时重跑一次更新模式。若发现某段内容是"放之四海皆准"的套话，直接删掉——这正是技能自身审查环节要清除的东西，保留它反而稀释了文档价值。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| index-knowledge（知识索引工具Skill） | 为代码库自动生成层次化 AGENTS.md 知识库 | 复杂度评分选址、并行探索智能体、动态智能体扩容、LSP 代码映射、更新/重建双模式、强制去重审查 | 需支持技能机制与子智能体的 AI 编码环境；调用只需一句自然语言 | 中大型仓库、单体仓库、多语言项目、需要给 AI 助手喂上下文的团队 | 优势：分层且不冗余，选址有量化依据，能识别项目特有反模式。不足：产物为 AGENTS.md 单一格式，深度依赖 LSP/智能体能力，环境不支持时需回退能力 |
| 手工编写 AGENTS.md / CLAUDE.md | 人工维护的项目约定文档 | 完全自由撰写 | 零门槛，但完全依赖人的经验与时间 | 小项目、约定简单明确的仓库 | 优势：可精确表达团队意图。不足：耗时、易过时、难覆盖多层目录，新人不知从何写起 |
| 通用 README / 代码注释 | 面向人类的传统项目说明 | 项目简介、快速开始、API 注释 | 低 | 对外开源项目、库类项目 | 优势：生态成熟、读者熟悉。不足：非结构化、不面向 AI 读取，缺少"哪该去哪找"的检索式结构，深层目录覆盖差 |
| AI 编辑器内置的项目规则文件（如各类 rules 配置） | 给 AI 助手注入少量行为约束 | 定义编码风格与禁止项 | 低，通常为单文件配置 | 个人项目、风格约束为主 | 优势：接入简单、即时生效。不足：多为单层扁平配置，无目录级层次化，缺乏自动化的项目结构分析能力 |
5. 该技能的典型应用场景与实际体验情况
场景一：新人接手一个陌生的大型仓库
- 角色/痛点：刚入职的后端工程师，面对 500+ 文件、6 层目录的仓库，不知道该从哪个入口读起；问同事又要排队。
- 使用方式：在根目录执行一次默认模式生成，先读根
AGENTS.md的"概述 + 结构 + 查找位置"三节锁定主线，再按需跳进src/hooks/AGENTS.md这类被标记为高复杂度的子目录。 - 实际体验：上手难度低，一句指令即可。效果上"查找位置表"最实用——它把"我要改鉴权 → 去哪个目录"直接映射出来。注意事项：首次生成的"命令"一节务必人工核对，确保与你本地实际脚本一致。
场景二：单体仓库（Monorepo）的多包维护
- 角色/痛点：平台团队维护十余个包，各包约定不同，AI 助手经常把 A 包的写法套到 B 包上。
- 使用方式：技能检测到单体仓库结构时会按包/工作空间追加探索智能体，评分环节让每个复杂包独立拿到一份
AGENTS.md，彼此隔离。 - 实际体验：这正体现了"复杂度评分选址"的价值——文档不会均匀撒胡椒面，而是集中在真的复杂的包上。注意事项：跨包共享工具往往被识别为"横切关注点"，建议在根目录文档的备注里补一句共享层的用法。
场景三：给 AI 编码助手补齐项目上下文
- 角色/痛点：AI 生成的代码总是"风格不对"，用错日志库、绕过项目封装、写出被明令禁止的模式。
- 使用方式：把生成的
AGENTS.md放在仓库内随代码一起提交，AI 助手读取后即可获知"反模式（本项目）"与"独特风格"两节。 - 实际体验：由于技能会专门抓取代码中
不要、从不、总是、已弃用这类注释，反模式一节常常写出人没意识到的隐性规则。注意事项：AGENTS.md应当随架构演进更新，长期不更新会反向误导 AI。
场景四：重构前的架构摸底
- 角色/痛点：准备拆分某个巨型模块，但不确定它的被依赖程度，怕动了引发连锁反应。
- 使用方式：跑一次生成，重点看"代码映射"表里的引用数列——引用中心性高的符号就是必须先隔离的风险点；再结合评分输出里
score: 18这类高分目录确定优先级。 - 实际体验：LSP 可用时这一节的准确性明显提升；若环境不支持 LSP，技能会回退到探索智能体 + AST-grep，细节颗粒度会下降，需要人工补验。
通用体验小结：整体上手难度低（一句自然语言即可触发），真正的门槛在于"结果复核"——把它当成一份高质量的初稿，而不是终稿。另需注意两点：一是 --create-new 会删除现有文档，删前确认已纳入版本管理；二是项目越大执行时间越长，建议在空档期跑。
6. 该技能能为用户带来的价值
效率层面：把"写项目文档"这件事从以天计的体力活，压缩成一次调用 + 一轮微调。四阶段并行执行的设计，让探索、分析、生成几乎同时铺开，而不是串行等待；项目越大，动态扩容的智能体带来的并行收益越明显。
门槛层面：文档写作长期依赖"资历"——只有待得够久的人才写得出来。这个技能把判断标准显式化：什么目录值得写（>15 分必建）、写多长（50–150 行 / 30–80 行）、什么不该写（通用建议、父子重复）。新人也能产出一份结构合格的初稿。
质量层面：评分矩阵与审查环节共同对抗"文档垃圾化"。多数自动文档工具的失败原因是"什么都写，结果什么都没说清"，而该技能用低分跳过、去重、电报文风三道闸门把冗余挡在外面。
长期价值：AGENTS.md 是随代码一起版本化的知识资产。当它与 AI 编码助手形成闭环后，团队获得的是一种"可累积"的能力——每次架构演进重跑一次更新模式，项目知识就沉淀一次，而不是随着人员流动反复丢失。
7. 常见问题 FAQ
Q1：这个技能怎么安装？需要配置什么吗？
A：在你的 AI 技能环境中按技能 ID 13738 或英文名 index-knowledge 检索安装，并确保对项目目录有读写权限。具体安装命令、支持的客户端版本与环境要求，本技能详情未提供，以官方说明为准。安装后在项目根目录发起一次简单调用，能看到四阶段任务清单和最终完成报告即表示生效。
Q2：使用这个技能收费吗？ A：技能详情中未涉及定价与授权信息，是否有免费额度、是否按调用计费，均以官方说明为准。建议在使用前查阅官方页面的说明。
Q3：--create-new 会删掉我现有的文档吗？
A：会。该参数的语义是"读取现有 → 删除所有 → 从头重新生成"，删除前它会先读取现有内容以保留上下文洞察，但文件本身仍会被重建。因此建议先把现有 AGENTS.md 提交到版本库，出问题可随时回滚。日常维护用默认的更新模式即可。
Q4：项目很大或者很小，都适合用吗？
A：都适合，但表现不同。小项目里评分环节会自动跳过大量低分目录，可能最终只有根目录一份文档——这是设计预期，不是没生效。大项目里它会根据文件数、行数、目录深度、大文件数量、是否单体仓库、语言数量动态增加探索智能体，耗时会更长，但覆盖也更细。如果觉得跑得太久，可以用 --max-depth=2 之类收紧深度。
Q5：和手工写 README、或用编辑器内置规则文件相比，该怎么选？ A：需要多层目录级知识、且希望给 AI 助手提供上下文时，选本技能；只需要一份对外介绍或少量风格约束时，手工 README 和单文件规则更轻。两者的核心差别在"层次化 + 复杂度选址"：本技能不会给每个目录都塞文档，只写真正复杂、真正独特的地方，因此更适合结构复杂的中大型仓库。