如何快速编写 HVE Core 自定义 Prompt：${input}模板与Agent引用实战指南

如何快速编写 HVE Core 自定义 Prompt：${input}模板与Agent引用实战指南

【免费下载链接】hve-coreA refined collection of Hypervelocity Engineering components (instructions, prompts, agents, and skills) to start your project off right, or upgrade your existing projects to get the most out of GitHub Copilot项目地址: https://gitcode.com/GitHub_Trending/hv/hve-core

HVE Core是微软开源的 GitHub Copilot 组件精选库，提供指令（instructions）、提示词（prompts）、智能体（agents）和技能（skills），帮你把 Copilot 用到极致。本文带你从零上手编写 HVE Core 自定义 Prompt：掌握${input:变量}模板语法，学会通过agent字段把任务委托给专用 Agent，10 分钟写出团队可复用的工作流。

一、Prompt 是什么：单次执行的工作流定义

在 HVE Core 中，AI 组件分为三类，定位各不相同：

Prompt 文件统一放在.github/prompts/目录下，按包分子目录组织，例如：

.github/prompts/ ├── hve-core/ │ ├── pull-request.prompt.md │ └── rpi.prompt.md └── security/ └── your-prompt.prompt.md

在 Copilot Chat 中输入/即可唤起命令选择器，按文件名查找并调用你的 Prompt。🎯 完整入门说明见官方文档 docs/customization/prompts.md。

二、一键创建 Prompt 文件：命名与目录规范

新建 Prompt 只需 3 步：

1. 选位置：放入.github/prompts/<包名>/子目录，文件名使用小写短横线命名 +.prompt.md后缀
2. 起好名字：文件名就是/命令名，务必具体。❌workflow.prompt.md→ ✅security-plan-from-prd.prompt.md
3. 写内容：YAML frontmatter（元信息）+ Markdown 正文（提示词模板）

例如仓库自带的 PR 描述生成器 .github/prompts/hve-core/pull-request.prompt.md，它的 frontmatter 是标准写法：

description: 'Generate pull request descriptions from branch diffs' agent: agent argument-hint: "[branch=origin/main] [createPullRequest=false] [excludeMarkdown={true|false}]"

frontmatter 字段速查：

💡 命名规范、字段取值范围的完整标准见 docs/contributing/prompts.md。

三、${input:varName} 变量模板：让 Prompt 变成参数化工具

这是 HVE Core 自定义 Prompt 的核心技巧。变量语法有两种形态：

• ${input:varName}——必填，用户未提供时由 Copilot 从对话或附件中推断
• ${input:varName:defaultValue}——可选，带默认值

看一个代码审查 Prompt 的实战写法：

# Code Review: ${input:moduleName} Review the module at ${input:modulePath:src/} for the following criteria: * Adherence to ${input:styleguide:TypeScript} conventions * Error handling completeness * Test coverage gaps

三个变量各司其职：

• ${input:moduleName}必填，自动从上下文推断要审查的模块
• ${input:modulePath:src/}未指定时默认src/
• ${input:styleguide:TypeScript}默认按 TypeScript 规范

最佳实践：在正文中加一个## Inputs区块，把每个变量标注为(Required)或(Optional, defaults to ...)，团队成员一目了然。仓库里的 .github/prompts/hve-core/rpi.prompt.md 就是范例：

## Inputs * ${input:task}: (Required) Task description or target outcome. * ${input:continue}: (Optional) Resume the active task from its durable RPI artifacts.

四、agent 引用实战：把 Prompt 委托给专用 Agent

agent字段决定 Prompt 由谁执行，分两种用法：

4.1 内置模式：简单任务直接跑

省略agent时使用当前 Agent；若声明了tools，则默认回退为agent。

4.2 委托自定义 Agent：协议复用不重写

当任务复杂、已有专用 Agent 时，直接填 Agent 的name:值即可：

description: "Plans implementation tasks from a requirements document" agent: RPI Agent

委托后，Agent 的完整协议（阶段、步骤、工具限制）接管执行流程，Prompt 正文只负责提供上下文和范围，避免重复造轮子。例如上文的 RPI 工作流：

agent: RPI Agent # RPI 1. Use `${input:task}` as the primary task context and start with research readiness. 2. Sequence rpi-research, rpi-plan, rpi-implement, and rpi-review as needed.

这就是"逻辑在 Agent、上下文在 Prompt"的分层思想：团队改工作流只动 Agent，改调用入口只动 Prompt。🧩

五、进阶：#file: 注入完整文件内容

当 Prompt 需要参考团队规范文件时，用#file:在运行时注入全文：

Review the changes in #file:src/api/handlers.ts against the standards defined in #file:.github/instructions/coding-standards/typescript.instructions.md.

注意区分两种引用方式：

• ${input:xxx}—— 用户提供的运行时参数
• #file:路径—— 静态拉取的文件全文

另外跨组件引用请按名称引用（如name:字段值），不要硬编码路径，这样 Prompt 打包分发到其他环境后依然可用。

六、质量把关：让团队放心复用

写完后建议过三道质量门：

1. 结构自检：H1 标题 → Overview → Prerequisites → Workflow Steps → Success Criteria，步骤用祈使句、编号清晰
2. 用 hve-builder 技能评审：对已有 Prompt 运行 review 模式，它会给出目标、激活方式、架构与问题严重度的只读报告；新建时可用 create 模式一次走完"编写 + 质检"生命周期
3. 手动验证：按步骤手动走一遍流程逻辑，再用真实场景让 AI 执行，核对输出产物与规格一致

发布 Prompt 前运行npm run plugin:sync与npm run plugin:validate，可把新命令自动登记到根目录 plugin.json 清单中。

七、资源导航：继续深入 HVE Core

小结：HVE Core 自定义 Prompt =description说清用途 +${input:变量}参数化 +agent委托专用智能体。掌握这套组合拳，你的团队就能把重复性的 AI 工作流固化成一条/命令，人人可用、开箱即跑。✅

【免费下载链接】hve-coreA refined collection of Hypervelocity Engineering components (instructions, prompts, agents, and skills) to start your project off right, or upgrade your existing projects to get the most out of GitHub Copilot项目地址: https://gitcode.com/GitHub_Trending/hv/hve-core