尧图网页设计 
AI Agent Skill 从概念到实战SKILL.md、渐进式加载与工作流复用**摘要**从一个真实任务出发讲清 Agent Skill 是什么、何时触发、怎样分层加载、如何与工具和 MCP 配合。再拆解官方与 GitHub 项目的实际 Skill并创建一个可复制到项目中的 Git 改动说明 Skill。目录先用一句话理解 Skill为什么需要 SkillSkill 目录里放什么Agent 怎样发现、调用和逐层加载 SkillSkill、Prompt、项目指令、MCP、工具和 Plugin 的区别从零实现一个代码变更总结 SkillCodex、Claude Code、VS Code 和 CLI 用法四个真实 Skill 的源码拆解怎样验证、迭代和治理什么时候创建什么时候不创建总结与参考资料一、先用一句话理解 Skill很多人第一次看到 SKILL.md会觉得它不过是“存起来的提示词”。这只说对了一半。更准确地说Skill 是一个能被 Agent 发现、按任务加载的工作包它说明什么任务适用、按什么步骤完成、需要哪些参考资料或脚本以及怎样判断结果合格。开放规范要求一个 Skill 至少是一个含有 SKILL.md 的目录还可以附带 scripts/、references/、assets/ 等资源。Agent Skills 开放规范可以把它比作团队操作手册模型是通用能力很强的新工程师description 是目录卡片SKILL.md 正文是主流程references/ 是有需要再查的规则scripts/ 是确定性辅助程序assets/ 是模板、图片和样例数据。**Skill 通常不是新模型也不会自动给 Agent 权限。**它组织做事方法能否读文件、搜网页、写数据或运行脚本仍由宿主提供的工具、权限与沙箱决定。以“帮我查出这个 GitHub PR 为什么 CI 失败”为例没有 Skill 时Agent 可以临场决定怎么查有了gh-fix-ci一类 Skill它会先判断任务是否属于 GitHub Actions 检查再按说明读取检查状态和失败日志整理证据最后给出修复建议。读取 GitHub 数据依靠gh和已授权的工具Skill 负责把这些动作组织成可重复的流程。第八节会沿着真实仓库文件拆开看。二、为什么需要 Skill2.1 不再反复粘贴同一套步骤假设每次代码审查都要说明“先看改动范围再按严重程度找缺陷必须引用位置和证据只报告问题不修改代码。”这些要求散落在不同聊天里换人、换项目又要重讲。Skill 把稳定重复的流程保存下来。之后用户只需提出任务Agent 可根据技能描述判断是否参考它也可以由用户显式点名调用。它尤其适合“步骤不难但很容易漏”的工作每次做发布说明都要核对提交范围、版本号、兼容性和链接每次检查 PDF 都要看文字也要看渲染后的版面。这些任务的质量取决于流程是否完整仅靠一句“请认真一点”很难稳定复现。2.2 补充模型不知道的团队知识模型知道常见实践但未必知道某团队的发布审批、业务术语、错误码规范和验收清单。Skill 可以把这些局部经验、参考资料与模板一起版本化随项目代码维护。2.3 按需加载减少无关上下文渐进式披露progressive disclosure是 Skill 的重要设计未命中技能的全文不用读选中的技能才读主说明参考文件再按任务需要打开。想象有 20 本工作手册先给 Agent 一张简短目录卡确定本次要用哪一本再翻开那一本的主流程碰到特殊情况才查附录。目录卡对应name、description等元数据正文对应SKILL.md附录对应references/等资源。注意**按需加载不是加载后免费。**选中的 SKILL.md、引用文档和脚本输出仍可能占用上下文。它节省的是本次没用到的 Skill 和资料的成本不是已读内容的 token。平台具体实现与预算也不同不能把某一家产品的数字当成统一标准。2.4 把“这次答得不错”变成可持续改进Skill 可以写明输入、步骤、输出和边界再用正例与负例检查是否命中、是否误触发。失败后就针对触发词、漏掉的步骤或验收标准做小幅修改而不是不断堆长 prompt。三、Skill 目录里放什么最小结构repo-change-summary/ └── SKILL.md确实需要拆分时可以长成下面这样。这是结构示意下文实作不会为了凑目录而创建空文件repo-change-summary/ ├── SKILL.md ├── references/ │ ├── review-checklist.md │ └── output-template.md ├── scripts/ │ └── collect-diff-stats.py ├── assets/ │ └── report-template.md └── agents/ └── openai.yaml3.1 Frontmatter名称与触发描述SKILL.md 以 YAML frontmatter 开头至少包含 name 和 description---name:repo-change-summarydescription:总结 Git 仓库中的未提交改动并指出有依据的风险。用户询问改了什么、需要变更摘要或只读检查 diff 时使用不要用于替代功能实现。---规范要求 name 使用小写字母、数字和连字符最多 64 个字符且不能以连字符起止或出现连续连字符通常与父目录同名。description 最多 1024 个字符应写清做什么和什么时候使用尽量使用用户真实会说的任务词。比如“帮助审查代码”太宽“总结当前 Git 改动用户问改了什么或需要只读检查 diff 时使用”更有区分度。为什么description要写“何时用”因为 Agent 在读到主文件前通常只看得到这段描述。若只写“一个强大的开发助手”系统无法分辨它适合代码审查、测试还是发布若把数据库、React、写作等无关关键词全部塞进去也容易误触发。OpenAI DocsBuild skills规范还列出可选 license、compatibility、metadata 和实验性的 allowed-tools。不同 Agent 对可选字段支持不一写入字段不等于获得宿主权限。字段规范3.2 正文将“仔细一点”改写成流程正文应回答开始前检查哪些输入主要步骤是什么信息不足或工具失败时怎么办输出格式和完成条件是什么哪些动作不允许或需要确认。“仔细审查改动”不容易执行“先读 diff按正确性、安全性、兼容性检查每条问题写位置、触发条件、影响和证据没有问题也说明检查范围不修改文件”则更容易验收。3.3 References、Scripts 和 Assetsreferences/让 Agent 阅读理解的详细规则、API 或边界案例。主说明指出何时打开。scripts/确定、重复的机械步骤。说明依赖、输入输出、错误行为。脚本代码不一定全部成为提示词但执行结果可能进入上下文。assets/任务要复用的模板、图片、样例或数据。agents/openai.yaml某些宿主的界面元数据不是通用规范必需项。不要为了目录完整而硬加脚本和空引用。简单技能用单文件即可知识较长或只在特定场景用时再拆分。SKILL.md的正文应该写“如何决策和交付”具体的长清单、操作手册放进references/只有需要可重复、确定的机械处理时再加scripts/。比如“判断哪条 CI 日志相关”需要模型理解上下文而“抓取检查状态并截取错误附近 30 行”适合脚本。脚本执行本身通常不用把整段源码塞进上下文但脚本输出仍会进入上下文所以输出也应简洁。OpenAIgh-fix-ci的脚本四、Agent 怎样发现、调用和逐层加载 Skill第 1 层发现技能目录准备轻量目录宿主按自身规则扫描项目级、个人级、组织级或插件内目录。它可以先把技能名称、描述和路径提供给 Agent而不是把所有正文预先放进上下文。Codex 的官方说明更具体初始技能列表包括名称、描述和文件路径这份初始列表最多占模型上下文窗口的 2%上下文窗口未知时最多 8,000 个字符。技能很多时先缩短描述仍超出预算可能省略部分技能并提示用户。这里的 8,000 是字符数不是“每个 Skill 的 token 配额”也不限制选中后读取的SKILL.md长度。OpenAI DocsBuild skills第 2 层匹配任务再读 SKILL.md触发常见两种显式调用用户点名比如 Codex 的 $skill-name 或 Claude Code 的 /skill-name具体语法看产品。隐式调用宿主/模型根据任务和 description 选择相关 Skill。隐式调用不是固定路由可能漏选或误选。所以描述要明确且有边界关键任务可显式指定。选中后 Agent 读取完整 SKILL.md再使用宿主已经提供且获准的工具执行。它看到 scripts/do_task.py 不意味着自动获得运行权限。这一步可以拆成两个判断该不该用由任务和description共同决定用了以后怎么做由SKILL.md正文决定。用户显式点名能避免漏选但仍要核对 Skill 是否适用当前环境。第 3 层按需读取参考文件或运行脚本主文件可以写“仅当改动包含数据库迁移时再看 references/database-migration-checks.md。”处理普通 UI 改动就不必加载迁移规则。开放规范建议相对 Skill 根目录引用文件并避免多层跳转。规范可选目录与文件引用例如同一个改动总结 Skill 面对两次任务本次改动读取的内容不必读取的内容只改前端按钮样式技能目录、SKILL.md、输出模板数据库迁移清单新增数据库迁移技能目录、SKILL.md、输出模板、迁移清单与任务无关的其他技能第三层的“按需”由正文中的条件触发而非所有references/文件自动注入。token 到底怎么省假设安装 20 个技能每份说明约 1,500 tokens。如果每轮都把全部正文加入上下文理论上这批文件约 30,000 tokens。分层方式先给较短的名称和描述本轮选一个 Skill 后读其主说明涉及特定领域时才打开对应参考文件。这是解释原理的估算不是任何产品承诺的实际 token 数。真实成本取决于宿主如何提供目录、描述和正文长度、读了多少参考文件及脚本输出。分层加载减少不相关上下文但已读取内容仍要占上下文。还要避免一个反效果把几十页规则直接写进SKILL.md一旦触发就会整篇进入上下文把正文做成短目录细节分到可按条件阅读的资料里才有分层收益。Vercel 的 React 性能 Skill 把 70 条规则分文件组织正好适合观察这种设计但它也提供了一个很大的汇编文档因此是否真的省上下文还取决于 Agent 最后读了什么。Vercel Skill 入口五、Skill、Prompt、项目指令、MCP、工具和 Plugin 的区别机制主要回答的问题例子单次 Prompt这一次要做什么“总结这次改动先别修改文件”项目指令如 AGENTS.md这个项目普遍遵守什么构建命令、代码风格、目录说明Skill遇到一类任务按什么流程完成代码审查、部署、研究并引用Tool / FunctionAgent 能执行哪个动作读文件、跑命令、搜网页、调 APIMCP Server如何通过标准协议连外部数据和动作查工单、读取 PR、写 CRMPlugin怎样把能力打包分发组合 Skills、MCP 连接和 UI以“完成一份有来源的 GitHub 项目分析”为例Skill 定义搜索、核验和引用步骤浏览器或 MCP 实际读取 GitHub脚本可验证链接项目指令约束文章风格Plugin 可把工作流和连接一起分发。OpenAI 文档概括MCP 提供实时数据、授权连接和受控动作Skill 指导何时调用工具、按什么顺序组合、如何处理不完整结果和交付内容。Skills 如何补充 MCP六、从零实现一个代码变更总结 Skill我们做一个适合初学者练手、又有实际用途的 Skill只读总结当前 Git 改动。它需要区分尚未暂存、已经暂存和未跟踪文件发现有数据库迁移时额外查看专项清单。本文给出完整文件内容复制即可试用不依赖未展示的后端程序。6.1 创建目录在项目根目录运行 PowerShellNew-Item-ItemType Directory-Force-Path.agents/skills/repo-change-summary/references目标结构my-project/ └── .agents/skills/repo-change-summary/ ├── SKILL.md └── references/ ├── output-template.md └── database-migration-checks.md这只创建目录。Codex 会扫描项目中的.agents/skills请在目标 Git 仓库里打开 Codex。若刚创建后没显示先核对目录和文件名再按当前客户端提示刷新或重启。OpenAI Docs本地 Skill 路径6.2 编写主流程 SKILL.md将以下内容保存为 .agents/skills/repo-change-summary/SKILL.md--- name: repo-change-summary description: 总结 Git 仓库中的未提交改动并给出有证据的风险。用户询问“改了什么”、需要 diff 摘要或只读审查时使用用户要求实现功能时不使用本技能替代开发。 --- # Git 改动说明 ## 目标 只读检查当前仓库的未提交改动给出可定位的摘要和风险。不要修改、暂存、提交或推送。 ## 工作步骤 1. 先运行 git rev-parse --show-toplevel。如果失败说明当前目录不是 Git 仓库并停止不要编造检查结果。 2. 运行 git status --short、git diff --stat、git diff、git diff --cached --stat 和 git diff --cached。区分工作区与暂存区。列出未跟踪路径普通 diff 不包含未跟踪文件内容未读取就不要推断其内容。 3. 用两到五条概括改动目的与范围再从正确性、安全性、兼容性、错误处理和测试覆盖方面检查。 4. 只有改动涉及数据库迁移时才读取 references/database-migration-checks.md 并做专项检查。普通改动不读取它。 5. 按 references/output-template.md 输出。每条问题写严重程度、路径或行号、触发条件、影响和证据。没有足够证据时写“待确认”不要写成确定缺陷。 6. 没发现可确认问题时明确说明检查范围和未执行的测试。 ## 边界 - 只使用读取信息的 Git 命令不编辑文件不暂存、提交或推送。 - 不执行会改变数据库或远程仓库的命令。 - 如发现疑似凭证只报告位置不复制凭证内容。这里有三个容易忽略的设计点一是description同时写了正向触发词和相邻但不适用的“实现功能”二是git diff与git diff --cached分别覆盖工作区和暂存区单看前者会漏掉已暂存改动三是迁移清单只在相关文件出现时才加载。普通 diff 不包含未跟踪文件的内容不能仅凭文件名声称已经审查过它们。6.3 添加输出模板 References保存为 references/output-template.md# 输出模板 ## 变更摘要 - 用 25 条说明改动目的和范围并区分工作区与暂存区。 ## 风险与问题 按严重程度排序。每条包含严重程度、路径或行号、触发条件、影响和依据。 没有可确认问题时明确说明“未发现可确认的问题”。 ## 检查范围与待确认项 列出未读取的未跟踪文件、未执行的测试、缺少的环境和不确定之处。不得暗示未执行的检查已经通过。再保存为references/database-migration-checks.md# 数据库迁移专项检查 仅在改动涉及数据库迁移时读取本文件。 1. 迁移是否能重复执行或安全重试若不能说明前置条件。 2. 大表加列、索引、回填是否可能长期持锁没有表规模和数据库版本时标记“待确认”。 3. 新旧应用版本并行期间字段是否兼容删除列和重命名尤其要核查发布顺序。 4. 是否有明确回滚或前滚方案数据删除通常不能靠回滚脚本恢复。 5. 只从 diff 中判断能证实的事项未连接数据库不宣称迁移已经成功运行。这两份参考资料承担不同角色输出模板每次使用迁移清单只有命中数据库变更时才读取。为了示范第三层加载才这样拆。真实项目里如果输出模板只有几行且每次都读直接放进SKILL.md也很合理。6.4 试用与检查保存好三个文件后在目标 Git 仓库中打开 Codex先显式试用$repo-change-summary 请只读检查当前改动先列摘要再列有依据的风险。再测试自动触发帮我总结一下当前未提交的改动先别修改任何文件。检查它是否在非 Git 目录拒绝编造 diff是否识别未跟踪文件是否遵守只读边界问题是否有位置和证据是否如实列出没执行的测试。建议先准备一个可丢弃的练习仓库修改一个已跟踪文件、git add暂存另一个文件、再新建一个未跟踪文件然后分别查看技能是否区分三类。不要把“模型说使用了 Skill”当成验收要核对它读了哪些内容输出是否能追溯到 diff是否承认未读取的文件和未运行的测试。这里给出的是完整配置与检查方法不同客户端的自动触发和执行结果仍需读者在自己的环境中实际试用。七、Codex、Claude Code、VS Code 和 CLI 用法7.1 CodexCodex 文档列出项目、个人、管理员和系统等范围。项目级一般放在仓库.agents/skills/name/SKILL.md适合随 Git 共享个人级可放在~/.agents/skills/name/SKILL.md用于跨项目复用。Codex 会从当前目录沿父目录扫描到仓库根因此需在目标仓库中启动。OpenAI DocsSkill 路径可显式使用 $repo-change-summary也可以自然描述“总结当前 Git 改动”让系统根据 description 判断。新技能没出现时检查路径和 name再按客户端文档刷新或重启。具体以当前 Codex Skills 文档为准。7.2 Claude Code项目级常见目录是 .claude/skills/repo-change-summary/SKILL.md个人级是 ~/.claude/skills/repo-change-summary/SKILL.md。可输入 /repo-change-summary 显式调用也可根据任务自动使用。Claude Code 还支持调用控制、动态上下文注入、subagent 执行等扩展不是每个兼容 Agent 都支持。Claude Code Skills 文档7.3 VS Code / GitHub CopilotVS Code 文档列出 .github/skills/、.claude/skills/、.agents/skills/ 等项目路径和用户路径且要求父目录名与 frontmatter 的 name 一致。IDE、CLI、云端形态需分别核对。VS Code Agent Skills7.4 使用 skills CLI 安装公开技能Vercel Labs 的 skills CLI 可以从开放生态安装技能npx skillsaddvercel-labs/agent-skills也可给定 GitHub 子目录npx skillsaddhttps://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices安装位置由 CLI 版本和选择决定。社区 Skill 与第三方代码一样安装前检查来源、许可证、脚本副作用和权限不要因为仓库流行而盲目执行。Vercel skills CLI 仓库7.5 创建后没生效先查哪一层现象优先检查技能列表里看不到放置路径、目录名、文件名SKILL.md、YAML frontmatter 是否完整必要时刷新客户端显式调用可以平时不自动触发description是否包含真实任务词范围是否过宽或过窄当前宿主是否启用了隐式调用已选中但做法不对正文是否写清输入、步骤、异常和完成标准引用文件是否真的存在读到说明但不能访问外部系统核对工具或 MCP 连接、登录与权限Skill 本身不会授予权限不要把这四类问题混成“Skill 没起作用”。前两类是发现与匹配第三类是说明质量最后一类是执行能力与授权。八、四个真实 Skill 的源码拆解接下来不按仓库 README 罗列功能而是沿着实际SKILL.md和配套文件看它何时触发、主文件安排了什么、哪些细节交给参考文件或脚本以及读者可以借鉴什么。这些都是对仓库文件的静态分析没有把示例运行结果当作亲测结果。8.1 OpenAIgh-fix-ci把“排查 CI”拆成可执行步骤Skill 入口 的描述限定在“GitHub PR 中由 GitHub Actions 执行的失败检查”。它不会因为用户说“构建失败”就把所有 CI 服务都纳入遇到 Buildkite 等外部检查只报告详情链接。这段范围限制很关键技能描述同时决定“什么时候使用”和“什么时候不使用”。主文件先列输入仓库路径、PR 编号或链接、gh认证随后安排顺序确认认证 → 定位 PR → 找失败检查 → 取 Actions 日志 → 摘录有用的错误片段 → 形成修复方案 → 在适当授权后实施并复查。原始SKILL.md它还把易变、重复的获取日志工作放进scripts/inspect_pr_checks.py。从源码可见脚本先检查当前目录是否为 Git 仓库与gh是否可用再解析 PR 和检查列表对于不同版本gh返回字段不一致的情况它会依据错误信息选择可用字段重试对失败检查再抓日志与错误上下文。支持--json可把结果交给 Agent 总结。脚本在发现失败检查时返回非零状态不能简单把非零退出码理解成脚本崩溃。可借鉴的分工如下位置承担的任务为什么放这里description精确限定 GitHub Actions 失败检查降低误触发SKILL.md排查顺序、缺日志时如何交代、修复边界让 Agent 有完整工作流inspect_pr_checks.py字段兼容、抓日志、截取错误上下文机械处理可重复验证这类 Skill 适用于任务有固定步骤、外部命令输出又比较杂的场景。普通提问“解释这段报错”未必需要整套 CI 工作流。openai/skills仓库目前已标记 deprecated但 Codex 的当前 Build skills 文档仍链接这个文件作示例因此这里分析的是结构与设计不建议照搬该仓库的旧安装说明。仓库状态8.2 Anthropicpdf同一技能中按任务分流Anthropic 的 PDF Skill 覆盖读取、合并、拆分、生成、OCR 和表单处理。入口描述很宽但正文明确区分任务一般 PDF 操作先看SKILL.md高级操作查REFERENCE.md需要填写表单时查FORMS.md。源码入口比如用户说“把三份 PDF 合并”Agent 可以从主文件找到pypdf的合并方法用户说“把这张表单填好”才需要继续读FORMS.md。这正是“主文件指路专项资料按需加载”。但也要看到它的权衡这个SKILL.md本身接近 300 行已经包含不少常见操作示例若某宿主在选中时完整读取主文件主文件的长度仍会消耗上下文。参考文件按需加载不等于主文件零成本。另一个值得借鉴的判断是提取到文字不代表 PDF 的视觉版式合格。表格错位、字体方块、裁切问题需要渲染后检查。这个例子说明 Skill 可以记录人类容易忘的验收动作。仓库的 PDF 目录标注了独立许可证复用其内容前应查看目录中的许可文件。8.3 Vercelreact-best-practices把大量规则做成索引Vercel 的 React 性能 Skill 的入口把规则分成 8 类并按影响程度排序异步瀑布、包体积、服务端性能、客户端数据请求、重渲染等。当前源码列出约 70 条规则每条规则在rules/中有独立文件。入口文件告诉 Agent 规则在哪细节文件解释原因并给出正确与错误用法。仓库源码以rules/async-parallel.md为例它针对彼此独立的异步操作建议并发等待。用我们自己的业务函数改写成最小示意// 两个请求互不依赖时可并发等待const[profile,projects]awaitPromise.all([loadProfile(),loadProjects(),]);若loadProjects(profile.id)依赖第一个结果就不能机械套用这条规则。Skill 提供的是检查方向Agent 仍需结合代码依赖关系判断。这个规则文件只有几十行查看异步瀑布问题时不必把全部 React 规则展开。不过仓库也有完整汇编的AGENTS.md若任务让 Agent 每次都读整份汇编文档按需加载的收益会被削弱。“有很多小文件”不是节省 token 的充分条件关键是入口怎样路由、实际读了哪些文件。8.4 OpenAIlinearSkill 与 MCP 怎样配合Linear Skill 示例 首先写明依赖 Linear MCP 连接与工作区访问权限。它的流程不是在本地造一个 Linear 数据库而是先明确团队、项目、优先级、标签等范围再选相应 MCP 工具先读问题或项目状态最后按用户请求创建或更新。原始SKILL.md从这个例子看边界很清楚list_issues、get_issue、create_issue等动作由 MCP Server 提供Skill 决定何时读取、何时写入、怎样汇总结果。没有连接或权限光有SKILL.md不会让 Agent 访问 Linear。这个旧仓库里的 MCP 配置命令和开关可能已经过时本文仅分析职责划分实际连接应以当前宿主与服务商文档为准。Codex 当前文档还给出了在agents/openai.yaml声明 MCP 依赖的方式属于宿主扩展不是 Agent Skills 通用规范的必填字段。OpenAI Docs可选元数据四个案例分别对应四种常见需求脚本处理机械输出、参考资料按场景分流、大型规则库索引、MCP 提供外部能力。设计自己的 Skill 时先看任务的真实复杂度挑需要的部分组合即可。九、怎样验证、迭代和治理9.1 用正例、负例测触发类型请求期望正例“总结当前未提交的 Git 改动”使用本 Skill同义正例“看下 diff 改了什么先不要动文件”使用本 Skill负例“给现有模块新增导出功能”不应误判成只读总结边界例当前目录不是 Git 仓库说明无法读取不编造输入覆盖改动分别位于工作区、暂存区、未跟踪文件三类分开说明不臆测未跟踪文件内容条件加载改动含数据库迁移额外读取迁移清单并标记无法确认的环境因素9.2 检查执行结果不只看调用名检查是否读取必要输入、遵守只读边界、问题是否能定位并有证据、是否如实说明未运行测试。OpenAI 的评估指南建议用正负例发现误触发并结合确定性检查与质量 rubric。OpenAI系统化评估 Skills可以分成三层验收触发对不对应使用时用了、不该使用时没用过程对不对确实读了工作区与暂存区、只在迁移时读专项资料结果对不对问题有证据、未运行事项明确列出。只统计“用了 Skill”会漏掉后两层。开放规范也提供格式校验思路但格式通过不能证明模型会正确执行任务。9.3 失败后针对根因修改没触发改 description 关键词与使用条件。触发过宽补充相邻但不适用的场景。漏步骤调整主流程。机械步骤不稳定考虑脚本。输出不好验收补模板和完成条件。主文件太长拆到 References 并写清何时读取。每次只改一两个直接对应失败现象的地方再用同一组正例和负例回测。如果为避免一个误触发把描述写成一大串例外往往说明这个 Skill 的职责过宽值得拆成两个更清晰的技能。OpenAI Docs精简技能描述与按需查阅Skill 可能包含第三方指令、脚本、联网操作或凭据引用。使用前检查来源、许可证、脚本副作用和权限在最小权限下试用。Skill 不能覆盖宿主安全策略也不能自动授权写生产数据或推送代码。十、什么时候创建什么时候不创建适合创建任务反复发生步骤相对稳定依赖团队知识或固定交付格式多阶段操作容易漏步骤需要多人或多个 Agent 复用。不必创建一次性简单需求其实是全项目共性规则应写项目指令需要实时系统能力但缺少 Tool/MCP流程必须强制执行而只靠自然语言不能保证应使用程序、审批或权限策略。一个实用判断看三个因素重复频率、步骤稳定性、专业上下文价值。都高时通常值得创建只是“能写成 Markdown”不是理由。拿不准时问自己四个问题这套做法下个月还会重复吗其他人接手时是否容易漏步骤失败后能否写出可检查的完成条件这套内容是否有需要按需查阅的资料多数回答“是”Skill 通常值得维护。若只是“获取 Linear 的最新工单”首先需要的是授权连接若是“每周按照固定规则整理工单并形成汇报”则可以在连接之上再加 Skill。十一、总结与参考资料Skill 的核心不是让模型凭空多出能力而是把一类任务的触发条件、步骤、参考知识、工具用法与验收标准整理成可复用、可维护、可评估的工作包。发现名称和描述 → 匹配任务或显式调用 → 读取 SKILL.md 主流程 → 按需打开 References / Assets 或运行脚本 → 使用宿主提供且获准的工具 → 按完成标准检查 → 将失败案例转成改进用例CSDN 标签AI Agent、Agent Skills、SKILL.md、Codex、Claude Code、GitHub Copilot、MCP、提示工程参考资料Agent Skills 开放规范OpenAI DocsBuild skillsOpenAISkills 如何补充 MCPAnthropic Claude CodeSkillsVS CodeUse Agent SkillsOpenAITesting Agent Skills Systematically with EvalsOpenAI技能描述与按需加载的实践OpenAIgh-fix-ci的 SKILL.md 与脚本Anthropicpdf的 SKILL.mdVercel React 性能 Skill 及独立规则OpenAIlinear的 SKILL.mdVercel skills CLI GitHubopenai/skills 仓库状态deprecated AI Agent Skill 从概念到实战：SKILL.md、渐进式加载与工作流复用
AI Agent Skill 从概念到实战SKILL.md、渐进式加载与工作流复用**摘要**从一个真实任务出发讲清 Agent Skill 是什么、何时触发、怎样分层加载、如何与工具和 MCP 配合。再拆解官方与 GitHub 项目的实际 Skill并创建一个可复制到项目中的 Git 改动说明 Skill。目录先用一句话理解 Skill为什么需要 SkillSkill 目录里放什么Agent 怎样发现、调用和逐层加载 SkillSkill、Prompt、项目指令、MCP、工具和 Plugin 的区别从零实现一个代码变更总结 SkillCodex、Claude Code、VS Code 和 CLI 用法四个真实 Skill 的源码拆解怎样验证、迭代和治理什么时候创建什么时候不创建总结与参考资料一、先用一句话理解 Skill很多人第一次看到 SKILL.md会觉得它不过是“存起来的提示词”。这只说对了一半。更准确地说Skill 是一个能被 Agent 发现、按任务加载的工作包它说明什么任务适用、按什么步骤完成、需要哪些参考资料或脚本以及怎样判断结果合格。开放规范要求一个 Skill 至少是一个含有 SKILL.md 的目录还可以附带 scripts/、references/、assets/ 等资源。Agent Skills 开放规范可以把它比作团队操作手册模型是通用能力很强的新工程师description 是目录卡片SKILL.md 正文是主流程references/ 是有需要再查的规则scripts/ 是确定性辅助程序assets/ 是模板、图片和样例数据。**Skill 通常不是新模型也不会自动给 Agent 权限。**它组织做事方法能否读文件、搜网页、写数据或运行脚本仍由宿主提供的工具、权限与沙箱决定。以“帮我查出这个 GitHub PR 为什么 CI 失败”为例没有 Skill 时Agent 可以临场决定怎么查有了gh-fix-ci一类 Skill它会先判断任务是否属于 GitHub Actions 检查再按说明读取检查状态和失败日志整理证据最后给出修复建议。读取 GitHub 数据依靠gh和已授权的工具Skill 负责把这些动作组织成可重复的流程。第八节会沿着真实仓库文件拆开看。二、为什么需要 Skill2.1 不再反复粘贴同一套步骤假设每次代码审查都要说明“先看改动范围再按严重程度找缺陷必须引用位置和证据只报告问题不修改代码。”这些要求散落在不同聊天里换人、换项目又要重讲。Skill 把稳定重复的流程保存下来。之后用户只需提出任务Agent 可根据技能描述判断是否参考它也可以由用户显式点名调用。它尤其适合“步骤不难但很容易漏”的工作每次做发布说明都要核对提交范围、版本号、兼容性和链接每次检查 PDF 都要看文字也要看渲染后的版面。这些任务的质量取决于流程是否完整仅靠一句“请认真一点”很难稳定复现。2.2 补充模型不知道的团队知识模型知道常见实践但未必知道某团队的发布审批、业务术语、错误码规范和验收清单。Skill 可以把这些局部经验、参考资料与模板一起版本化随项目代码维护。2.3 按需加载减少无关上下文渐进式披露progressive disclosure是 Skill 的重要设计未命中技能的全文不用读选中的技能才读主说明参考文件再按任务需要打开。想象有 20 本工作手册先给 Agent 一张简短目录卡确定本次要用哪一本再翻开那一本的主流程碰到特殊情况才查附录。目录卡对应name、description等元数据正文对应SKILL.md附录对应references/等资源。注意**按需加载不是加载后免费。**选中的 SKILL.md、引用文档和脚本输出仍可能占用上下文。它节省的是本次没用到的 Skill 和资料的成本不是已读内容的 token。平台具体实现与预算也不同不能把某一家产品的数字当成统一标准。2.4 把“这次答得不错”变成可持续改进Skill 可以写明输入、步骤、输出和边界再用正例与负例检查是否命中、是否误触发。失败后就针对触发词、漏掉的步骤或验收标准做小幅修改而不是不断堆长 prompt。三、Skill 目录里放什么最小结构repo-change-summary/ └── SKILL.md确实需要拆分时可以长成下面这样。这是结构示意下文实作不会为了凑目录而创建空文件repo-change-summary/ ├── SKILL.md ├── references/ │ ├── review-checklist.md │ └── output-template.md ├── scripts/ │ └── collect-diff-stats.py ├── assets/ │ └── report-template.md └── agents/ └── openai.yaml3.1 Frontmatter名称与触发描述SKILL.md 以 YAML frontmatter 开头至少包含 name 和 description---name:repo-change-summarydescription:总结 Git 仓库中的未提交改动并指出有依据的风险。用户询问改了什么、需要变更摘要或只读检查 diff 时使用不要用于替代功能实现。---规范要求 name 使用小写字母、数字和连字符最多 64 个字符且不能以连字符起止或出现连续连字符通常与父目录同名。description 最多 1024 个字符应写清做什么和什么时候使用尽量使用用户真实会说的任务词。比如“帮助审查代码”太宽“总结当前 Git 改动用户问改了什么或需要只读检查 diff 时使用”更有区分度。为什么description要写“何时用”因为 Agent 在读到主文件前通常只看得到这段描述。若只写“一个强大的开发助手”系统无法分辨它适合代码审查、测试还是发布若把数据库、React、写作等无关关键词全部塞进去也容易误触发。OpenAI DocsBuild skills规范还列出可选 license、compatibility、metadata 和实验性的 allowed-tools。不同 Agent 对可选字段支持不一写入字段不等于获得宿主权限。字段规范3.2 正文将“仔细一点”改写成流程正文应回答开始前检查哪些输入主要步骤是什么信息不足或工具失败时怎么办输出格式和完成条件是什么哪些动作不允许或需要确认。“仔细审查改动”不容易执行“先读 diff按正确性、安全性、兼容性检查每条问题写位置、触发条件、影响和证据没有问题也说明检查范围不修改文件”则更容易验收。3.3 References、Scripts 和 Assetsreferences/让 Agent 阅读理解的详细规则、API 或边界案例。主说明指出何时打开。scripts/确定、重复的机械步骤。说明依赖、输入输出、错误行为。脚本代码不一定全部成为提示词但执行结果可能进入上下文。assets/任务要复用的模板、图片、样例或数据。agents/openai.yaml某些宿主的界面元数据不是通用规范必需项。不要为了目录完整而硬加脚本和空引用。简单技能用单文件即可知识较长或只在特定场景用时再拆分。SKILL.md的正文应该写“如何决策和交付”具体的长清单、操作手册放进references/只有需要可重复、确定的机械处理时再加scripts/。比如“判断哪条 CI 日志相关”需要模型理解上下文而“抓取检查状态并截取错误附近 30 行”适合脚本。脚本执行本身通常不用把整段源码塞进上下文但脚本输出仍会进入上下文所以输出也应简洁。OpenAIgh-fix-ci的脚本四、Agent 怎样发现、调用和逐层加载 Skill第 1 层发现技能目录准备轻量目录宿主按自身规则扫描项目级、个人级、组织级或插件内目录。它可以先把技能名称、描述和路径提供给 Agent而不是把所有正文预先放进上下文。Codex 的官方说明更具体初始技能列表包括名称、描述和文件路径这份初始列表最多占模型上下文窗口的 2%上下文窗口未知时最多 8,000 个字符。技能很多时先缩短描述仍超出预算可能省略部分技能并提示用户。这里的 8,000 是字符数不是“每个 Skill 的 token 配额”也不限制选中后读取的SKILL.md长度。OpenAI DocsBuild skills第 2 层匹配任务再读 SKILL.md触发常见两种显式调用用户点名比如 Codex 的 $skill-name 或 Claude Code 的 /skill-name具体语法看产品。隐式调用宿主/模型根据任务和 description 选择相关 Skill。隐式调用不是固定路由可能漏选或误选。所以描述要明确且有边界关键任务可显式指定。选中后 Agent 读取完整 SKILL.md再使用宿主已经提供且获准的工具执行。它看到 scripts/do_task.py 不意味着自动获得运行权限。这一步可以拆成两个判断该不该用由任务和description共同决定用了以后怎么做由SKILL.md正文决定。用户显式点名能避免漏选但仍要核对 Skill 是否适用当前环境。第 3 层按需读取参考文件或运行脚本主文件可以写“仅当改动包含数据库迁移时再看 references/database-migration-checks.md。”处理普通 UI 改动就不必加载迁移规则。开放规范建议相对 Skill 根目录引用文件并避免多层跳转。规范可选目录与文件引用例如同一个改动总结 Skill 面对两次任务本次改动读取的内容不必读取的内容只改前端按钮样式技能目录、SKILL.md、输出模板数据库迁移清单新增数据库迁移技能目录、SKILL.md、输出模板、迁移清单与任务无关的其他技能第三层的“按需”由正文中的条件触发而非所有references/文件自动注入。token 到底怎么省假设安装 20 个技能每份说明约 1,500 tokens。如果每轮都把全部正文加入上下文理论上这批文件约 30,000 tokens。分层方式先给较短的名称和描述本轮选一个 Skill 后读其主说明涉及特定领域时才打开对应参考文件。这是解释原理的估算不是任何产品承诺的实际 token 数。真实成本取决于宿主如何提供目录、描述和正文长度、读了多少参考文件及脚本输出。分层加载减少不相关上下文但已读取内容仍要占上下文。还要避免一个反效果把几十页规则直接写进SKILL.md一旦触发就会整篇进入上下文把正文做成短目录细节分到可按条件阅读的资料里才有分层收益。Vercel 的 React 性能 Skill 把 70 条规则分文件组织正好适合观察这种设计但它也提供了一个很大的汇编文档因此是否真的省上下文还取决于 Agent 最后读了什么。Vercel Skill 入口五、Skill、Prompt、项目指令、MCP、工具和 Plugin 的区别机制主要回答的问题例子单次 Prompt这一次要做什么“总结这次改动先别修改文件”项目指令如 AGENTS.md这个项目普遍遵守什么构建命令、代码风格、目录说明Skill遇到一类任务按什么流程完成代码审查、部署、研究并引用Tool / FunctionAgent 能执行哪个动作读文件、跑命令、搜网页、调 APIMCP Server如何通过标准协议连外部数据和动作查工单、读取 PR、写 CRMPlugin怎样把能力打包分发组合 Skills、MCP 连接和 UI以“完成一份有来源的 GitHub 项目分析”为例Skill 定义搜索、核验和引用步骤浏览器或 MCP 实际读取 GitHub脚本可验证链接项目指令约束文章风格Plugin 可把工作流和连接一起分发。OpenAI 文档概括MCP 提供实时数据、授权连接和受控动作Skill 指导何时调用工具、按什么顺序组合、如何处理不完整结果和交付内容。Skills 如何补充 MCP六、从零实现一个代码变更总结 Skill我们做一个适合初学者练手、又有实际用途的 Skill只读总结当前 Git 改动。它需要区分尚未暂存、已经暂存和未跟踪文件发现有数据库迁移时额外查看专项清单。本文给出完整文件内容复制即可试用不依赖未展示的后端程序。6.1 创建目录在项目根目录运行 PowerShellNew-Item-ItemType Directory-Force-Path.agents/skills/repo-change-summary/references目标结构my-project/ └── .agents/skills/repo-change-summary/ ├── SKILL.md └── references/ ├── output-template.md └── database-migration-checks.md这只创建目录。Codex 会扫描项目中的.agents/skills请在目标 Git 仓库里打开 Codex。若刚创建后没显示先核对目录和文件名再按当前客户端提示刷新或重启。OpenAI Docs本地 Skill 路径6.2 编写主流程 SKILL.md将以下内容保存为 .agents/skills/repo-change-summary/SKILL.md--- name: repo-change-summary description: 总结 Git 仓库中的未提交改动并给出有证据的风险。用户询问“改了什么”、需要 diff 摘要或只读审查时使用用户要求实现功能时不使用本技能替代开发。 --- # Git 改动说明 ## 目标 只读检查当前仓库的未提交改动给出可定位的摘要和风险。不要修改、暂存、提交或推送。 ## 工作步骤 1. 先运行 git rev-parse --show-toplevel。如果失败说明当前目录不是 Git 仓库并停止不要编造检查结果。 2. 运行 git status --short、git diff --stat、git diff、git diff --cached --stat 和 git diff --cached。区分工作区与暂存区。列出未跟踪路径普通 diff 不包含未跟踪文件内容未读取就不要推断其内容。 3. 用两到五条概括改动目的与范围再从正确性、安全性、兼容性、错误处理和测试覆盖方面检查。 4. 只有改动涉及数据库迁移时才读取 references/database-migration-checks.md 并做专项检查。普通改动不读取它。 5. 按 references/output-template.md 输出。每条问题写严重程度、路径或行号、触发条件、影响和证据。没有足够证据时写“待确认”不要写成确定缺陷。 6. 没发现可确认问题时明确说明检查范围和未执行的测试。 ## 边界 - 只使用读取信息的 Git 命令不编辑文件不暂存、提交或推送。 - 不执行会改变数据库或远程仓库的命令。 - 如发现疑似凭证只报告位置不复制凭证内容。这里有三个容易忽略的设计点一是description同时写了正向触发词和相邻但不适用的“实现功能”二是git diff与git diff --cached分别覆盖工作区和暂存区单看前者会漏掉已暂存改动三是迁移清单只在相关文件出现时才加载。普通 diff 不包含未跟踪文件的内容不能仅凭文件名声称已经审查过它们。6.3 添加输出模板 References保存为 references/output-template.md# 输出模板 ## 变更摘要 - 用 25 条说明改动目的和范围并区分工作区与暂存区。 ## 风险与问题 按严重程度排序。每条包含严重程度、路径或行号、触发条件、影响和依据。 没有可确认问题时明确说明“未发现可确认的问题”。 ## 检查范围与待确认项 列出未读取的未跟踪文件、未执行的测试、缺少的环境和不确定之处。不得暗示未执行的检查已经通过。再保存为references/database-migration-checks.md# 数据库迁移专项检查 仅在改动涉及数据库迁移时读取本文件。 1. 迁移是否能重复执行或安全重试若不能说明前置条件。 2. 大表加列、索引、回填是否可能长期持锁没有表规模和数据库版本时标记“待确认”。 3. 新旧应用版本并行期间字段是否兼容删除列和重命名尤其要核查发布顺序。 4. 是否有明确回滚或前滚方案数据删除通常不能靠回滚脚本恢复。 5. 只从 diff 中判断能证实的事项未连接数据库不宣称迁移已经成功运行。这两份参考资料承担不同角色输出模板每次使用迁移清单只有命中数据库变更时才读取。为了示范第三层加载才这样拆。真实项目里如果输出模板只有几行且每次都读直接放进SKILL.md也很合理。6.4 试用与检查保存好三个文件后在目标 Git 仓库中打开 Codex先显式试用$repo-change-summary 请只读检查当前改动先列摘要再列有依据的风险。再测试自动触发帮我总结一下当前未提交的改动先别修改任何文件。检查它是否在非 Git 目录拒绝编造 diff是否识别未跟踪文件是否遵守只读边界问题是否有位置和证据是否如实列出没执行的测试。建议先准备一个可丢弃的练习仓库修改一个已跟踪文件、git add暂存另一个文件、再新建一个未跟踪文件然后分别查看技能是否区分三类。不要把“模型说使用了 Skill”当成验收要核对它读了哪些内容输出是否能追溯到 diff是否承认未读取的文件和未运行的测试。这里给出的是完整配置与检查方法不同客户端的自动触发和执行结果仍需读者在自己的环境中实际试用。七、Codex、Claude Code、VS Code 和 CLI 用法7.1 CodexCodex 文档列出项目、个人、管理员和系统等范围。项目级一般放在仓库.agents/skills/name/SKILL.md适合随 Git 共享个人级可放在~/.agents/skills/name/SKILL.md用于跨项目复用。Codex 会从当前目录沿父目录扫描到仓库根因此需在目标仓库中启动。OpenAI DocsSkill 路径可显式使用 $repo-change-summary也可以自然描述“总结当前 Git 改动”让系统根据 description 判断。新技能没出现时检查路径和 name再按客户端文档刷新或重启。具体以当前 Codex Skills 文档为准。7.2 Claude Code项目级常见目录是 .claude/skills/repo-change-summary/SKILL.md个人级是 ~/.claude/skills/repo-change-summary/SKILL.md。可输入 /repo-change-summary 显式调用也可根据任务自动使用。Claude Code 还支持调用控制、动态上下文注入、subagent 执行等扩展不是每个兼容 Agent 都支持。Claude Code Skills 文档7.3 VS Code / GitHub CopilotVS Code 文档列出 .github/skills/、.claude/skills/、.agents/skills/ 等项目路径和用户路径且要求父目录名与 frontmatter 的 name 一致。IDE、CLI、云端形态需分别核对。VS Code Agent Skills7.4 使用 skills CLI 安装公开技能Vercel Labs 的 skills CLI 可以从开放生态安装技能npx skillsaddvercel-labs/agent-skills也可给定 GitHub 子目录npx skillsaddhttps://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices安装位置由 CLI 版本和选择决定。社区 Skill 与第三方代码一样安装前检查来源、许可证、脚本副作用和权限不要因为仓库流行而盲目执行。Vercel skills CLI 仓库7.5 创建后没生效先查哪一层现象优先检查技能列表里看不到放置路径、目录名、文件名SKILL.md、YAML frontmatter 是否完整必要时刷新客户端显式调用可以平时不自动触发description是否包含真实任务词范围是否过宽或过窄当前宿主是否启用了隐式调用已选中但做法不对正文是否写清输入、步骤、异常和完成标准引用文件是否真的存在读到说明但不能访问外部系统核对工具或 MCP 连接、登录与权限Skill 本身不会授予权限不要把这四类问题混成“Skill 没起作用”。前两类是发现与匹配第三类是说明质量最后一类是执行能力与授权。八、四个真实 Skill 的源码拆解接下来不按仓库 README 罗列功能而是沿着实际SKILL.md和配套文件看它何时触发、主文件安排了什么、哪些细节交给参考文件或脚本以及读者可以借鉴什么。这些都是对仓库文件的静态分析没有把示例运行结果当作亲测结果。8.1 OpenAIgh-fix-ci把“排查 CI”拆成可执行步骤Skill 入口 的描述限定在“GitHub PR 中由 GitHub Actions 执行的失败检查”。它不会因为用户说“构建失败”就把所有 CI 服务都纳入遇到 Buildkite 等外部检查只报告详情链接。这段范围限制很关键技能描述同时决定“什么时候使用”和“什么时候不使用”。主文件先列输入仓库路径、PR 编号或链接、gh认证随后安排顺序确认认证 → 定位 PR → 找失败检查 → 取 Actions 日志 → 摘录有用的错误片段 → 形成修复方案 → 在适当授权后实施并复查。原始SKILL.md它还把易变、重复的获取日志工作放进scripts/inspect_pr_checks.py。从源码可见脚本先检查当前目录是否为 Git 仓库与gh是否可用再解析 PR 和检查列表对于不同版本gh返回字段不一致的情况它会依据错误信息选择可用字段重试对失败检查再抓日志与错误上下文。支持--json可把结果交给 Agent 总结。脚本在发现失败检查时返回非零状态不能简单把非零退出码理解成脚本崩溃。可借鉴的分工如下位置承担的任务为什么放这里description精确限定 GitHub Actions 失败检查降低误触发SKILL.md排查顺序、缺日志时如何交代、修复边界让 Agent 有完整工作流inspect_pr_checks.py字段兼容、抓日志、截取错误上下文机械处理可重复验证这类 Skill 适用于任务有固定步骤、外部命令输出又比较杂的场景。普通提问“解释这段报错”未必需要整套 CI 工作流。openai/skills仓库目前已标记 deprecated但 Codex 的当前 Build skills 文档仍链接这个文件作示例因此这里分析的是结构与设计不建议照搬该仓库的旧安装说明。仓库状态8.2 Anthropicpdf同一技能中按任务分流Anthropic 的 PDF Skill 覆盖读取、合并、拆分、生成、OCR 和表单处理。入口描述很宽但正文明确区分任务一般 PDF 操作先看SKILL.md高级操作查REFERENCE.md需要填写表单时查FORMS.md。源码入口比如用户说“把三份 PDF 合并”Agent 可以从主文件找到pypdf的合并方法用户说“把这张表单填好”才需要继续读FORMS.md。这正是“主文件指路专项资料按需加载”。但也要看到它的权衡这个SKILL.md本身接近 300 行已经包含不少常见操作示例若某宿主在选中时完整读取主文件主文件的长度仍会消耗上下文。参考文件按需加载不等于主文件零成本。另一个值得借鉴的判断是提取到文字不代表 PDF 的视觉版式合格。表格错位、字体方块、裁切问题需要渲染后检查。这个例子说明 Skill 可以记录人类容易忘的验收动作。仓库的 PDF 目录标注了独立许可证复用其内容前应查看目录中的许可文件。8.3 Vercelreact-best-practices把大量规则做成索引Vercel 的 React 性能 Skill 的入口把规则分成 8 类并按影响程度排序异步瀑布、包体积、服务端性能、客户端数据请求、重渲染等。当前源码列出约 70 条规则每条规则在rules/中有独立文件。入口文件告诉 Agent 规则在哪细节文件解释原因并给出正确与错误用法。仓库源码以rules/async-parallel.md为例它针对彼此独立的异步操作建议并发等待。用我们自己的业务函数改写成最小示意// 两个请求互不依赖时可并发等待const[profile,projects]awaitPromise.all([loadProfile(),loadProjects(),]);若loadProjects(profile.id)依赖第一个结果就不能机械套用这条规则。Skill 提供的是检查方向Agent 仍需结合代码依赖关系判断。这个规则文件只有几十行查看异步瀑布问题时不必把全部 React 规则展开。不过仓库也有完整汇编的AGENTS.md若任务让 Agent 每次都读整份汇编文档按需加载的收益会被削弱。“有很多小文件”不是节省 token 的充分条件关键是入口怎样路由、实际读了哪些文件。8.4 OpenAIlinearSkill 与 MCP 怎样配合Linear Skill 示例 首先写明依赖 Linear MCP 连接与工作区访问权限。它的流程不是在本地造一个 Linear 数据库而是先明确团队、项目、优先级、标签等范围再选相应 MCP 工具先读问题或项目状态最后按用户请求创建或更新。原始SKILL.md从这个例子看边界很清楚list_issues、get_issue、create_issue等动作由 MCP Server 提供Skill 决定何时读取、何时写入、怎样汇总结果。没有连接或权限光有SKILL.md不会让 Agent 访问 Linear。这个旧仓库里的 MCP 配置命令和开关可能已经过时本文仅分析职责划分实际连接应以当前宿主与服务商文档为准。Codex 当前文档还给出了在agents/openai.yaml声明 MCP 依赖的方式属于宿主扩展不是 Agent Skills 通用规范的必填字段。OpenAI Docs可选元数据四个案例分别对应四种常见需求脚本处理机械输出、参考资料按场景分流、大型规则库索引、MCP 提供外部能力。设计自己的 Skill 时先看任务的真实复杂度挑需要的部分组合即可。九、怎样验证、迭代和治理9.1 用正例、负例测触发类型请求期望正例“总结当前未提交的 Git 改动”使用本 Skill同义正例“看下 diff 改了什么先不要动文件”使用本 Skill负例“给现有模块新增导出功能”不应误判成只读总结边界例当前目录不是 Git 仓库说明无法读取不编造输入覆盖改动分别位于工作区、暂存区、未跟踪文件三类分开说明不臆测未跟踪文件内容条件加载改动含数据库迁移额外读取迁移清单并标记无法确认的环境因素9.2 检查执行结果不只看调用名检查是否读取必要输入、遵守只读边界、问题是否能定位并有证据、是否如实说明未运行测试。OpenAI 的评估指南建议用正负例发现误触发并结合确定性检查与质量 rubric。OpenAI系统化评估 Skills可以分成三层验收触发对不对应使用时用了、不该使用时没用过程对不对确实读了工作区与暂存区、只在迁移时读专项资料结果对不对问题有证据、未运行事项明确列出。只统计“用了 Skill”会漏掉后两层。开放规范也提供格式校验思路但格式通过不能证明模型会正确执行任务。9.3 失败后针对根因修改没触发改 description 关键词与使用条件。触发过宽补充相邻但不适用的场景。漏步骤调整主流程。机械步骤不稳定考虑脚本。输出不好验收补模板和完成条件。主文件太长拆到 References 并写清何时读取。每次只改一两个直接对应失败现象的地方再用同一组正例和负例回测。如果为避免一个误触发把描述写成一大串例外往往说明这个 Skill 的职责过宽值得拆成两个更清晰的技能。OpenAI Docs精简技能描述与按需查阅Skill 可能包含第三方指令、脚本、联网操作或凭据引用。使用前检查来源、许可证、脚本副作用和权限在最小权限下试用。Skill 不能覆盖宿主安全策略也不能自动授权写生产数据或推送代码。十、什么时候创建什么时候不创建适合创建任务反复发生步骤相对稳定依赖团队知识或固定交付格式多阶段操作容易漏步骤需要多人或多个 Agent 复用。不必创建一次性简单需求其实是全项目共性规则应写项目指令需要实时系统能力但缺少 Tool/MCP流程必须强制执行而只靠自然语言不能保证应使用程序、审批或权限策略。一个实用判断看三个因素重复频率、步骤稳定性、专业上下文价值。都高时通常值得创建只是“能写成 Markdown”不是理由。拿不准时问自己四个问题这套做法下个月还会重复吗其他人接手时是否容易漏步骤失败后能否写出可检查的完成条件这套内容是否有需要按需查阅的资料多数回答“是”Skill 通常值得维护。若只是“获取 Linear 的最新工单”首先需要的是授权连接若是“每周按照固定规则整理工单并形成汇报”则可以在连接之上再加 Skill。十一、总结与参考资料Skill 的核心不是让模型凭空多出能力而是把一类任务的触发条件、步骤、参考知识、工具用法与验收标准整理成可复用、可维护、可评估的工作包。发现名称和描述 → 匹配任务或显式调用 → 读取 SKILL.md 主流程 → 按需打开 References / Assets 或运行脚本 → 使用宿主提供且获准的工具 → 按完成标准检查 → 将失败案例转成改进用例CSDN 标签AI Agent、Agent Skills、SKILL.md、Codex、Claude Code、GitHub Copilot、MCP、提示工程参考资料Agent Skills 开放规范OpenAI DocsBuild skillsOpenAISkills 如何补充 MCPAnthropic Claude CodeSkillsVS CodeUse Agent SkillsOpenAITesting Agent Skills Systematically with EvalsOpenAI技能描述与按需加载的实践OpenAIgh-fix-ci的 SKILL.md 与脚本Anthropicpdf的 SKILL.mdVercel React 性能 Skill 及独立规则OpenAIlinear的 SKILL.mdVercel skills CLI GitHubopenai/skills 仓库状态deprecated