skill-llm-wiki

skill-llm-wiki

⚠ 仅阅读 SKILL.md 以及它指向的特定 guide/ 文件

硬性规则： SKILL.md 是你的入口文件。你还可以阅读此技能 guide/ 子目录中的文件，但只能阅读当前操作的路由流程明确指定的文件。绝不要阅读此技能目录中的其他内容：绝不要打开 README.md，绝不要打开 scripts/ 下的文件，绝不要打开 LICENSE，绝不要打开路由流程未启用的 guide/ 文件，也不要出于好奇打开任意文件。绝不要只为了查看文件内容而使用 cat / head / tail / Read。

script/ 下的脚本是工具，不是参考资料。请严格按照 guide/cli.md 中的说明，通过 node scripts/cli.mjs <subcommand> 调用它们。绝不要阅读其源代码，也不要从中导入内容。绝不要检查其内部实现——你需要了解的脚本行为都已在 guide/cli.md 中说明。

原因。 每读取一个字节都会消耗 token。此技能经过特意拆分，让你只读取当前操作所需的部分。一次典型的 Validate 操作会读取约 18 KB；一次典型的 Build 操作会读取约 32 KB；询问此技能用途的问题只需读取此文件（约 12 KB）。请遵守预算。

⚠ 预检：确认已安装 Node.js

在任何操作中首次调用 node scripts/cli.mjs 之前，使用 Bash 工具运行以下命令：

node --version 2>/dev/null || printf '%s\n' '__NODE_MISSING__'

解读这一行输出：

• __NODE_MISSING__ — 未安装 Node.js。请阅读 guide/ux/preflight.md，选取“Case A”消息，并原样转达给用户。**停止操作。**不要尝试运行任何 node scripts/cli.mjs 命令，也不要尝试自行安装 Node。
• v<N>.x.x，其中 N < 18 — Node.js 版本过旧。请阅读 guide/ux/preflight.md，选取“Case B”消息，替换其中的版本字符串，并原样转达。停止操作。
• v<N>.x.x，其中 N ≥ 18 — 预检通过。继续操作。

每次操作开始时都要运行预检。绝不缓存、跳过或添加额外逻辑。scripts/cli.mjs 也会执行运行时检查，如果在不受支持的 Node 版本上调用，会以代码 4 退出——这只是纵深防御；始终先运行 Bash 预检，让用户看到 guide/ux/preflight.md 中详细的安装或升级提示。

此技能的功能

构建和维护LLM wiki：基于文件系统的知识存储，经过结构化处理，便于大模型以确定性且节省 token 的方式检索。提供六种操作：构建、扩展、验证、重建、修复、合并。提供三种布局模式：

• sibling（默认） — 写入稳定的同级目录 <source>.wiki/。一个 wiki，一个同级目录，永久如此。可通过私有仓库 <wiki>/.llmwiki/git/ 中的 git 标签（pre-op/<id>、op/<id>）访问先前状态。不会产生一系列 .llmwiki.v<N> 版本化目录。
• in-place — 源文件夹本身就是 wiki。会在源文件夹内创建 <source>/.llmwiki/git/；pre-op/<first-op> 快照会逐字节捕获用户的原始内容；回滚会精确还原原始目录树。仅当用户明确传入 --layout-mode in-place 时运行——绝不推断，也绝不替换为其他模式。
• hosted — 写入用户选择且带有 .llmwiki.layout.yaml 契约的路径。用户传入 --layout-mode hosted --target <path>。

每项操作都是一个 git 序列：preflight → pre-op snapshot → phase commits → validation → commit-finalize。回滚、差异、日志、责备、引用日志、历史记录和远程镜像都是一等技能子命令，可通过 node scripts/cli.mjs <subcommand> 调用。所有操作都必须显式调用——没有钩子、监视程序或自动化。

遇到含糊的调用时会拒绝执行并提示用户。 如果用户的请求可能有两种含义（默认的 sibling 会覆盖其他目录、托管目标没有契约、将 --layout-mode in-place 与 --target 一起使用，等等），CLI 会以代码 2 退出，并返回结构化的 INT-NN 错误，而不是自行猜测。完整列表见 guide/ux/user-intent.md。

