玩转 GitHub Copilot 定制化：全栈架构指南

在复杂的软件组织中，“让 AI 自行猜测”不仅低效，更是风险。为了让 GitHub Copilot 输出一致、高质量的代码，团队必须学会像编排员工一样，编排 指令 (Instructions)、技能 (Skills)、提示词 (Prompts) 和 代理 (Agents)。

本指南提供了一套完整的框架，帮助您定义、组织和治理这些资源，构建健壮的 AI 辅助开发工作流。

---

1. 核心定义与区别

理解每个组件的专注点是有效编排的关键。

资源组件	定义与作用域	一句话核心 (Focus)
指令 (Instructions) *.instructions.md	“宪法” (Constitution)。静态的、项目/团队级的行为准则。告诉 Copilot 本仓库的约束、风格和“必须项”（Must-haves）。	规定 “应该怎么做” (规则与风格)。
技能 (Skills) SKILL.md	“能力” (Capabilities)。可复用的功能单元（工具/函数），封装了特定操作（如 API 调用、DB 搜索、执行测试）。	提供 “能做什么” (可调用工具)。
提示词 (Prompts) *.prompt.md	“模版” (Templates)。结构化的输入模式（上下文 + 指令 + 占位符），确保高频任务输出的稳定性。	规定 “怎么问” (交互模型)。
代理 (Agents) *.agent.md	“编排者” (Orchestrators)。自治单元，结合逻辑、Skills 和 Prompts 来执行多步工作流并管理状态。	负责 “谁来做，怎么组合” (编排)。

---

2. 协同工作流 (“闭环”)

在一个真实的工程环境中，这些组件是如何协同工作的？

1. 标准化 (Instructions)：架构团队在 .github/copilot-instructions.md 中编写全局强制规则（如“严禁密钥泄露”），在 .github/instructions/ 中编写主题规则（如“仅使用 React Hooks”）。这限制了所有输出的风格。
2. 赋能 (Skills)：平台团队实现健壮的 Skills（如 run-tests, check-ci-status），赋予 Agent 安全与环境交互的能力。
3. 模版化 (Prompts)：开发者为重复性任务创建 Prompt 模版（如“生成 PR 描述”、“单元测试模版”），确保输入的一致性。
4. 编排 (Agents)：自动化工程师定义 Agent。一个 Agent 可能会：
   • 选取一个 Prompt。
   • 查询遵循 Instructions 的 LLM。
   • 调用 Skill 执行副作用（如修改文件、运行 Lint）。
5. 验证与迭代：建立反馈闭环。如果 Agent 生成了不合规代码，更新 Instructions 或 Prompts。如果工具执行失败，修复 Skill。

---

3. 治理与组织策略

为了防止配置混乱，必须实行严格的所有权和边界管理。

关注点分离 (Separation of Concerns)

• Instructions：归 技术负责人/安全团队 所有。变更频率低，需严格审查。
• Skills：归 DevOps/基建团队 所有。关注可靠性与安全性（副作用管理）。
• Prompts：归 开发者 所有。快速迭代，关注开发体验。
• Agents：归 SRE/自动化团队 所有。关注工作流逻辑与错误处理。

优先级与冲突解决

• 强制规则：必须写在 .github/copilot-instructions.md 中。使用强硬措辞（”MUST”, “FORBIDDEN”）。
• 上下文注入：Prompts 应包含关键 Instructions 的摘要，确保即使在临时会话中，模型也能遵守全局策略。
• 事前检查：Agent 在提交变动前，必须调用“验证 Skill”（Linter/静态分析）进行合规性检查。

版本化与审计

• 配置即代码：所有 .github/ 变更必须走 PR 流程。
• 审计日志：执行副作用（如创建 PR）的 Agent 必须在标题/描述中明确标识（如“由 Agent X 生成”），并记录使用的 Prompt 输入。

部署与推广

• 沙盒测试：新 Agent/Prompt 先在沙盒环境或非关键分支测试。
• 灰度发布：逐步放开 Agent 的自动化权限（建议 -> 草稿 PR -> 自动合并）。

---

4. 典型场景示例

