agent-customization

Agent 自定义

决策流程

基元	适用场景
工作区指令	始终生效，适用于项目中的所有位置
文件指令	通过 applyTo 模式显式应用，或通过 description 按需应用
MCP	集成外部系统、API 或数据
Hooks	在 Agent 生命周期节点执行确定性的 shell 命令（阻止工具调用、自动格式化、注入上下文）
自定义 Agent	用于隔离上下文的子 Agent，或带有工具限制的多阶段工作流
提示词	带参数化输入的单一专注任务
技能	按需执行的工作流，附带捆绑资源（脚本/模板）

快速参考

请参阅参考文档，了解模板、领域示例、高级 frontmatter 选项、资源组织方式、反模式和创建检查清单。如果参考文档不够用，请加载各基元对应的官方文档链接。

类型	文件	位置	参考
工作区指令	copilot-instructions.md、AGENTS.md	.github/ 或根目录	链接
文件指令	*.instructions.md	.github/instructions/	链接
提示词	*.prompt.md	.github/prompts/	链接
Hooks	*.json	.github/hooks/	链接
自定义 Agent	*.agent.md	.github/agents/	链接
技能	SKILL.md	.github/skills/<name>/、.agents/skills/<name>/、.claude/skills/<name>/	链接

用户级：{{VSCODE_USER_PROMPTS_FOLDER}}/（.prompt.md、.instructions.md、*.agent.md；不包括技能） 自定义项会随用户的设置同步一起漫游

创建流程

如果需要探索或验证代码库中的模式，请使用只读子 Agent。如果 ask-questions 工具可用，请用它询问用户并澄清需求。

创建任何自定义文件时，请按以下步骤操作。

1. 确定范围

询问用户希望将自定义项放在哪里：

• 工作区：用于项目专属、团队共享的自定义项 → .github/ 文件夹
• 用户配置文件：用于个人的、跨工作区的自定义项 → {{VSCODE_USER_PROMPTS_FOLDER}}/

2. 选择合适的基元

根据用户需求，使用上方的决策流程选择合适的文件类型。

3. 创建文件

直接在适当的路径创建文件：

• 使用各参考文件中的位置表
• 按需添加必需的 frontmatter
• 按照模板添加正文内容

4. 验证

创建后：

• 确认文件位于正确位置
• 验证 frontmatter 语法（位于 --- 标记之间的 YAML）
• 检查 description 是否存在且有意义

边界情况

指令还是技能？ 这适用于大多数工作，还是特定任务？大多数 → 指令。特定 → 技能。

技能还是提示词？ 两者都会在聊天中显示为斜杠命令（输入 /）。包含捆绑资源的多步骤工作流 → 技能。带输入的单一专注任务 → 提示词。

技能还是自定义 Agent？ 所有步骤都使用相同能力 → 技能。需要隔离上下文（子 Agent 返回单一输出），或在不同阶段使用不同工具限制 → 自定义 Agent。

Hooks 还是指令？ 指令引导 Agent 行为（非确定性）。Hooks 则通过 PreToolUse 或 PostToolUse 等生命周期事件中的 shell 命令强制执行行为——它们可以阻止操作、要求批准或确定性地运行格式化程序。参见 Hooks 参考。

常见陷阱

description 是发现入口。 description 字段决定 Agent 是否加载某项技能、指令或 Agent。如果触发短语不在 description 中，Agent 就找不到它。使用“Use when...”模式，并加入具体关键词。

YAML frontmatter 解析失败却不报错。 值中未转义的冒号、用制表符代替空格，以及与文件夹名称不匹配的 name，都会导致静默失败，且不会显示错误消息。描述中包含冒号时，务必加引号：description: "Use when: doing X"。

applyTo: "**" 会占用上下文。 这表示“每次请求文件时都包含”——每次交互时，无论指令是否相关，都会将其加载到上下文窗口中。除非该指令确实适用于所有文件，否则请使用具体的 glob（**/*.py、src/api/**）。