VS Code Copilot 的 /init 技能深度解析：为 AI 编码代理自动生成 AGENTS.md 与聊天定制文件

VS Code 内置的 Copilot 扩展提供了一个名为 init 的 Agent 技能（/init），它通过探索代码库、识别项目约定，自动创建或更新 .github/copilot-instructions.md / AGENTS.md 等聊天定制文件，让 AI 编码代理在新项目中"开箱即 productive"。本文以仓库中 init 技能的 SKILL.md 为主体，结合其依赖的 agent-customization 参考文档与扩展源码中的注册配置，完整拆解这个技能的能力边界、四阶段工作流、内容编写原则，以及它与 /chronicle improve 等技能形成的闭环。读完本文，你将理解 VS Code 如何用一份 SKILL.md 把"给 AI 代理写项目说明"这一高频任务变成一条可重复执行的斜杠命令。

技能定位：一份内置在 Copilot 扩展中的 SKILL.md

在 VS Code 仓库中，这个技能的文件实体位于 extensions/copilot/assets/prompts/skills/init/SKILL.md。它并不是一个可执行脚本，而是遵循 VS Code Agent Skills 规范的一组提示词指令：YAML frontmatter 描述元数据，Markdown 正文定义代理执行该任务时应遵循的完整工作流。

从 extensions/copilot/package.json 中的 chatSkills 声明数组可以看到该技能的注册方式：

{
  "path": "./assets/prompts/skills/init/SKILL.md",
  "sessionTypes": [
    "local"
  ]
}

sessionTypes 限定为 "local" 意味着该技能只在本地会话类型中可用，与同列表中限定为 "local" + "copilotcli" 的 agent-customization 技能不同——init 目前只面向 VS Code 本地工作区场景提供。同一数组还登记了 create-prompt、create-instructions、create-skill、create-agent、create-hook 等"后续配套技能"，这正是 init 完成初始化后建议用户继续创建的对象。

Frontmatter 逐字段解析

init 技能的 frontmatter 只有四个字段：

---
name: init
description: Generate or update chat customization files for AI coding agents
argument-hint: Optionally specify a focus area or pattern to document for agents
disable-model-invocation: true
---

对照仓库内 Agent Skills 参考文档 中定义的 SKILL.md 格式，各字段含义如下：

字段	取值	作用
name	init	必填，1-64 字符的小写字母数字加连字符，必须与文件夹名一致；在聊天中输入 / 时显示为 /init
description	Generate or update chat customization files…	必填，代理据此判断技能用途的"发现面"
argument-hint	Optionally specify a focus area or pattern…	可选，用户调用 /init <参数> 时提示可补充聚焦领域或模式
disable-model-invocation	true	可选，禁用模型自动触发加载

disable-model-invocation: true 是这个技能的关键设计点。参考文档中给出的斜杠命令行为表说明了四个配置的差异：

配置	显示为斜杠命令	可被模型自动加载
默认（两字段均省略）	是	是
user-invocable: false	否	是
disable-model-invocation: true	是	否
两者都设置	否	否

因此 /init 只能由用户显式输入斜杠命令触发，模型不会在对话中悄悄加载并执行它——这是一个会实际创建/修改文件的"重操作"技能，交由用户显式发起更安全。同目录下 create-agent、create-skill 等技能也都设置了相同的 disable-model-invocation: true，形成统一的"用户显式调用"策略。该字段在扩展侧由 frontmatter 解析逻辑消费，例如 promptFileParser.ts 中导出的 disableModelInvocation 常量，以及 agentTypes.ts 中根据 config.disableModelInvocation 决定代理是否可被模型调用的分支逻辑。

核心目的：创建或更新两类聊天定制文件

技能正文开宗明义，/init 的目标是创建或更新"聊天定制文件"（chat customization files），分为两类：

1. 代理指令文件：.github/copilot-instructions.md 或 AGENTS.md——帮助 AI 编码代理理解代码库并立即投入工作；
2. 技能与自定义代理（skills and custom agents）——把常见任务自动化、或在代码库中强制执行特定约定。

技能对调用参数也做了明确约束：用户可以用参数调用命令，参数既可以是"针对某个定制文件的具体请求"，也可以对新项目而言是"项目本身的描述"。带参数调用时，要聚焦与该参数相关的定制内容；只创建或修改聊天定制文件，绝不允许开始执行参数中描述的开发任务（原文："Never start working on a task in the argument"）。这是对参数注入的典型防御——/init 帮我重构订单模块 不应该让代理去动手改代码，而应把"订单模块相关的约定"写进定制文件。

