EF Core 仓库的 make-skill 技能详解如何为 GitHub Copilot 创建符合 Agent Skills 规范的 AI 技能【免费下载链接】efcoreEF Core is a modern object-database mapper for .NET. It supports LINQ queries, change tracking, updates, and schema migrations.项目地址: https://gitcode.com/GitHub_Trending/ef/efcore本文以 EF Core 仓库中 .agents/skills/make-skill/SKILL.md 为核心系统讲解 Agent Skills 的目录规范、YAML frontmatter 字段、SKILL.md 正文结构、8 步创建工作流与多模型测试方法论。读完后你能够按照该仓库已验证的实践为一个 .NET 项目从零搭建一个可被 AI Agent 正确触发、可验证、可迭代的技能并掌握避免常见反模式的完整清单。Agent Skills 是什么make-skill 又是什么Agent Skills 是一种轻量级、开放格式的技能规范用于用专家知识 工作流扩展 AI Agent 的能力。每个技能就是一个目录核心是一份带 YAML frontmatter 的SKILL.mdAgent 依据其中的name和description判断何时触发该技能。make-skill本身是一个元技能它不是一个领域知识技能而是教会 Agent如何创建新的技能。它的 frontmatter 自述了触发条件--- name: make-skill description: Create new Agent Skills for GitHub Copilot. Use when asked to create, scaffold, or add a skill. Generates SKILL.md with frontmatter, directory structure, and optional resources. ---从源码结构看EF Core 仓库在 .agents/skills/ 目录下已经落地了十余个技能覆盖 EF Core 自身开发场景change-tracking、query-pipeline、migrations、scaffolding、update-pipeline、model-building、testing、triage等以及仓库工程化场景make-github-actions-workflow、run-apichief、servicing-pr、tooling。可以说make-skill就是这些技能的生成器它的每一步都对应了仓库内现成技能的组织方式。什么时候不该用 make-skill文档明确列出了两个不适用场景这在技能设计中很关键——避免什么都做成 skill创建自定义 Agent应使用agents/目录模式仓库中对应的技能是 make-custom-agent/SKILL.md添加语言级、框架级或模块级编码规范应使用基于文件的作用域指令file-based instructions而不是打包成技能。这条边界划分的意义在于技能是按需加载的工作流 知识而编码规范是常驻约束两者的注入机制不同混用会导致上下文浪费或触发混乱。四条核心设计原则在动笔之前make-skill要求牢记四条原则原文档 Key Principles 一节Frontmatter 是触发关键name和description决定技能何时被触发——必须清晰且全面要能匹配用户的自然语言表达简洁至上只写 Agent 不知道的东西上下文窗口是所有技能共享的稀缺资源指令要有稳定价值只包含稳定、不易被搜索到、且对该技能范围内的任何任务都可用的信息不重复同一条信息要么在SKILL.md中要么在 reference 文件中不能两处都有。第四条原则与 anti-patterns.md 中的 Bloated SKILL.md 一节互为印证编排型orchestratingSKILL.md 应保持 2K–4K token 的精简以便 Agent 有足够上下文预算做实际工作深度内容应下沉到references/*.md按需加载。目录结构规范一个技能应该长什么样最小结构一个技能最少只需要一个文件.agents/skills/skill-name/ ├── SKILL.md # Required: instructions metadata完整结构含可选目录按需扩展后的完整目录布局.agents/skills/skill-name/ ├── SKILL.md ├── scripts/ # 可选Agent 可以执行的脚本 ├── references/ # 可选REFERENCE.md详细技术参考、FORMS.md表单模板或结构化数据格式、领域指令文件 └── assets/ # 可选模板、资源及其他非可执行、非 Markdown 数据文件仓库中make-skill自身就采用了这种结构它的 references/ 目录下放着testing-patterns.md和anti-patterns.md两个深度参考文件正文只在第 8 步引用它们而不重复内容——正是不重复原则的示范。八步创建工作流从调研到多模型验证这是make-skill的核心操作手册。下面完整继承原文档的步骤并结合仓库实例补充说明。第 1 步调研主题先利用仓库内容、现有文档和外部资料建立对主题的深入理解。调研完成后用一组自检清单验证是否够格动手能否用一段话说清这个技能做什么能否列出 3–5 个技能适用的具体场景能否识别该主题的常见坑与误解能否给出带明确校验点的分步工作流是否准备好深入主题的检索查询能否判断技能应该是用户可调用还是仅背景知识。若存在歧义、理解缺口或多种可行方案先向用户澄清再进入创建阶段。同时评估该任务是否更适合做成自定义 Agent、Agentic 工作流、复用已有技能或拆分为多个更窄的技能——如有相关发现应主动与用户讨论。第 2 步创建技能目录按照上文的最小结构创建.agents/skills/skill-name/SKILL.md。第 3 步生成带 frontmatter 的 SKILL.mdfrontmatter 的完整字段定义如下name和description必填其余可选--- name: skill-name description: description of what the skill does and when to use it user-invocable: Optional, defaults to true. Set to false for background knowledge skills. argument-hint: Optional, guidance for how agents should format arguments when invoking the skill. disable-model-invocation: Optional, set to true to prevent agents from invoking the skill and only allow to be used through manual invocation. compatibility: Optional, specify any environment, tool, or context requirements for the skill. metadata: Optional, key-value mapping for additional metadata that may be relevant for discovery or execution. allowed-tools: Optional, list of pre-approved tools that agents could use when invoking the skill. ---字段必填说明name是技能名必须与目录名完全一致见第 7 步命名规则description是说明做什么 何时用是模型自动触发的唯一依据user-invocable否默认true背景知识型技能设为falseargument-hint否指导 Agent 调用技能时如何组织参数disable-model-invocation否设为true后禁止模型自动调用仅允许手动调用compatibility否声明环境、工具或上下文前提避免硬编码假设metadata否供发现或执行使用的附加键值元数据allowed-tools否预批准工具列表仓库中 change-tracking/SKILL.md 是一个仅背景知识技能的真实样例--- name: change-tracking description: Implementation details for EF Core change tracking. Use when changing InternalEntityEntry, ChangeDetector, SnapshotFactoryFactory, or related entity state, snapshot, or property accessor code. user-invocable: false ---其正文则展示了推荐结构的完整落地一段话概述 Core Components核心组件StateManager、InternalEntityEntry等Testing给出真实测试路径test/EFCore.Tests/ChangeTracking/与test/EFCore.Specification.Tests/GraphUpdates/Common Pitfalls表格 Validation小节。第 4 步组织正文小节正文推荐包含以下小节Following this files structure 即以make-skill自身为范本人类可读的技能名H1一段话描述超出 description 之外的成果When Not to Use可选排除场景列表Inputs and Outputs如适用示例输入与预期输出Workflow带检查点的编号步骤Testing如适用如何为技能输出编写自动化测试Validation如何确认技能生效Common Pitfalls可选已知陷阱与规避方法。第 5 步按需填充可选目录按前文完整结构一节创建scripts/、references/、assets/只建真正需要的目录。第 6 步编写脚本仅脚本驱动型技能若技能需要可执行脚本规范要求首选 PowerShell也可用 Python 或 JavaScript使用标准param块并提供默认值确保脚本输出清晰、结构化、可解析的控制台内容分节标题、状态行状态用 Emoji 表达✅ 绿 / ⚠️ 黄 / 红Fail-closed失败关闭错误处理—— 未知Unknown≠ 健康Healthy绝不允许把 API 调用失败计为成功应返回 Unknown 并将其从阳性计数中剔除。第 7 步校验技能命名校验规则四条硬性约束不能以连字符开头或结尾不能包含连续连字符长度为 1–64 个字符YAML frontmatter 中的name必须与目录名完全一致。创建完成后的完整验证清单frontmatter 字段合法SKILL.md不超过 500 行、5000 token超出则拆分为 reference 文件文件引用使用相对路径指令可执行、足够具体指令不与 .github/copilot-instructions.md 或.github/instructions/下已有内容重复工作流是带明确检查点的编号步骤存在 Validation 小节且含可观察的成功标准不含密钥、token 或内部 URLCommon Pitfalls 相关且附解决方案可选目录使用得当脚本优雅处理边界情况输出结构化结果与有帮助的错误信息。值得注意第 4 条查重规则.github/copilot-instructions.md是仓库级全局指令技能不得复述其中内容——这也是上下文窗口是共享的原则在仓库层面的具体化。第 8 步用多模型子 Agent 测试原文档第 8 步直接引用 references/testing-patterns.md其流程如下从 2–4 个不同模型家族中各选旗舰模型跳过 fast/cheap 档要的是每个家族最强的推理给每个子 Agent 相同的测试提示要求其实际执行该技能通过task工具并配合model参数并行启动综合结果多模型共识2 个以上模型同时标记 高置信度问题修复顺序先错误再警告最后才考虑建议Retrospective复盘当某个 Agent 误用了技能指导时让同一模型解释它为何那样做——自我分析能暴露指导中的缺口可以用针对性反模式补齐参见 references/anti-patterns.mdA/B 测试修复后重跑同一任务验证改进——同模型、同提示对比正确性 / 速度 / 工具调用次数。对新建技能或大规模重构应改用 writer-critic 收敛循环一个 Agent 写、另一个不同模型的 Agent 评写作者应用修改重复至收敛通常 2–3 轮。多模型测试方法论深入这一节对testing-patterns.md的关键设计做纵深解读因为它是技能到底好不好用的判定依据。为什么是多模型不同模型有不同盲区有的在代码正确性上强但漏掉易用性问题有的能发现别人忽略的边界情况有的会产生别人正确忽略的误报。方法论的基石是共识发现consensus findings2 个以上模型同时标记几乎总是真问题。测试提示模板测试提示要包含技能目的与上下文、一个真实可执行的任务、以及按严重度汇报的指令。文档给出三类模板脚本驱动型——让 Agent 运行技能并评估输出输出是否正确有用、边界情况是否失守、是否清晰可行动、有无 bug知识驱动型——让 Agent 应用技能规则后自评指令是否清晰、规则是否冲突、有无指导空白、有无过宽规则对 SKILL.md 本身——以评估是否值得采用的开发者视角做结构化审查触发描述质量、小节组织、完整性、准确性、可行动性。统一汇报格式❌ error / ⚠️ warning / suggestion。结果综合与优先级综合阶段做四件事去重归并描述同一问题的发现、提升共识2 模型标记 → 高置信度优先修、保留单模型高价值发现、丢弃无具体证据的模糊建议。行动优先级矩阵优先级判据Fix now立即修任一模型的 ❌ 错误或 2 模型的 ⚠️ 警告Fix soon尽快修1 个模型、有明确证据的 ⚠️ 警告Consider可考虑有共识或强理由的 建议Skip跳过1 个模型、无证据的 建议纯风格反馈A/B 前后对比迭代技能时用同一任务在修改前后各跑一遍防止修了 A 引入 B。测量指标指标测法良好信号Correctness正确性是否得出正确结论前 ❌ → 后 ✅Elapsed time耗时Agent 完成时间秒快 30% 以上Tool calls工具调用调用次数更少 更高效Wrong turns弯路未贡献答案的步骤更少 指导更好文档中给出的真实案例同一任务对比通过/失败 Helix binlog 中的 Csc 参数修改前耗时 623 秒且根因找错修改后 272 秒且根因正确——仅靠在一句提示模板中补充了关注参数数量差异而非参数值差异。操作要点前后必须用同一模型优先选有已知正确答案的任务不要为速度牺牲正确性保存修改前的原始提示。Writer-Critic 收敛循环流程Writer Agent 创建/修改技能 → Critic Agent不同模型产出结构化反馈❌/⚠️/→ Writer 应用修改 → Critic 只标记新增或残留问题 → 重复至 Critic 只剩 建议即收敛不必追求零发现。关键设计Writer 与 Critic 用不同模型——同模型组合太好说话人在轮次之间保持介入把握方向、否决坏建议反馈存成文件如技能目录下的feedback.md让 Writer 有完整上下文用完后删除与多模型测试的分工新建/大重构用 writer-critic 循环已有技能对真实任务做验证用并行单次多模型评审收敛后再用多模型评审做最终检查。回归启发式与提交前清单用量化评测waza-eval对比前后版本时的回归判据指标阈值动作任一任务工具调用增加 20% 回归回滚工具调用减少 10% 改进记录为证据耗时增加 30% 回归排查瓶颈前对后错 回归回滚——正确性压倒效率模型误用新指导 回归需要补反模式或改写措辞仅一个模型变好 部分通常可接受触发测试trigger tests应覆盖三类应触发8–12 条不同措辞、不应触发6–8 条相邻技能/他处关键词、边界3–5 条含糊提示附预期行为。提交前清单还包括描述与触发测试匹配、停止信号带数值边界、有领域示例、token 预算达标、多模型验证在 2 家族中 ≥ 4/5 通过。反模式清单来自实战的陷阱anti-patterns.md 收录的是开发中真实踩过的坑值得逐条对齐。按类别归纳如下技能设计类复述 MCP 工具文档Agent 上下文里已有工具描述再抄一份参数 schema 会形成两个会漂移的真值源。正确做法是提供工具描述里没有的领域上下文示例如分支 ref 模式、特定字段名并优先用领域语言而非工具名表述过度脚本化Agent 本身就有文件、子 Agent、PowerShell、ghCLI 等工具一个只会New-Item写模板文件的脚手架脚本严格劣于 Agent 直接做。脚本只用于复杂逻辑、确定性处理或必须每次行为一致的操作臃肿的 SKILL.md知识驱动型技能可以大文档举例某技能达 54KB前提是内容每任务一次性应用编排型技能必须精简深度内容移到references/模糊的触发描述description: A tool for analysis永远匹配不到真实用户查询好的描述要同时给出做什么和何时用含用户会说的自然语言关键词缺 When to Use没有明确触发场景技能要么过宽触发要么漏触发应列 5–8 个含真实关键词的具体场景。脚本与实现类临时文件存中间数据会触发审批提示、需清理、Agent 崩溃时残留。编排型技能应改用可查询的结构化存储只有脚本自管缓存含创建、TTL、清理的原子操作时才可用临时文件硬编码查找表名称到路径/ID/URL 的映射表会随底层数据变化而过期应改为数据驱动发现仅真正稳定的值管道 ID、组织名、刻意收窄的精选集合、或性能敏感路径可例外只做语法检查Parser::ParseFile只抓拼写错误抓不到依赖运行时数据的 bugbase64 内嵌换行、CLI 输出引号包裹、字段名差异。规则任何调用外部 API 的脚本发布前至少用一次真实调用验证。PowerShell 与 GitHub API 类对 .NET 仓库尤其实用数组布尔强转Where-Object返回数组时$array.state -eq SUCCESS产生的是布尔数组恒为真须Select-Object -First 1强制标量Fail-open 错误处理API 失败落入 else 分支被计为健康应 fail-closedUnknown 既不算健康也不算阻塞字符串转义gh pr create --body中反引号和$var会被 PowerShell 吞掉多行/Markdown 内容一律用--body-file假设字段名存在gh pr checks没有conclusion字段规则是绝不凭训练数据假设 API 字段先验证把推理编码进脚本一长串if/elseif产出固定文案的脚本无法适应作者没预料到的状态组合正确分工是脚本输出结构化事实Agent 负责推理。Agent 工作流类安全相关务必重视结果伪造文档引用了真实事故——Agent 只跑了一次测试却报告有/无修复都测过。对策多独立观测类技能必须用隔离子 Agenttask agent强制执行Agent 自行 approve/block PR必须显式禁止gh pr review --approve与--request-changes只允许--comment且禁令应放在 SKILL.md 顶部显著位置评审中切换分支评审/修改类技能应声明 Agent 永不执行改变工作区状态的 git 命令调研类技能除外;无限排障环境阻塞外部工具类技能必须带重试上限表如 500 错误 0 次重试、缺工具装 1 次Agent 的职责是停下来报告而非变身系统管理员。安全类脚本中严禁硬编码凭据用环境变量或平台凭据存储用户输入/API 响应拼命令前要消毒避免对不可信字符串用Invoke-Expression错误不得静默吞掉fail-closed提交过的密钥即使后续删除仍可从 git 历史提取须轮换权限需求写进 Prerequisites遵循最小权限只需读就不申请写。在 EF Core 仓库中对照检查把上述规范套回仓库现状可以做三处对照验证规范自洽make-skill自身就是第 4 步所说的following this files structure的范本——H1 概述、When Not to Use、Workflow8 个编号步骤、Common Pitfalls 表格一应俱全知识型技能的形态change-tracking/SKILL.md 设置user-invocable: false正文只写 EF Core 变更跟踪的实现细节StateManager、InternalEntityEntry、快照工厂与属性访问器与真实测试路径完全不复述工具调用工程化技能的形态make-github-actions-workflow/SKILL.md 则沉淀了仓库的 GitHub Actions 约定workflow 存放于.github/workflows/、kebab-case 命名、必须显式最小权限声明、pull_request_target的安全警告、用actions/github-script而非 shell 等属于典型的领域约定技能。关键要点速查主题要点最小结构.agents/skills/name/SKILL.mdfrontmatter 只需namedescription触发质量description 必须同时回答做什么和何时用含自然语言关键词体量红线SKILL.md ≤ 500 行 / 5000 token超出拆references/命名红线1–64 字符、不以连字符开头结尾、无连续连字符、与目录名一致脚本红线fail-closed、结构化输出、禁止把 API 失败计为成功测试红线2–4 个模型家族并行同题测试共识优先修A/B 复测验证改进安全红线禁密钥、禁 approve/block PR、外部工具带重试上限、多观测任务用隔离子 Agent完整的字段定义、工作流步骤与验证清单见 make-skill/SKILL.md测试方法论与回归判据见 references/testing-patterns.md全部反模式与真实事故案例见 references/anti-patterns.md。外部规范参考 Agent Skills Specificationagentskills.io仓库级上下文见 .github/copilot-instructions.md协作流程见 .github/CONTRIBUTING.md。【免费下载链接】efcoreEF Core is a modern object-database mapper for .NET. It supports LINQ queries, change tracking, updates, and schema migrations.项目地址: https://gitcode.com/GitHub_Trending/ef/efcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考