将其他技能或 Agent 集成为使用方

如果用户正在构建一个以编程方式调用此技能的技能、Agent 或 CI 任务（而不是在当前会话中要求你为其构建 wiki），请引导他们查看 guide/consumers/index.md。该目录树说明：如何针对 format_version 设置门槛，如何用一条命令为某个主题 wiki 执行 init，如何在每次叶节点写入后执行 heal，如何检测技能缺失的情况，以及如何使用随附的 scripts/testkit/ 辅助工具编写使用方测试。每个使用方操作指南都从 guide/consumers/index.md 分发；不要仅根据 SKILL.md 重新推导集成方式。

快速探测摘要：skill-llm-wiki contract --json 会返回 format_version、完整的 CLI 和 frontmatter 架构；skill-llm-wiki where --json 会返回绝对安装路径。两者均不受运行时依赖预检限制，因此使用方可在技能尚未完成设置时进行探测。

非自动化契约

此技能没有钩子、没有文件系统监视程序、没有 PostToolUse 监听器、没有安装时接线，也没有后台进程。每项操作仅会在用户明确请求后，针对明确指定的目标目录直接执行。如果用户没有提出请求，就什么也不做。不要提议自动化。不要创建钩子。不要安排任何任务。

如果用户手动编辑 wiki，导致索引过时，在用户明确要求刷新之前不会发生任何操作——届时只运行用户要求的操作。

⚠ Agent 委派契约

每项 wiki 操作都必须在专用子 Agent 中运行，不能在当前会话中直接执行。 这是一条硬性规则，而非优化选项。

当用户请求六项操作（Build、Extend、Validate、Rebuild、Fix、Join）中的任意一项时，不要在主聊天中直接执行 node scripts/cli.mjs <operation> ...。请改为：

1. 明确请求——确定操作、来源、目标、布局模式和任何约束。必要时请用户澄清（参见 guide/ux/user-intent.md）。
2. 在主会话中运行 Node.js 预检——这项操作开销低、输出简短，并且必须在启动任何 Agent 之前执行，以便失败时用户能看到详细的安装／升级消息。预检失败时，停止操作；不要启动 Agent。
3. 通过宿主程序的子 Agent 调度原语启动专用的「wiki-runner」子 Agent（Claude Code：Agent 工具；Codex CLI：等效工具；参见 subagent-dispatch-v1 规范），并提供一条自包含的提示词，说明：操作、已确定的 CLI 调用、按文件名列出的已启用 guide/ 叶节点、任何质量模式／布局模式标志，以及完成标准。子 Agent 负责运行 CLI、处理 Tier 2 子委派、管理自己的上下文，并在完成后汇报摘要。
4. 将子 Agent 的摘要转达给用户。 主会话绝不将 wiki 内容加载到自身上下文窗口中。

原因

Wiki 的规模可能相差很大：从包含 10 条记录的笔记文件夹，到包含 10,000 条记录的知识库。对于一个以散文为主、包含 10,000 条记录的语料库，Build 在起草 frontmatter 时，可能会在 Tier 2 中调用宿主大模型处理数千条记录。如果在主会话中直接运行所有这些操作，就会把用户的上下文预算消耗在他们并未要求查看的内容上，也会让后续对话没有空间。wiki-runner 子 Agent 拥有自己的上下文窗口；主会话的预算则可以保持精简，以便继续与用户交流。

wiki-runner 子 Agent 的职责

