mcpField
M
make-instructions

make-instructions

github.com/dotnetAgent 工作流14.8k47 次安装今天更新
代码仓库

关于 make-instructions

用于创建范围明确的 VS Code `.instructions.md` 文件，为 Copilot 提供代码库特定背景。该技能涵盖范围调查、避免重复现有规则、编写带 YAML 前置内容的文件，以及验证配套评测。

主要功能

  1. 01调查适用范围及现有指令
  2. 02选择文件位置和名称
  3. 03编写含 YAML 前置内容的指令
  4. 04创建并验证配套评测
  5. 05检查规则重复与配置问题

适用场景

  1. 01记录特定代码区域的约定
  2. 02添加基于文件模式的 Copilot 指导
  3. 03检查指令范围及应用方式
  4. 04为新指令准备评测

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dotnet/efcore --skill make-instructions

安装后在 Claude Code 中输入/make-instructions确认已加载。

详细介绍

创建基于文件的指令

此技能可帮助你搭建 VS Code 基于文件的指令（.instructions.md 文件），为 Copilot 提供代码库特定部分的背景知识。系统会根据 glob 模式或语义匹配自动应用这些文件，让 Copilot 在处理匹配的文件时获得特定领域的上下文。

何时不应使用

  • 设置项目范围的指令——改用 .github/copilot-instructions.md 或 AGENTS.md
  • 创建包含结构化步骤的可复用 Agent 工作流——改用 Agent Skills
  • 添加需要按需调用的指令——改用 Agent Skills

工作流

步骤 1：调查主题

了解指令所涵盖的范围。确定：

  • 指令适用的文件或文件模式
  • 该范围内的关键约定、模式或架构规则
  • Copilot 应避免的常见陷阱
  • 仅凭代码无法发现的领域知识

阅读适用于相同路径的全仓库指令文件，并明确列出排除项。即使这些规则与限定范围的示例相关，也不要在新文件中重复；只包含在更窄范围内更具体或有实质差异的指导。

如果范围不明确或与现有指令重叠，请向用户澄清。

步骤 2：选择文件位置

指令文件默认放在 .github/instructions/ 中。选择一个描述性文件名：

.github/instructions/<topic>.instructions.md

例如：csharp-style.instructions.md、query-pipeline.instructions.md、test-conventions.instructions.md

步骤 3：使用 YAML frontmatter 生成文件

创建文件，并添加必需的 YAML frontmatter 标头：

---
name: '<Display Name>'              # Optional. Display name in the UI. Defaults to filename.
description: '<Short description>'  # Optional. Shown on hover. Also used for semantic matching.
applyTo: '<glob pattern>'           # Optional. Glob pattern relative to workspace root. Omit to require manual attachment or rely on semantic matching only.
---

常见的 applyTo 模式：

  • **/*.cs — 所有 C# 文件
  • test/** — 特定文件夹下的文件
步骤 4：编写正文内容

编写简洁且可执行的 Markdown 内容。遵循以下原则：

  • 简洁明了——指令会占用上下文窗口；只包含 Agent 本身无法了解的内容
  • 具体明确——使用明确的规则，而非含糊的指导
  • 提供示例——展示推荐与应避免模式的简短代码片段非常有效
  • 说明原因——如果规则的缘由不明显，应说明原因，帮助 Agent 正确处理边缘情况
  • 跳过由 Linter 强制执行的规则——不要重复格式化工具和 Linter 已能检查的内容
  • 使用 Markdown 链接引用提供更多背景信息的特定文件或 URL

建议的章节（根据需要调整）：

  1. — 描述该领域的单行标题
  2. 背景段落 — 简要说明该范围的内容及这些规则的重要性
  3. 指南 / 约定 — 具体规则的项目符号列表
  4. 示例 — 展示推荐与应避免模式的简短代码块（可选）
  5. 关键文件 — 用于了解项目结构的重要文件表格（可选）
  6. 常见陷阱 — 需要避免的问题（可选）
第 5 步：编写并验证评估测试

创建 eng/harness-evaluation/instructions/<id>/eval.yaml，其中 <id> 是相对于 .github/instructions/ 的指令路径，去掉后缀并将嵌套路径分隔符替换为 --。

遵循 eng/harness-evaluation/README.md 中的编写和验证规则。练习指令中独有的指导内容，并确保处理组的效果显著优于省略指令的对照组。

首次编写时，请先生成并检查所需的指令和评估文件，再运行行为对比。

创建文件后，请确认：

  • 文件位于 .github/instructions/（或已配置的指令文件夹）中
  • 文件名以 .instructions.md 结尾，且只包含小写字母、数字和连字符
  • YAML frontmatter 有效
  • applyTo glob 与预期文件匹配
  • 内容简洁（目标为少于 500 行或 5000 个 token）——冗长的指令会降低效果
  • 不包含机密信息、令牌或内部 URL
  • 指令未重复 .github/copilot-instructions.md 或 .agents/skills/ 中已有的内容
  • 配套的评估能证明这些行为在省略指令的对照组中无法稳定实现

常见问题

问题解决方案
applyTo 范围过广使用具体的 glob；** 会匹配每个文件，浪费上下文
缺少 applyTo如果没有它，指令就不会自动应用——需要手动附加，或通过 description 进行语义匹配
指导内容含糊将“编写良好的测试”替换为类似“使用 [ConditionalFact] 方法添加正向和负向测试用例”的具体要求

评论

支持 Markdown