您的需求	实现策略
统一代码风格	Instructions (仓库级) + CI Skill (Linter) 进行校验。
半自动 PR 描述	Prompt 模版 (注入上下文) 由开发者触发 -> 人工审查。
自动修复漏洞	Agent 编排：vuln-scan (Skill) -> generate-fix (Prompt) -> verify-fix (Instruction校验) -> open-pr (Skill)。
复杂代码迁移	Agent 组合：code-search + refactor (Skills)，使用 Instructions 提供迁移规则，Prompts 生成代码。

---

5. 安全与合规

• 最小权限：与外部系统交互的 Skills 必须使用受限的凭证。
• 密钥屏障：Instructions 必须明确禁止输出 Secrets/凭证。
• 人机回环 (Human-in-the-loop)：高风险的 Agent 操作（如生产发布）必须包含人工审批步骤，或仅限生成草稿。

---

6. 生成器 Prompt (复用神器)

使用此 Meta-Prompt，为任何新项目瞬间生成标准化的目录结构。

# System Prompt: Generate VS Code Copilot Customization

You are an expert in configuring Github Copilot for VS Code. Your task is to analyze the current project's structure and generate a complete, strictly compliant `.github` configuration set for Copilot Customization.

## 1. Core Concepts & Definitions

Strictly adhere to these definitions and scopes:

- **Instructions** (`.instructions.md`): The "Constitution".
  - **Purpose**: Static, high-priority rules and constraints (e.g., "Must use async/await").
  - **Scope**: Repository-wide or specific to file types.
  - **Ownership**: Engineering Lead / Architect.

- **Skills** (`SKILL.md`): The "Capabilities".
  - **Purpose**: Reusable functional units/tools (e.g., "Run Test", "Search DB").
  - **Scope**: Callable by Agents.
  - **Ownership**: DevOps / Infra Team.

- **Prompts** (`.prompt.md`): The "Interaction Templates".
  - **Purpose**: Template for frequent inputs to ensure stable output (e.g., "Refactor Request").
  - **Scope**: User-triggered context injection.
  - **Ownership**: Developers.

- **Agents** (`.agent.md`): The "Orchestrators".
  - **Purpose**: Autonomous units that orchestrate Skills and Prompts to complete workflows.
  - **Scope**: Task execution.
  - **Ownership**: Automation / SRE.

## 2. Analysis Phase
- **Scan**: Read `README.md`, `package.json`, `requirements.txt`.
- **Identify**: Coding style, workflows, debugging tools, and testing frameworks.

## 3. Generation Phase (Strict Compliance)
Generate the following files in `.github/`. Use standard English.

### A. Instructions
- **`copilot-instructions.md`** (Global):
  - **Content**: Security (no secrets), Critical Conventions, Team Principles.
- **`.github/instructions/code-style.instructions.md`** (Topic):
  - **Content**: Detailed language patterns (e.g., Python 3-layer arch, Vue Composition API).
  - **Frontmatter**: `trigger: always_on` (if high priority).

### B. Skills (`.github/skills/<name>/SKILL.md`)
- **`.github/skills/dev-toolkit/SKILL.md`**:
  - **Content**: Essential CLI commands for Env Setup, Testing, Debugging, Deployment.
  - **Format**: Concise code blocks with comments.

### C. Prompts (`.github/prompts/<name>.prompt.md`)
- **`.github/prompts/dev-scenarios.prompt.md`**:
  - **Content**: 5-10 common scenarios (e.g., "New Component", "Debug API", "Write Test").
  - **Strategy**: Embed key instruction summaries into prompts to ensure compliance.

### D. Agents (`.github/agents/<name>.agent.md`)
- **`.github/agents/implementer.agent.md`**:
  - **Role**: "Implementation Specialist".
  - **Behavior**: Orchestrate skills (e.g., search -> modify -> test). Check instructions before action.
s
## 4. Governance Strategy (Include in comments/docs)
- **Separation**: Instructions = Rules; Prompts = Templates; Skills = Tools; Agents = Workers.
- **Validation**: All Agent outputs should ideally be verified (e.g., run `dev-toolkit` tests).

## 5. Output Format
Return the content for each file using standard artifact or code block formatting, specifying the file path.

总结

• 指令 = 规则 (稳定、高优)
• 提示词 = 交互 (灵活、模版)
• 技能 = 工具 (复用、受控)
• 代理 = 编排 (流程、自动化)

将 AI 配置视为一项严谨的工程实践——明确所有权、版本控制和验证机制——您就能将 Copilot 从一个智能的“自动补全工具”转变为值得信赖的“研发合伙人”。