• 执行 CLI 子命令，并定期传回进度（不要在每个阶段都频繁发送消息——每个阶段一行就够了）。
• 管理自身的上下文窗口。 子 Agent 会监控剩余预算，并在接近上限时自动压缩。有关此协议，请参阅 guide/isolation/scale.md 中的“wiki-runner 中的上下文窗口管理”——简而言之：私有 git 中的阶段提交是持久检查点，因此子 Agent 可以安全地丢弃先前阶段的对话历史，只重新读取下一阶段所需的内容。
• 处理 Tier 2 的 exit-7 握手。 该技能的 CLI 在 Node 下运行，无法直接启动子 Agent。当 operator-convergence 阶段积累了 Tier 2 请求（集群命名、中间层级的合并决策、propose_structure 整个目录的请求、nest_decision 门控决策，……）时，CLI 会将这些请求写入 <wiki>/.work/tier2/pending-<batch-id>.json，并以代码 7（NEEDS_TIER2）退出。每个待处理请求都遵循 subagent.dispatch.v1 结构（prompt、inputs、effort、可选的 model、response_schema、outputs_path），因此任何 Agent Skills 执行框架都可以处理。Exit 7 并非失败，而是暂停并恢复的信号。wiki-runner 必须：
  1. 检测 CLI 是否以 exit 7 退出。
  2. 读取 <wiki>/.work/tier2/ 下的所有 pending-*.json 文件。
  3. 处理每个请求（参见下文“内联处理与扇出”）。
  4. 收集每个子 Agent 的结构化 JSON 响应。
  5. 将合并后的结果写入 <wiki>/.work/tier2/responses-<batch-id>.json（每个待处理批次对应一个文件，批次 ID 必须匹配）。
  6. 使用相同的位置参数重新调用 CLI。编排器会在恢复时将响应写入分层决策映射，并从上次提交的迭代继续执行。
  7. 如果重新调用后再次产生 exit 7，则继续循环（可能是更深层的子集群、剩余目录，或在提前执行 NEST 后生成的其他 propose_structure 请求）。在 exit 0（完成）或任何其他非零代码（实际失败——向主会话报告）时终止。

内联处理与扇出处理

wiki-runner 会根据批次大小选择内联或扇出处理。无论采用哪种方式，技能 CLI 的线协议都相同：输入待处理文件，输出响应文件，中间以退出码 7 退出。因此，这完全取决于上下文预算和吞吐量，由 wiki-runner 在运行时决定：

• 内联（每批 ≤ 约 50 个请求）。 wiki-runner 会直接回答每个请求，自己作为 Tier 2 工作器进行推理。不会针对每个请求分派子 Agent。wiki-runner 可以看到每个请求的 prompt、inputs、response_schema、effort（可选的 model 覆盖项），并直接写入 JSON 响应。对于典型的、针对约 10–50 个叶节点语料库进行的 build/rebuild，这是合适的选择：批次规模较小，扇出开销会远超实际工作量，而且 wiki-runner 自身的上下文足以处理几十次 frontmatter 数据块比较。环境限制：在当前的 Agent Skills 工具框架（Claude Code、Codex CLI）中，通用子 Agent 无法自行再创建子 Agent，因此当 wiki-runner 本身是嵌套子 Agent 时，内联处理实际上是唯一可行的选项，技能设计也不得要求扇出处理。

• 扇出处理（每批 > 约 50 个请求，或每个请求的 effort/model 各不相同）。 wiki-runner 会将批次大小报告给主会话，由主会话通过宿主工具框架的子 Agent 原语，针对每个请求（或每小组同质请求）分派一个范围明确的子 Agent，并传入请求的 prompt、inputs、response_schema、effort 和可选的 model。子 Agent 只能看到这些输入（merge_decision 请求的两个 frontmatter 数据块、cluster_name 请求中某个集群的叶节点元数据、propose_structure 请求中某个目录的完整叶节点列表，等等）。切勿传入整个 wiki。对于大型语料库（数千个叶节点，意味着数千个草拟 frontmatter 和合并决策请求），扇出处理更合适；若采用内联处理，则会耗尽 wiki-runner 的上下文。

无论采用哪种方式，技能 CLI 都无需更改——它始终会生成待处理文件并以退出码 7 退出；wiki-runner 可以自行决定在响应文件出现之前如何进行实际推理。

每种 Tier 2 类型的提示词模板

对于小批量内联处理，wiki-runner 可以使用以下现成模板。每个模板都必须返回与请求 response_schema 匹配的严格 JSON；在 JSON 对象之外添加说明文字属于测试错误。

propose_structure：

You are a Tier 2 sub-agent for skill-llm-wiki acting as a structural optimiser. Answer in STRICT JSON matching the response_schema. Return ONLY the JSON object, no commentary.

