一、什么是 Prompt 文件？
你已经学会了用 Agent 定义 AI 的“专业身份”（第一节），用 Instructions 为 AI 设定“全局行为准则”（第二节）。但在日常开发中，还有一些频繁执行的标准化任务，比如：
- “请审查这段代码的安全性”
- “为这个函数生成单元测试”
- “写一个符合 Conventional Commits 规范的提交信息”
这些任务流程固定、要求明确，每次都要重新输入一长串提示词，既低效又容易遗漏关键要求。
Prompt 文件正是为了解决这个问题——它把常用的任务提示词保存为可复用的模板，你可以通过/命令一键调用，Copilot 会自动加载模板内容（包括变量占位符、工具权限等），让你以最少的输入完成重复性工作。
💡 官方定义：Prompt 文件是存储在仓库中的可重用提示模板，用于标准化特定任务的 AI 交互。你可以在 Copilot Chat 中通过
/菜单选择，或直接输入/文件名来调用。
二、Prompt 在配置体系中的定位
为了更好地理解 Prompt 的作用，我们重新审视整个 Copilot 定制化体系：
| 定制功能 | 文件类型与位置 | 触发方式 | 核心用途 | 类比 |
|---|---|---|---|---|
| 自定义指令 | .github/copilot-instructions.md | 自动（每次对话都加载） | 全局背景规则（编码规范、架构原则） | 公司的《员工手册》 |
| 自定义代理 | .github/agents/*.agent.md | 手动选择（下拉菜单或@agent-name） | 拥有专属角色、工具权限的专家 | 特种兵编制 |
| 提示文件 | .github/prompts/*.prompt.md | 手动调用（/prompt-name） | 标准化、可交互的重复任务模板 | 作战指令卡 |
| 代理技能 | .github/skills/<skill-name>/SKILL.md | 自动/手动 | 封装脚本和资源的复杂任务模块 | 战术工具包 |
Prompt 是最轻量、最直接的复用方式：它不改变 AI 的身份（Agent 改变身份），不改变全局规则（Instructions 改变背景），只是把一段精心设计的提示词保存下来，并支持变量交互——让你每次调用时可以临时填入不同的参数。
三、.prompt.md 文件结构与 Frontmatter 详解
*.prompt.md文件与agent.md、instructions.md一样，由YAML Frontmatter和Markdown 内容两部分组成。下面是支持的 Frontmatter 字段。
3.1 name（可选，推荐配置）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 在 Copilot Chat 的/菜单中显示的名称 |
| 默认值 | 文件名（不含.prompt.md） |
示例：
name:"代码审查（安全版）"3.2 description（可选，强烈推荐）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 简要描述该 Prompt 的作用，帮助你在菜单中区分不同 Prompt |
| 长度建议 | 10-200 字符 |
示例：
description:"根据 OWASP Top 10 审查代码中的安全漏洞"3.3 agent（可选）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 指定调用此 Prompt 时使用哪个 Agent（如@security-agent） |
| 默认值 | 当前活跃的 Agent |
示例：
agent:"security-agent"为什么要指定 Agent？
如果你的 Prompt 需要特殊的工具权限或角色背景（例如安全审查需要只读权限，不能修改文件），可以绑定一个已经配置好的 Agent。这样调用 Prompt 时，Copilot 会自动切换到该 Agent 模式。
3.4 model（可选）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 指定调用此 Prompt 时使用的 AI 模型 |
| 可选值 | gpt-4o、gpt-4-turbo、gpt-3.5-turbo等（取决于你的订阅） |
| 默认值 | 用户当前选择的模型 |
示例：
model:"gpt-4o"3.5 tools（可选）
| 属性 | 说明 |
|---|---|
| 类型 | string 或 string[] |
| 用途 | 为此 Prompt 临时启用的工具列表（覆盖当前 Agent 的工具设置） |
| 默认值 | 不启用额外工具（继承 Agent 的配置） |
示例：
tools:["read","grep","search"]⚠️ 注意：如果当前 Agent 不支持工具（例如
ask模式），指定tools后 Copilot 会自动将模式升级为agent。
3.6 argument-hint（可选）
| 属性 | 说明 |
|---|---|
| 类型 | string |
| 用途 | 当你调用 Prompt 时，在输入框中显示的占位提示文字 |
| 默认值 | 无 |
示例：
argument-hint:"<请粘贴要审查的代码或输入文件路径>"这个字段可以提升用户体验，让团队成员知道该 Prompt 期望什么输入。
四、核心机制：使用${input:变量名}实现交互
Prompt 文件与普通提示词最大的区别在于支持变量占位符。通过${input:变量名}语法，你可以在模板中定义需要用户临时填写的参数。
4.1 基本语法
${input:<变量名>:<可选默认值/占位文本>}- 变量名：必填，用于在模板中引用用户输入的值
- 默认值/占位文本：可选，显示在输入框中作为提示或默认内容
4.2 实际示例
假设你要创建一个“生成 React 组件”的 Prompt：
--- name: "创建 React 组件" description: "生成一个带有 TypeScript 类型定义的 React 函数组件" --- 请创建一个名为 `${input:组件名:例如 UserCard}` 的 React 函数组件。 **Props 定义**： ```typescript interface ${input:组件名}Props { ${input:Props类型:例如 user: User; onClick?: () => void} }组件要求：
- 使用 React 18+ 的函数组件
- 包含 JSDoc 注释
- 使用 Tailwind CSS 进行样式布局
当你调用 `/创建 React 组件` 时，Copilot 会依次弹出三个输入框： 1. “请输入组件名” (默认显示 `例如 UserCard`) 2. “请输入 Props 类型” (默认显示 `例如 user: User; onClick?: () => void`) 你填写后，AI 就会基于这些参数生成最终代码。 ### 4.3 变量作用域 变量在单个 Prompt 文件的 Markdown 内容中全局有效。你可以在多处使用同一个变量名，用户只需输入一次，所有引用位置都会被替换。 ## 五、编写高质量 Prompt 的实战技巧 Frontmatter 定义了交互方式，但 Prompt 的核心价值在于 **Markdown 内容**。以下是提升效果的三条核心技巧。 ### 5.1 明确角色与约束 在内容开头，为 AI 设定清晰的角色和必须遵守的约束： ```markdown ## 角色 你是一位资深后端工程师，专注于 **Node.js + TypeScript** 项目。 ## 约束 - 严格遵循项目的 `.github/copilot-instructions.md` 中的编码规范 - 不要使用 `any` 类型 - 必须处理所有异步操作的错误 - 输出只包含代码和必要注释，不要添加额外解释5.2 提供输入格式和示例
如果 Prompt 需要处理用户提供的代码片段或数据，明确告知 AI 期望的输入格式，并给出正反例：
## 输入格式 用户会提供一个函数或一段代码块。请基于它生成单元测试。 ## 好的示例 输入： ```typescript function add(a: number, b: number): number { return a + b; }输出应包含：
- 正常情况测试
- 边界情况（如负数、零）
- 类型错误测试
### 5.3 结构化输出要求 明确要求 AI 按固定格式输出，便于阅读和复制： ```markdown ## 输出格式 请按以下结构输出： ### 1. 问题列表 - [严重] 问题描述 + 行号 - [一般] 问题描述 ### 2. 修复建议 对每个问题给出修改后的代码片段 ### 3. 总体评价 - 优点： - 改进空间：六、完整实战示例：security-review.prompt.md
下面是一个可以直接使用的安全审查 Prompt，结合了所有知识点：
--- name: "安全审查" description: "基于 OWASP Top 10 检查代码中的安全漏洞" agent: "security-agent" tools: ["read", "search", "grep"] argument-hint: "<请粘贴代码或输入文件路径>" model: "gpt-4o" --- ## 🎯 角色 你是一位应用安全专家，精通 OWASP Top 10 漏洞和常见攻击模式。 ## 📥 输入 用户会提供一段代码（或文件名）。你需要分析这段代码。 ## ✅ 审查清单 请检查以下项目： 1. **注入漏洞**：SQL 注入、命令注入、NoSQL 注入 2. **认证与授权**：是否有硬编码凭证、未检查权限的 API 3. **敏感数据暴露**：是否记录了密码/token、未加密传输 4. **XSS**：用户输入是否被安全转义 5. **不安全反序列化**：是否使用了 `eval()`、`new Function()` 等 ## 📤 输出格式（严格按此格式） ### 🔴 严重漏洞（Critical） - 漏洞描述 + 具体代码行 - 攻击场景（攻击者如何利用） - 修复方案（代码示例） ### 🟡 高危问题（High） （同上结构） ### 🔵 最佳实践偏离（Info） - 建议改进的地方（无安全风险但影响健壮性） ### ✅ 结论 - 是否建议合并：是 / 否（并说明理由） ## ⚠️ 约束 - 不要输出任何修改后的完整文件，只输出审查报告 - 如果不确定是否存在漏洞，标记为“需要人工确认”并说明原因 - 所有修复示例必须使用参数化查询或安全 API，禁止使用字符串拼接七、部署与使用
7.1 存放位置
在仓库根目录下创建.github/prompts/文件夹，将所有*.prompt.md文件放入其中：
your-repo/ ├── .github/ │ ├── agents/ │ │ └── security-agent.agent.md │ ├── instructions/ │ │ └── backend.instructions.md │ ├── prompts/ │ │ ├── security-review.prompt.md │ │ ├── generate-test.prompt.md │ │ └── write-commit-message.prompt.md │ └── copilot-instructions.md └── src/7.2 调用方法
- 斜杠命令：在 Copilot Chat 输入框中输入
/security-review（文件名，不含扩展名），然后按回车。如果 Prompt 定义了argument-hint，光标会自动定位到参数输入位置。 - 菜单选择：输入
/，从弹出的列表中选择“安全审查”。 - 带参数调用：可以直接输入
/security-review 待审查的代码片段，参数会作为${input}变量的默认值。
7.3 共享
将.github/prompts/目录提交到 Git 仓库后，所有克隆该仓库的团队成员都可以使用这些 Prompt。这非常适合团队标准化代码审查流程、测试模板等。
八、Prompts vs. Agents vs. Instructions 对比总结
| 维度 | Instructions | Agents | Prompts |
|---|---|---|---|
| 作用 | 提供全局背景规则 | 定义专业身份和权限 | 标准化具体任务流程 |
| 触发方式 | 自动（每次对话） | 手动选择（下拉菜单或@） | 手动调用（/命令） |
| 是否支持变量交互 | 否 | 否（但可通过对话传递） | 是（${input}语法） |
| 典型用途 | 编码规范、架构原则 | 多步骤复杂任务（如重构、迁移） | 单一重复任务（如审查、生成测试） |
| 文件位置 | .github/copilot-instructions.md | .github/agents/*.agent.md | .github/prompts/*.prompt.md |
使用建议：
- 全局规则用Instructions
- 需要特定工具权限或持久化角色的用Agent
- 标准化、可交互的重复性任务用Prompts
三者可以组合使用：一个 Prompt 可以指定使用某个 Agent（通过agent字段），该 Agent 又继承了 Instructions 的全局规则。
九、参考资料
- GitHub Docs: Using prompt files with Copilot Chat
- GitHub Blog: Customizing GitHub Copilot with prompts and slash commands
- GitHub Docs: About custom agents
- GitHub Docs: Custom instructions for GitHub Copilot
以上是重新整理后的第三节，格式与前两节完全一致（包含二级标题、三级标题、表格、代码块、对比总结、参考资料）。现在可以向用户交付了。
