---
title: "Prompt Files"
description: "把重复的 Copilot Chat 任务沉淀成可调用、可审查、可维护的 .prompt.md 文件。"
verifiedAt: "2026-05-06"
---

Prompt files（提示词文件）不是收藏提示词的文件夹，而是把重复工作变成可调用命令。VS Code 官方文档把它描述为独立 Markdown 文件：你在 Chat 里手动调用，它再把任务目标、上下文和执行约束交给 Copilot。

> [!IMPORTANT]
> 一句话决策：**长期规则写 instructions，重复任务写 prompt file，一次性问题直接问**。三个层级混用是商业项目里 Copilot 不稳定的最常见原因。

> [!TIP]
> **阅读目标**：读完本章，你应该能判断一个任务是否值得做成 `.prompt.md`，并能写出不会污染长期上下文的 prompt file。

## 1. 它解决什么问题

Prompt file 适合把团队会反复发出的 Chat 请求标准化。例如：

- 生成 PR 描述。
- 为一次重构补回归测试。
- 按发布检查清单复检文档。
- 为新组件生成最小实现。
- 对 REST API 做安全审查。
- 把迁移任务拆成计划、diff、测试和回滚。

它和 custom instructions 的区别很关键：

- **Custom instructions** 自动应用，适合项目长期规则。
- **Prompt files** 手动调用，适合重复但不是每次都需要的任务。
- **普通 prompt** 适合一次性问题，不需要沉淀。

```mermaid
flowchart TD
    Task["要告诉 Copilot 的内容"] --> Stable{"每次任务都必须遵守?"}
    Stable -->|是| Instruction["写进 instructions"]
    Stable -->|否| Repeat{"同类任务会重复出现?"}
    Repeat -->|否| Adhoc["直接在 Chat 里提问"]
    Repeat -->|是| NeedsScript{"需要脚本、示例或资源?"}
    NeedsScript -->|否| PromptFile["写成 prompt file"]
    NeedsScript -->|是| Skill["升级为 agent skill"]

    style Instruction fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style PromptFile fill:#dcfce7,stroke:#16a34a,stroke-width:2px
    style Skill fill:#fef3c7,stroke:#d97706,stroke-width:2px
```

## 2. 放在哪里

VS Code 官方默认位置：

- 工作区级 prompt files：`.github/prompts/`
- 用户级 prompt files：VS Code 用户数据，跟随当前 profile

团队教程里默认推荐先放工作区级 `.github/prompts/`。理由很简单：它能跟代码一起 code review，也能让新人打开仓库后直接复用。

如果是只属于个人的写作习惯、提交偏好、解释风格，不要塞进仓库。放到用户级，避免把个人工作流误当成团队规范。

## 3. 文件格式

Prompt file 使用 `.prompt.md` 扩展名。YAML frontmatter 是可选的，但商业项目建议至少写 `description`，让调用者知道这个命令解决什么问题。

一个最小可用例子：

```md
---
description: "Add regression tests"
agent: "agent"
tools:
  - "search/codebase"
---

Review the current diff and add regression tests for the changed behavior.

Use these constraints:

- Prefer focused tests that fail before the fix.
- Do not rewrite unrelated tests.
- Mention any behavior that cannot be tested locally.
```

官方支持的常用 frontmatter 字段包括：

- `description`：prompt 的简短说明。
- `name`：在 Chat 输入 `/` 后使用的名称；未指定时用文件名。
- `argument-hint`：提示调用者应该补什么参数。
- `agent`：运行 prompt 的 agent，例如 `ask`、`agent`、`plan` 或自定义 agent。
- `model`：指定运行模型；不指定时使用当前模型选择器。
- `tools`：限制或声明这个 prompt 可用的工具。

正文就是正常 Markdown。需要引用仓库文件时，用相对链接；需要引用工具时，VS Code 支持 `#tool:<tool-name>` 语法。

## 4. 写作结构

高质量 prompt file 通常有 5 个块：

1. **目标**：这次任务要交付什么。
2. **输入**：调用者必须提供什么路径、issue、diff、日志或限制。
3. **过程**：Copilot 应该先看什么，再改什么，再验证什么。
4. **边界**：哪些文件、行为、权限不能碰。
5. **输出**：最后必须给哪些证据，例如测试命令、风险、回滚方式。

不要写成口号。比如“写得专业一点”没有工程含义；“按当前 diff 生成 PR description，包含用户影响、测试证据和回滚说明”才可执行。

## 5. 适合沉淀的任务

优先沉淀这些：

- **PR 模板化**：从 diff 生成变更摘要、测试证据、风险提示。
- **测试补齐**：针对 bug fix 生成最小回归测试。
- **文档复检**：检查 frontmatter、链接、标题层级、移动端可读性。
- **迁移计划**：把升级任务拆成依赖、步骤、验证和回滚。
- **安全审查**：围绕认证、授权、输入校验、日志脱敏出清单。
- **发布前 QA**：要求 Copilot 只基于 build、lint、screenshot 和 diff 下结论。

暂时不要沉淀这些：

- 一次性追问。
- 已经过期的临时事故背景。
- 密钥、内部地址、客户数据。
- 和仓库事实无关的个人偏好。
- 会要求 Copilot 自动执行危险操作的 prompt。

<details>
<summary>深读：prompt file 为什么不能替代 instructions</summary>

Prompt file 是手动调用的任务入口，不会自动给所有请求加规则。如果你把测试框架、代码风格、目录边界只写进 prompt file，Copilot 在普通 Chat、inline edit 或 agent mode 里仍然可能不知道这些约束。

稳定规则应该进 instructions；只有当任务本身需要一套可重复步骤时，才写 prompt file。
</details>

## 本章自检

写完一个 prompt file 后，用这 5 个问题检查：

1. 它是否解决一个会重复出现的具体任务？
2. 它是否明确说明输入、过程、边界和输出？
3. 它是否没有写入密钥、客户数据或内部敏感地址？
4. 它是否只在需要时调用，而不是伪装成长期规则？
5. 它是否能用一个真实 diff、issue 或文档变更跑通？

通过标准：团队成员不用口头解释，也能用同一个 prompt file 得到结构相近、可验证的结果。

## 官方来源

- [Use prompt files in VS Code](https://code.visualstudio.com/docs/copilot/customization/prompt-files) —— VS Code 官方 prompt file 位置、格式和 frontmatter。
- [Customization](https://code.visualstudio.com/docs/copilot/concepts/customization) —— VS Code 官方定制能力总览。
- [About customizing GitHub Copilot responses](https://docs.github.com/en/copilot/concepts/prompting/response-customization) —— GitHub 官方响应定制概念页。

## 接下来去哪

<Cards>
  <Card title="仓库自定义指令" description="把长期稳定规则放回 instructions。" href="/docs/github-copilot/official/06-context-customization/repository-instructions" />
  <Card title="Skills、Hooks、Plugins" description="当 prompt file 需要脚本、资源或分发时继续升级。" href="/docs/github-copilot/official/06-context-customization/skills-hooks-plugins" />
</Cards>