Directory: <inputs.directory>
Leaves:
```json
<inputs.leaves array>
```

Your task:
Propose the optimal nested structure for this directory. Group related leaves into named subcategories (slug + purpose + member ids). Leaves that genuinely stand alone should be reported as siblings. You SHOULD favour nesting over flatness whenever 2+ leaves share a defensible conceptual grouping — err on the side of nesting if in doubt.

Response schema:
{
  "subcategories": [ { "slug": "<kebab-case>", "purpose": "<one line>", "members": ["<leaf-id>", ...] }, ... ],
  "siblings": ["<leaf-id>", ...],
  "notes": "..."
}

Return your answer now as a single JSON object.

nest_decision：

You are a Tier 2 sub-agent for skill-llm-wiki acting as a nesting gate. Answer in STRICT JSON.

Cluster candidates:
```json
<inputs.leaves array>
```

Should these N sibling leaves be grouped together under a new parent subcategory? Answer `nest` if they share a defensible conceptual grouping that would meaningfully improve routing, `keep_flat` if the overlap is incidental and nesting would add noise, or `undecidable` if you cannot tell from the frontmatter.

Response: { "decision": "nest"|"keep_flat"|"undecidable", "reason": "<one line>" }

cluster_name：

You are a Tier 2 sub-agent for skill-llm-wiki naming a cluster. Answer in STRICT JSON.

Cluster members:
```json
<inputs.leaves array>
```

Return a short kebab-case slug (one or two words, e.g., `history` or `layout-modes`) and a one-line purpose. If the leaves are clearly unrelated, return decision `reject` with a reason.

Response: { "slug": "<kebab-case>", "purpose": "<one line>" } or { "decision": "reject", "reason": "<...>" }

• 报告完成情况，提供一段摘要，并附上编排器分配的 op-id。

默认模型和工作力度

除非用户另有说明，否则 wiki-runner 及其 Tier 2 扇出会在默认工作力度下，选择最适合任务规模的模型。具体如下：

• Wiki-runner：以能够协调 CLI 子进程并在上下文中容纳整个操作的子 Agent 类型启动。对于超大型语料（>1k 条目或 >10 MB），优先使用上下文长度为 1M、工作力度较高的模型（effort: "heavy"）。
• Tier 2 draft-frontmatter 子 Agent：选择宿主映射到 effort: "light" 的模型；从单个源文件撰写一组约 200 词的 focus + covers[] 时，这种模型具有较高的成本效益。
• Tier 2 operator-convergence 子 Agent：根据成对项的模糊程度，使用 effort: "light" 至 effort: "balanced"。宿主映射的模型应擅长对 frontmatter 成对项进行结构判断。
• Tier 2 rebuild plan review 子 Agent：使用 effort: "heavy"，因为这属于需要「深入理解」的情况。
• HUMAN-class Fix 子 Agent：使用 effort: "balanced"，因为此决策需要给出理由。

用户指定覆盖项。 如果用户指定模型（"use sonnet"、"use gpt-5-codex"、"use opus 1M for the whole thing"）或工作力度（"light effort"、"maximum quality"），则将其作为调度信封的可选 model 字段和必需的 effort 字段传递。宿主运行器会在设置了 model 时采用用户指定的模型；否则会将 effort 映射到自己的模型阵容。用户指定的覆盖项必须应用于该操作启动的每个子 Agent，而不只是 wiki-runner。如果用户指定了相互冲突的覆盖项（例如，所选模型不支持要求的工作力度），请先询问再继续。

行内执行是例外，而非常规做法

只有在进行一次性只读探测且输出很少时，才可在主会话中直接运行 node scripts/cli.mjs：--version、--help、validate <small-wiki>、log <wiki>、diff <wiki> --op <id> --stat、resolve-wiki。如果探测可能返回数百行以上，或涉及变更，则启动子 Agent。

布局模式检测

默认模式为 sibling。技能的 intent.mjs 解析器会根据调用决定有效模式，不会自行猜测。以下是各操作的检测流程概要：