被调用时，技能还要求代理立即、简短地告知用户"正在探索代码库并着手创建/改进聊天定制文件"，若带参数则同时说明聚焦的领域或模式，并在需要时主动征求反馈。

四阶段工作流详解

阶段一：发现现有约定

技能给出的第一步是一个具体的文件发现搜索模式：

**/{.github/copilot-instructions.md,AGENT.md,AGENTS.md,CLAUDE.md,.cursorrules,.windsurfrules,.clinerules,.cursor/rules/**,.windsurf/rules/**,.clinerules/**,README.md}

这个 glob 一次性覆盖了 VS Code 自己识别的两种指令文件（.github/copilot-instructions.md、AGENTS.md，含笔误变体 AGENT.md），以及来自其他 AI 编码工具的约定文件（Claude Code 的 CLAUDE.md、Cursor 的 .cursorrules 与 .cursor/rules/**、Windsurf 的 .windsurfrules 与 .windsurf/rules/**、Cline 的 .clinerules 与 .clinerules/**），外加 README.md。这一步的意义在于：如果用户已经用别的工具维护过代理约定，/init 能"就地取材"地合并更新，而不是另起炉灶。

阶段二：并行探索代码库

第二步要求"通过子代理（subagent）探索代码库，必要时 1-3 个并行"。要挖掘的知识被明确限定为"让 AI 代理立刻 productive 所必需"的几类：

• 构建/测试命令——代理会尝试自动执行这些命令；
• 架构决策与组件边界；
• 区别于通用实践的项目特定约定；
• 潜在陷阱或常见开发环境问题；
• 体现典型模式的关键文件/目录。

同时要求清点既有文档（docs/**/*.md、CONTRIBUTING.md、ARCHITECTURE.md 等），目的是识别"应该链接、而非复制"的主题——这直接服务后面阶段三的第一条原则。

阶段三：生成或合并，遵循三条内容原则

这一步是技能的核心产出逻辑，规则分两层。

文件选择规则：

• 新建文件时优先 AGENTS.md 而非 .github/copilot-instructions.md；
• 如果用户已有其中任一文件，更新它，而不是再建新文件。

这与配套参考文档 agent-instructions.md 中的文件类型表一致：copilot-instructions.md 放在 .github/ 下、跨编辑器通用；AGENTS.md 放在根目录或子目录、支持 monorepo 层级，且被定位为开放标准；两者只选其一（"Use only one—not both"），同时存在两份正是该文档列出的反模式之首。

内容编写三原则（技能正文逐条列出了 agent-customization 技能的要求）：

1. Link, don't embed（链接而非嵌入）：工作区中已存在的文档不要复制，用 Markdown 链接指过去；
2. Minimal by default（默认最小化）：只收录"相关且代理难以自行发现"的内容，细节留给其他文档；
3. Concise and actionable（简洁且可行动）：每一行都要能指导行为。

对已有文件则要求"保留有价值内容、更新过时章节、去除重复"。

agent-instructions.md 还给出了生成 AGENTS.md / copilot-instructions.md 时应参照的模板骨架（Code Style / Architecture / Build and Test / Conventions 四个小节，且"只包含工作区真正需要的小节"），以及一份反模式清单：

• 同时使用两种指令文件；
• "Kitchen sink"——堆砌一切而非聚焦重点；
• 复制 README 而不是链接它；
• 写"显而易见的指令"——比如已经被 linter 强制执行的约定。

阶段四：迭代收敛

最后一步要求对模糊或不完整的章节主动向用户征求反馈；如果工作区很复杂，应建议为特定区域（如前端、后端、测试）分别创建独立的指令文件或技能，而不是一份巨型文档。

收尾动作：结果汇报与后续定制建议

工作流完成后，技能要求代理做两件收尾工作。

其一，打印成果表。 列出本次新增或修改的所有聊天定制文件，并对每个文件附一句"它为什么对 AI 编码代理有用"的说明。这让用户对生成的每个文件的价值一目了然，也便于团队评审时逐条确认。

其二，提出后续建议。 技能原文要求：定稿后，向用户建议下一步可创建的相关爱定——/create-(agent|hook|instruction|prompt|skill) …，并解释每个定制"是什么、在实际中如何使用"。这些建议命令在仓库中都是真实存在的配套技能，各自聚焦单一产物：

建议命令	产物	定位（摘自各技能 frontmatter description）
/create-agent	*.agent.md	为特定职责创建自定义代理
/create-skill	SKILL.md	打包可复用工作流
/create-instructions	*.instructions.md	按 applyTo 模式按需注入的指令
/create-prompt	*.prompt.md	带参数化输入的单点任务
/create-hook	*.json	在代理生命周期钩子上确定性执行 shell 命令

与 agent-customization 和 chronicle 技能的协作关系

init 技能并非孤立存在，从源码结构看它是整个"代理定制"技能簇的入口节点，有两处明确的跨技能引用。

引用 agent-customization（被引用方）。 技能正文写道："Use the related skill agent-customization for detailed information about the different types of customization files." agent-customization 技能 提供了一份原语选型决策表（agent instructions / File Instructions / MCP / Hooks / Custom Agents / Prompts / Skills 各自的适用场景）和一张"类型—文件—位置—参考文档"速查表：

类型	文件	位置
agent instructions	copilot-instructions.md、AGENTS.md	.github/ 或根目录
File Instructions	*.instructions.md	.github/instructions/
Prompts	*.prompt.md	.github/prompts/
Hooks	*.json	.github/hooks/
Custom Agents	*.agent.md	.github/agents/
Skills	SKILL.md	.github/skills/<name>/ 等

阶段三要求"Follow the guidelines in the agent-customization skill"，实际上就是把文件放置位置和 frontmatter 规范委托给这个工作流技能，而 init 自己只聚焦"探索代码库 + 生成/合并指令文件"这条主线——职责切分清晰。

被 chronicle 引用（引用方）。 chronicle 技能 的 /chronicle improve 工作流中有一条明确的回指："如果指令文件不存在，你应当创建它——在这种情况下，先分析代码库——查阅 init 技能并遵循其代码库探索方式，将其与第二步的会话历史发现结合，产出一份全面的指令文件。" 反过来，init 技能末尾也建议："如果会话历史可用，使用 chronicle 技能检查过往会话中的摩擦模式（friction patterns）——它能暴露仅靠代码库探索发现不了的项目特定约定或陷阱"，并向用户提及 /chronicle improve 作为迭代优化指令的途径。两个技能由此构成闭环：/init 用代码库视角冷启动定制文件，/chronicle improve 用真实会话摩擦数据做热修正。

VS Code 仓库自身就是 init 模式的范例

一个有意思的佐证是：VS Code 仓库本身就遵循了 init 技能所倡导的"Link, don't embed"原则。仓库根目录的 AGENTS.md 全文只有几行：声明本文件为 AI 编码代理提供 VS Code 代码库的指令入口，对详细的项目概览、架构、编码规范与验证步骤则直接链接到 .github/copilot-instructions.md，而不再重复。这正是技能阶段三"默认最小化 + 链接而非嵌入"两条原则的活样例：AGENTS.md 作为跨工具的入口指针保持极简，细节文档保持单一事实来源。

小结

/init 技能用一个文件展示了 VS Code 对"让 AI 编码代理在新仓库中快速上手"这一问题的产品化回答：

• 显式触发：disable-model-invocation: true 保证创建/修改文件的重操作只由用户主动发起；
• 兼容并包：发现阶段同时识别 VS Code、Claude、Cursor、Windsurf、Cline 五家工具族的约定文件，避免约定碎片化；
• 最小信息量：以"构建测试命令、架构边界、特殊约定、陷阱、代表性文件"五类知识为探索目标，产出遵循"链接不嵌入、默认最小、逐行可行动"三原则；
• 生态衔接：完成后可顺畅接入 /create-* 系列技能扩展定制，并通过 /chronicle improve 用会话摩擦数据持续迭代。

对使用者而言，在任意项目中输入 /init（可选附参数指定聚焦领域），即可获得一份经过代码库探索、去重合并、可直接提交进版本控制的代理定制文件；对扩展开发者而言，extensions/copilot/assets/prompts/skills/ 目录下的 init、agent-customization、chronicle、create-* 这一组 SKILL.md 与 package.json 中的 chatSkills 声明，是理解 VS Code Agent Skills 加载、注册与协作机制的完整可读样本。