[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"$f24Dswx1jRADOS80MAsWtxR4GdehZhP4eRJF3mb7PWX0":3},{"item":4,"related":51},{"id":5,"type":6,"title":7,"slug":8,"summary":9,"body":10,"coverUrl":11,"productScreenshots":12,"productLinks":13,"authorName":14,"authorUrl":15,"authorSubject":16,"category":17,"tags":22,"sourceLabel":39,"sourceName":40,"sourceUrl":41,"status":42,"seoTitle":43,"seoDescription":44,"canonicalUrl":45,"isFeatured":46,"sno":47,"sortOrder":48,"publishedAt":49,"updatedAt":50,"createdAt":50},"a2052bdb-8828-4c3c-8393-36172844bc57","article","一个 SKILL.md 如何让 AI 学会一套可复用工作流？","agent-skills-skill-md-workflows","Agent Skills 把一套工作方法打包成包含 SKILL.md、脚本、参考资料和资产的目录。本文解释 Skill 与 Prompt、MCP、AGENTS.md 的区别，拆解渐进式加载和可执行脚本，并讨论技能包的安全边界。","很多人第一次使用 AI Agent 时，会把所有要求都写进一条很长的 Prompt：先读取文件，再按某种格式分析，最后生成报告，还要调用几个脚本。任务一多，这条 Prompt 会越来越长，也越来越难复用。\n\nAgent Skills 提供了一个更像软件包的组织方式：把一套稳定的工作方法放进一个目录，用 `SKILL.md` 说明何时使用、应该怎么做，再按需附带脚本、参考资料和模板。\n\n## 先给结论：Skill 是给 Agent 使用的“工作流软件包”\n\nAgent Skills 的规范要求一个 Skill 至少包含一个 `SKILL.md`，并允许同时包含 `scripts\u002F`、`references\u002F`、`assets\u002F` 等目录。[Agent Skills 规范](https:\u002F\u002Fagentskills.io\u002Fspecification)\n\n一个最小目录可能是：\n\n```text\npdf-report\u002F\n├── SKILL.md\n├── scripts\u002F\n│   └── extract_tables.py\n├── references\u002F\n│   └── report-style.md\n└── assets\u002F\n    └── report-template.md\n```\n\n这和“把一堆提示词复制到聊天框里”最大的区别，是能力变成了可以版本控制、评审、测试和迁移的文件结构。\n\n## `SKILL.md` 最重要的不是写得长\n\n一个好的 Skill 首先要让 Agent 能回答两个问题：\n\n1. **什么时候应该使用我？**\n2. **使用我时，最关键的约束是什么？**\n\n规范要求 YAML frontmatter 至少包含 `name` 和 `description`。其中 description 不应该只写“处理 PDF”，而应该同时说明能力和触发条件，例如“提取 PDF 文本和表格，填写表单并合并文件；处理 PDF、表单或文档抽取任务时使用”。\n\n正文再补充步骤、输入输出示例、边界情况和验证方式。\n\n```markdown\n...\nname: release-notes\ndescription: 从 Git 提交和 PR 中生成版本说明。用户要求整理 changelog、release notes 或版本摘要时使用。\n...\n\n## 工作流程\n\n1. 读取提交范围并过滤合并提交。\n2. 按功能、修复和破坏性变更分类。\n3. 检查每一条是否有可验证的依据。\n4. 输出固定格式并列出未确定事项。\n```\n\n## 为什么要渐进式加载\n\n如果所有 Skill 的全部细节一开始就塞进上下文，Agent 会消耗大量 token，还容易把不相关的规则混在一起。Agent Skills 规范采用渐进式披露：\n\n- 启动时只读取名称和描述；\n- 判断需要使用后，再读取完整的 `SKILL.md`；\n- 只有执行任务时，才打开脚本、参考资料和资产。\n\n这让“可复用能力”不再等于“永久占用上下文”。同时，它也要求 description 写得准确：描述太泛，Agent 可能不会触发；描述太宽，Agent 可能在不该使用时强行加载。\n\n## Skill、MCP 和 AGENTS.md 分别解决什么\n\n这三个概念经常被混在一起，但分工不同：\n\n| 机制 | 主要回答的问题 |\n| --- | --- |\n| Skill | 这类任务应该按什么方法完成？ |\n| MCP | Agent 怎样连接外部工具和数据？ |\n| AGENTS.md | 在这个仓库里应该遵守哪些项目规则？ |\n\n例如，“制作 PDF 报告”可以由 Skill 提供流程；读取公司数据库可以通过 MCP；项目要求使用某种目录结构和测试命令，则写进 AGENTS.md。它们可以组合，但不应把所有内容塞进一个文件。\n\n## 可执行脚本让 Skill 不只是建议\n\n如果 Skill 只写“请检查文件并生成报告”，执行结果仍然依赖模型临场发挥。把确定性高的步骤做成脚本，能让 Agent 把判断力用在真正需要判断的地方。\n\n例如：\n\n- 脚本负责解析表格、校验 JSON、渲染 PDF；\n- Skill 负责决定哪些字段重要、如何解释异常、什么时候需要人工确认；\n- `references\u002F` 保存不适合重复写进主指令的详细规范。\n\n这样既能减少重复劳动，也能让失败更容易定位：是脚本报错，还是 Agent 选错了流程？\n\n## Skill 的安全边界\n\nSkill 可以携带脚本和资源，因此不能把它当作普通 Markdown 看待。发布或安装 Skill 时至少要检查：\n\n1. 脚本是否会读取不必要的敏感文件；\n2. 是否包含隐蔽的网络上传或外部命令；\n3. 说明文字是否诱导 Agent 绕过用户确认；\n4. `allowed-tools` 是否被误当成完整权限系统；\n5. 参考资料中的指令是否会覆盖用户的明确要求。\n\n规范中的 `allowed-tools` 仍是实验性字段，不同 Agent 的支持程度可能不同。真正的权限控制应该由宿主环境、沙箱和工具本身负责，而不是只依赖一段说明文字。\n\n## 怎样把 Skill 做成精品\n\n一个值得长期维护的 Skill 通常具备四个特点：\n\n- 触发条件具体，明确“什么时候不该用”；\n- 主流程短而完整，细节放入引用文件；\n- 把高风险动作和人工确认点写清楚；\n- 有可执行脚本和验证样例，而不是只有口号。\n\n一句话总结：**Skill 不是更长的 Prompt，而是一份可以被 Agent 发现、加载、执行和复用的工作流包。**\n\n## 来源\n\n- [Agent Skills 官方规范](https:\u002F\u002Fagentskills.io\u002Fspecification)\n- [OpenAI Academy：Using skills](https:\u002F\u002Fopenai.com\u002Facademy\u002Fskills\u002F)","\u002Fuploads\u002F2026-09-08\u002Fea16f4b5-cdb3-4d44-8bb2-4e07bbe90ee7.jpg",[],[],"Foundit","https:\u002F\u002Ffoundit.cn","foundit-ai-editorial",{"id":18,"name":19,"slug":20,"description":21},"6179d3b6-dc34-4483-9ded-3cd9f1b37a47","科普","abbreviation","介绍各领域新兴概念",[23,27,31,35],{"id":24,"name":25,"slug":26},"88d2bc27-0e0f-468a-b907-2991cb97b87b","人工智能","ai",{"id":28,"name":29,"slug":30},"0848beb4-db26-4fb8-b391-f852a11be192","AI编程","ai-coding",{"id":32,"name":33,"slug":34},"a202d639-99a6-488a-a712-4d4c6ffd7e15","开发","dev",{"id":36,"name":37,"slug":38},"144abe77-0dc6-4f66-a176-20bddb1c0bfa","编程","coding","Agent Skills 官方规范","Agent Skills Specification","https:\u002F\u002Fagentskills.io\u002Fspecification","published","Agent Skills 与 SKILL.md：让 AI 复用工作流的文件规范","从目录结构、frontmatter、渐进式披露和脚本资源出发，解释 Agent Skills 如何把长 Prompt 变成可复用、可审查的工作流包。",null,false,46,0,"2026-09-08T00:00:00.000Z","2026-09-08T03:19:24.073Z",[52,61,71],{"id":53,"type":6,"title":54,"slug":55,"summary":56,"coverUrl":57,"authorName":14,"sno":58,"publishedAt":59,"createdAt":60},"871e57ba-8d0e-4f70-a706-b7ec5f472ea7","Skill是什么？","what-is-skill","一套可复用、可安装、可共享的任务说明","https:\u002F\u002Foxqtewbrpuiouqqjrvdv.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fpublic-media\u002F2026-07-18\u002F4c35d873-e4f1-418f-a9ae-bb56d85df6ff.jpg",45,"2026-06-11T00:00:00.000Z","2026-07-18T15:17:09.969Z",{"id":62,"type":6,"title":63,"slug":64,"summary":65,"coverUrl":66,"authorName":67,"sno":68,"publishedAt":69,"createdAt":70},"d55f78f9-5755-434f-9f6f-462a0ff764c7","氛围编程避坑","vibe-coding-reminds","AI能写代码，但不能替你负责","https:\u002F\u002Foxqtewbrpuiouqqjrvdv.supabase.co\u002Fstorage\u002Fv1\u002Fobject\u002Fpublic\u002Fpublic-media\u002F2026-07-17\u002F867d174b-fbb8-4a1c-8bbf-f12a2881e763.jpg","GPT-5.6 Sol",54,"2026-07-01T00:00:00.000Z","2026-07-17T15:47:16.293Z",{"id":72,"type":6,"title":73,"slug":74,"summary":75,"coverUrl":76,"authorName":14,"sno":77,"publishedAt":78,"createdAt":79},"190a2a0d-4b47-40f7-902a-00ac69ce1b15","AI 编程时代，为什么 Git 和 Pull Request 更重要了","ai-coding-git-pull-request-safety-net","AI 让改动出现得更快，也让变化更难凭记忆追踪。本文解释小提交、Pull Request、自动检查和人工批准如何把 AI 编程变成可比较、可验证、可回滚的协作流程。","\u002Fuploads\u002F2026-09-13\u002F95ac3b51-0915-4200-8130-4ba3195fd935.jpg",40,"2026-09-13T00:00:00.000Z","2026-09-13T11:56:01.900Z"]