• Build。 如果用户显式传入 --layout-mode <mode>，则遵照执行。否则默认为 sibling。如果源目录已包含 .llmwiki/git/，技能会以 INT-02 拒绝操作（「这已经是一个 wiki——你是想扩展、重建还是修复？」）。如果默认的同级目录 <source>.wiki/ 会指向一个非空的外部目录，技能会以 INT-01 拒绝操作。
• Extend / Rebuild / Fix。 对现有 wiki 执行操作；布局模式取决于构建该 wiki 时使用的模式。解析器会读取同级/原位布局中的 <wiki>/.llmwiki/git/，以及托管布局中的 <target>/.llmwiki.layout.yaml。
• Join。 用户指定的 <target> 若包含契约，则使用托管模式；否则使用同级模式。多源合并必须显式指定规范源（否则报错 INT-07）。
• Hosted。 用户传入 --layout-mode hosted --target <path>。如果缺少 <target>/.llmwiki.layout.yaml，技能会以 INT-01b 拒绝操作，并询问是要创建契约还是选择其他目标目录。

绝不要手动解析目标路径来猜测模式。始终使用用户明确指定的标志调用 CLI，并信任解析器的判定；将 INT-NN 错误原样呈现给用户。

每个操作只确定一次模式。操作过程中绝不要切换模式。

如何调用此技能

当用户请求执行某项操作时：

0. 运行 Node.js 预检。 参见上文。如果失败，请停止并转达 guide/ux/preflight.md 中面向用户的消息。
1. 仔细阅读请求。 要执行哪项操作？源是什么？目标是什么？在进行任何更改前，先确认不确定的细节。如果请求含糊不清（例如“迁移我的笔记”“原地操作”“放到我的记忆文件夹里”），请在调用 CLI 前提示用户消除歧义，参见 guide/ux/user-intent.md 中需要这样处理的情形。
2. 确定确切目标。 绝不要推断目标。目标不明确时请询问。对于 build ./docs，默认的同级位置是 ./docs.wiki/。
3. 决定布局模式。 参见上文的“布局模式检测”。默认采用同级布局；in-place 和 hosted 必须显式指定 --layout-mode 标志。
4. 通过 guide/ 自身的索引进行路由——参见下文的“路由”部分。阅读 guide/index.md，根据用户请求计算激活集合，然后只阅读已激活的叶节点。绝不要从 wiki 外部随意挑选 guide/ 文件。
5. 规划各阶段。 对于较长的操作，使用 TodoWrite，让用户能够查看进度并在需要时中断。
6. 从风险最低的阶段开始。 任何涉及现有 wiki 的操作，都应先运行 Validate，并在继续进行结构性更改前报告发现的问题。
7. 使用 CLI 执行确定性阶段。 每个子命令都记录在 guide/cli.md 中。
8. 在你自己的上下文中处理 AI 密集型工作。 根据散文草拟 focus 和 covers[]、在没有分类体系时进行分类、语义 DECOMPOSE 分区、AI-ASSIST 修复——这些都由你负责。使用 Read 读取源文件，使用 Write 写入 frontmatter，并验证往返结果。
9. 提交前进行验证。 提交前始终对新状态运行 Validate。绝不要让 wiki 处于损坏状态。
10. 请求的操作完成后立即停止。 除非用户提出要求，否则不要继续执行 Rebuild 或 Fix。不要对用户未提及的 wiki 运行 shape-check。不要打开同级 wiki 进行比较。

路由到 guide/

guide/ 是一个真实的 LLM wiki——与此技能为用户构建的结构相同。Claude 通过该方法标准的语义路由流程在其中进行路由，而不是依赖手动维护的表格。这样可以让你掌握一次路由规范，之后将其应用于你操作的任何 wiki。

流程

