AI Agent Skill 从概念到实战：SKILL.md、渐进式加载与工作流复用

AI Agent Skill 从概念到实战：SKILL.md、渐进式加载与工作流复用

**摘要：**从一个真实任务出发，讲清 Agent Skill 是什么、何时触发、怎样分层加载、如何与工具和 MCP 配合。再拆解官方与 GitHub 项目的实际 Skill，并创建一个可复制到项目中的 Git 改动说明 Skill。

目录

1. 先用一句话理解 Skill
2. 为什么需要 Skill
3. Skill 目录里放什么
4. Agent 怎样发现、调用和逐层加载 Skill
5. Skill、Prompt、项目指令、MCP、工具和 Plugin 的区别
6. 从零实现一个代码变更总结 Skill
7. Codex、Claude Code、VS Code 和 CLI 用法
8. 四个真实 Skill 的源码拆解
9. 怎样验证、迭代和治理
10. 什么时候创建，什么时候不创建
11. 总结与参考资料

一、先用一句话理解 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 负责把这些动作组织成可重复的流程。第八节会沿着真实仓库文件拆开看。

二、为什么需要 Skill

2.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.yaml

3.1 Frontmatter：名称与触发描述

SKILL.md 以 YAML frontmatter 开头，至少包含 name 和 description：

---name:repo-change-summarydescription:总结 Git 仓库中的未提交改动并指出有依据的风险。用户询问改了什么、需要变更摘要或只读检查 diff 时使用；不要用于替代功能实现。---

规范要求 name 使用小写字母、数字和连字符，最多 64 个字符，且不能以连字符起止或出现连续连字符；通常与父目录同名。description 最多 1024 个字符，应写清做什么和什么时候使用，尽量使用用户真实会说的任务词。比如“帮助审查代码”太宽；“总结当前 Git 改动；用户问改了什么或需要只读检查 diff 时使用”更有区分度。

为什么description要写“何时用”？因为 Agent 在读到主文件前，通常只看得到这段描述。若只写“一个强大的开发助手”，系统无法分辨它适合代码审查、测试还是发布；若把数据库、React、写作等无关关键词全部塞进去，也容易误触发。OpenAI Docs：Build skills

规范还列出可选 license、compatibility、metadata 和实验性的 allowed-tools。不同 Agent 对可选字段支持不一；写入字段不等于获得宿主权限。字段规范

3.2 正文：将“仔细一点”改写成流程

正文应回答：开始前检查哪些输入；主要步骤是什么；信息不足或工具失败时怎么办；输出格式和完成条件是什么；哪些动作不允许或需要确认。

“仔细审查改动”不容易执行；“先读 diff，按正确性、安全性、兼容性检查；每条问题写位置、触发条件、影响和证据；没有问题也说明检查范围；不修改文件”，则更容易验收。

3.3 References、Scripts 和 Assets

• references/：让 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 Docs：Build 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 面对两次任务：

第三层的“按需”由正文中的条件触发，而非所有references/文件自动注入。

token 到底怎么省？

假设安装 20 个技能，每份说明约 1,500 tokens。如果每轮都把全部正文加入上下文，理论上这批文件约 30,000 tokens。分层方式先给较短的名称和描述；本轮选一个 Skill 后读其主说明；涉及特定领域时才打开对应参考文件。

这是解释原理的估算，不是任何产品承诺的实际 token 数。真实成本取决于宿主如何提供目录、描述和正文长度、读了多少参考文件及脚本输出。分层加载减少不相关上下文，但已读取内容仍要占上下文。

还要避免一个反效果：把几十页规则直接写进SKILL.md，一旦触发就会整篇进入上下文；把正文做成短目录，细节分到可按条件阅读的资料里，才有分层收益。Vercel 的 React 性能 Skill 把 70 条规则分文件组织，正好适合观察这种设计；但它也提供了一个很大的汇编文档，因此是否真的省上下文，还取决于 Agent 最后读了什么。Vercel Skill 入口

五、Skill、Prompt、项目指令、MCP、工具和 Plugin 的区别

以“完成一份有来源的 GitHub 项目分析”为例：Skill 定义搜索、核验和引用步骤；浏览器或 MCP 实际读取 GitHub；脚本可验证链接；项目指令约束文章风格；Plugin 可把工作流和连接一起分发。

OpenAI 文档概括：MCP 提供实时数据、授权连接和受控动作；Skill 指导何时调用工具、按什么顺序组合、如何处理不完整结果和交付内容。Skills 如何补充 MCP

六、从零实现一个代码变更总结 Skill

我们做一个适合初学者练手、又有实际用途的 Skill：只读总结当前 Git 改动。它需要区分尚未暂存、已经暂存和未跟踪文件；发现有数据库迁移时额外查看专项清单。本文给出完整文件内容，复制即可试用，不依赖未展示的后端程序。

6.1 创建目录

在项目根目录运行 PowerShell：

New-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：

# 输出模板 ## 变更摘要 - 用 2～5 条说明改动目的和范围，并区分工作区与暂存区。 ## 风险与问题 按严重程度排序。每条包含严重程度、路径或行号、触发条件、影响和依据。 没有可确认问题时，明确说明“未发现可确认的问题”。 ## 检查范围与待确认项 列出未读取的未跟踪文件、未执行的测试、缺少的环境和不确定之处。不得暗示未执行的检查已经通过。

再保存为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 Codex

Codex 文档列出项目、个人、管理员和系统等范围。项目级一般放在仓库.agents/skills/<name>/SKILL.md，适合随 Git 共享；个人级可放在~/.agents/skills/<name>/SKILL.md，用于跨项目复用。Codex 会从当前目录沿父目录扫描到仓库根，因此需在目标仓库中启动。OpenAI Docs：Skill 路径

可显式使用 $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 Copilot

VS Code 文档列出 .github/skills/、.claude/skills/、.agents/skills/ 等项目路径和用户路径，且要求父目录名与 frontmatter 的 name 一致。IDE、CLI、云端形态需分别核对。VS Code Agent Skills

7.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 没起作用”。前两类是发现与匹配，第三类是说明质量，最后一类是执行能力与授权。

八、四个真实 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 总结。脚本在发现失败检查时返回非零状态，不能简单把非零退出码理解成脚本崩溃。

可借鉴的分工如下：

这类 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 OpenAIlinear：Skill 与 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 用正例、负例测触发

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、提示工程

参考资料

1. Agent Skills 开放规范
2. OpenAI Docs：Build skills
3. OpenAI：Skills 如何补充 MCP
4. Anthropic Claude Code：Skills
5. VS Code：Use Agent Skills
6. OpenAI：Testing Agent Skills Systematically with Evals
7. OpenAI：技能描述与按需加载的实践
8. OpenAIgh-fix-ci的 SKILL.md 与脚本
9. Anthropicpdf的 SKILL.md
10. Vercel React 性能 Skill 及独立规则
11. OpenAIlinear的 SKILL.md
12. Vercel skills CLI GitHub
13. openai/skills 仓库状态（deprecated）