1. 根据用户请求构建上下文档案。 档案是一个小型结构化对象，由 Claude 在其内部构建。包含的三个字段用于塑造你针对 wiki 进行语义匹配时构造的查询——这些字段不再用于对汇总路由表进行字面关键词或标签匹配。

   • keywords——来自请求的词元。包括操作名称（build、extend、validate、rebuild、fix、join）、常见同义表达（create wiki、check wiki、repair、optimise、merge wikis）、子命令名称（ingest、shape-check）以及用户使用的其他具体术语。用这些内容构造语义意图，再与每个条目的 focus 进行匹配。
   • tags——Claude 根据请求推导出的简短类别标签：
     • operation——只要用户请求六种操作中的任意一种，就设置此标签。
     • hosted-mode——当目标为托管模式时设置（模式检测步骤已作出此判断）。
     • mutation——除 Validate 外的任何操作都设置此标签（可能会发生结构性更改）。
     • preflight-failure——仅当 Node.js 预检实际失败时才设置；默认情况下绝不设置。
   • operation——请求所涉及的单个操作 ID（build / extend / validate / rebuild / fix / join），信息查询则为 null。这表示 operations 子树属于相关范围。

2. 阅读 guide/index.md。 解析其中的 frontmatter。entries[] 字段列出每个直接子项及其 id、file、type、focus 和所有由作者编写的 tags。父级索引还包含由作者编写的 shared_covers 列表，用于描述该子树中所有子项的共同点——在决定是否继续向下查找时，将其作为补充上下文。

3. 判断哪些条目与当前请求相关。 阅读每个条目的 focus（并参考父级的 shared_covers，将其作为子树共享的上下文），然后做出语义相关性判断：该条目的用途是否与用户的请求有交集？如果请求中的关键词或短语出现在条目的 focus 中，这是强烈的正向信号；即使没有字面重合，只要语义上与请求意图相近，也同样是强烈信号——同义词和转述也应视为匹配。判断应当包容，但不能不加甄别：如果条目的 focus 与当前请求明显无关，就跳过。没有可供查询的字面关键词／标签对照表；是否匹配取决于你的判断。

4. 继续查找匹配的子类别。 如果匹配的条目包含 type: index，则 Read 其 index.md，并在该层重复步骤 2。不要使用 AND 筛选，也不要级联激活集合——步骤 3 中的语义相关性判断是唯一的筛选条件。对于信息类查询，通常不会继续查找 guide/ 下的 operations/ 子树，因为其 focus（“六种 CLI 操作及其阶段”）与询问技能功能的问题并不匹配——这正是你所需要的提前停止。

5. 加载匹配的叶子条目。 对于每个匹配的叶子条目，读取其完整文件。打开叶子条目后，其中自己的 activation.{keyword_matches,tag_matches,escalation_from} 块（如果存在）只是补充提示数据，而非路由规则：它说明作者认为该叶子条目在某些情况下为何相关，并可帮助判断后续操作（例如，“该叶子条目在 escalation_from 中列出了 fix，因此如果我正在处理 Fix 操作，应该检查相邻的 correctness/invariants.md 是否也适用”）。但绝不能据此按字面匹配来决定是否加载该叶子条目——这项决定已在步骤 3 中根据父级的 focus 描述做出。

6. 预检失败时走专用路径。 如果 Node.js 预检失败，你的上下文配置仅为 tags: [preflight-failure]，不包含任何操作意图。围绕预检这一概念语义查找 wiki：ux/preflight.md 叶子条目的 focus 显然匹配（其父级子类别 ux/ 中关于面向用户的消息的共享说明，也进一步支持这一匹配）。只加载这一个叶子条目，原样转述相应的 Case 消息，然后停止。不要加载操作类叶子条目。

7. 信息类查询。 当用户询问“这个技能的作用是什么？”“解释一下托管模式”“有哪些操作？”或其他任何不要求针对某个目标执行操作的问题时，步骤 3 中的语义判断应当在根级 entries[] 中得出零个匹配项——其中的 focus 字符串描述的是“如何做 X”，而非“X 是什么”，因此与信息类意图没有交集。不要读取 guide/ 中的任何内容。 仅根据 SKILL.md 作答。例外情况：如果用户的问题明确针对某个 wiki 主题（例如“解释一下托管模式”“布局契约是如何运作的”），则从语义上继续查找到对应的那个叶子条目，并且只读取它。

为什么这比手动维护表格更好

• 自动维护。 在 guide/ 下添加新叶节点，只需清晰地写出其 focus，并将其放在正确的子类别下。路由会在下一次 index-rebuild 时将其纳入。无需编辑 SKILL.md。
• 每个关键词只写一次。 作者只需将每个与路由相关的词准确写一次——放在叶节点自己的 focus 中（也可以选择放在 activation 提示块或父级的 shared_covers 中）。旧的底层结构会将每个关键词沿着逐级细化的链条重复写入每个祖先的 activation_defaults，因此单个叶节点的关键词最终会出现在三到四个索引中。新的底层结构消除了这种重复。
• 语义匹配可处理同义词、改述和新词汇。 旧的字面路由只能匹配作者列出的关键词。使用语义匹配后，即使两个短语没有任何相同的字面词项，“blame a line”也会找到 focus 写着“inspect per-line authorship”的叶节点。这就是 Claude 已经用于处理此技能其他内容的推理方式——现在路由也与之保持一致。
• 路由与技能的其余部分保持一致。 第 2 层决策本来就是语义式的（集群命名、嵌套门控、propose_structure）。路由是最后一个确定性层，而它强加给每个索引文件的汇总负担，就是确定性所付出的代价。采用语义路由后，底层结构与其他部分保持一致，也消除了这项负担。
• 传授可迁移的技能。 应用于 guide/ 的流程，也同样适用于任何 LLM wiki——例如，用户自己的 ./memory.wiki/ 或 ./docs.wiki/。一个流程，无限个 wiki。
• 让信息查询提前结束。 对“这个技能能做什么？”的提问，在根目录不会产生任何语义匹配，因此只需根据 SKILL.md 作答。这仍然是成本最低的路径。

禁止使用的捷径

• 不要在 SKILL.md 中通过硬编码路径读取 guide/ 文件。始终遵循路由流程。
• 阅读叶节点前，必须先阅读 guide/index.md 以查看其 focus。
• 决定匹配前，不要查看叶节点的 frontmatter——根索引的 entries[] 已包含叶节点的 focus 字符串，足以判断其相关性。
• 不要跳过信息查询的提前结束步骤，也不要预先读取所有内容。每个字节都会消耗 token。

应避免的常见错误

• 通过硬编码路径读取 guide/ 文件。 始终按路由流程操作。路由流程就是方法，不要绕过。
• 针对信息查询读取任何 guide/ 文件。 对于“这个技能有什么用？”这类问题，根目录条目中不会有语义匹配项——仅根据 SKILL.md 作答。
• 在决定是否匹配前查看叶节点的 frontmatter。 guide/index.md 的 entries[] 已包含每个子项的 focus 字符串——匹配时应使用它。打开叶节点读取其 frontmatter 是浪费：相关性判断应在父级完成。
• 将脚本作为源码读取。 绝不这样做。通过 guide/cli.md 中记录的 CLI 子命令使用脚本（按路由流程到达该文件）。
• 跳过 Node.js 预检。 每次操作前都要运行，无一例外。
• 尝试自行安装或升级 Node.js。 绝不这样做。预检失败时，按语义在 wiki 中查找预检概念——guide/ux/preflight.md 的 focus 与之匹配——读取该文件并原样转达。
• 在 sibling 模式下写入用户的源文件夹。 绝不这样做。sibling 模式下源文件不可变；所有写入都应进入 <source>.wiki/。
• 在 hosted 模式下超出布局约定进行写入。 布局约定具有权威性。
• 推断 in-place 模式。 绝不这样做。用户必须显式传入 --layout-mode in-place；存在任何歧义时，都应以 INT-02 或 INT-09a 拒绝操作。
• 将叶节点内容写入 index.md。 索引正文仅用于导航。叶节点内容应放在叶节点文件中。
• 提议自动化。 不要使用钩子、监视器或计划任务。每项操作都必须由用户明确请求。
• 运行用户未要求的操作。 除非用户提出要求，否则不要在 Validate 后接着运行 Rebuild。
• 在一次操作中混用布局模式。 intent.mjs 只解析一次，并在整个操作中遵循该模式。
• 在操作过程中重复读取同一 guide/ 文件。 每次操作读取一次即可。