一个 SKILL.md 如何让 AI 学会一套可复用工作流？

很多人第一次使用 AI Agent 时，会把所有要求都写进一条很长的 Prompt：先读取文件，再按某种格式分析，最后生成报告，还要调用几个脚本。任务一多，这条 Prompt 会越来越长，也越来越难复用。

Agent Skills 提供了一个更像软件包的组织方式：把一套稳定的工作方法放进一个目录，用 SKILL.md 说明何时使用、应该怎么做，再按需附带脚本、参考资料和模板。

先给结论：Skill 是给 Agent 使用的“工作流软件包”

Agent Skills 的规范要求一个 Skill 至少包含一个 SKILL.md，并允许同时包含 scripts/、references/、assets/ 等目录。Agent Skills 规范

一个最小目录可能是：

pdf-report/
├── SKILL.md
├── scripts/
│   └── extract_tables.py
├── references/
│   └── report-style.md
└── assets/
    └── report-template.md

这和“把一堆提示词复制到聊天框里”最大的区别，是能力变成了可以版本控制、评审、测试和迁移的文件结构。

SKILL.md 最重要的不是写得长

一个好的 Skill 首先要让 Agent 能回答两个问题：

1. 什么时候应该使用我？
2. 使用我时，最关键的约束是什么？

规范要求 YAML frontmatter 至少包含 name 和 description。其中 description 不应该只写“处理 PDF”，而应该同时说明能力和触发条件，例如“提取 PDF 文本和表格，填写表单并合并文件；处理 PDF、表单或文档抽取任务时使用”。

正文再补充步骤、输入输出示例、边界情况和验证方式。

...
name: release-notes
description: 从 Git 提交和 PR 中生成版本说明。用户要求整理 changelog、release notes 或版本摘要时使用。
...

## 工作流程

1. 读取提交范围并过滤合并提交。
2. 按功能、修复和破坏性变更分类。
3. 检查每一条是否有可验证的依据。
4. 输出固定格式并列出未确定事项。

为什么要渐进式加载

如果所有 Skill 的全部细节一开始就塞进上下文，Agent 会消耗大量 token，还容易把不相关的规则混在一起。Agent Skills 规范采用渐进式披露：

• 启动时只读取名称和描述；
• 判断需要使用后，再读取完整的 SKILL.md；
• 只有执行任务时，才打开脚本、参考资料和资产。

这让“可复用能力”不再等于“永久占用上下文”。同时，它也要求 description 写得准确：描述太泛，Agent 可能不会触发；描述太宽，Agent 可能在不该使用时强行加载。

Skill、MCP 和 加载链接预览… 分别解决什么

这三个概念经常被混在一起，但分工不同：

例如，“制作 PDF 报告”可以由 Skill 提供流程；读取公司数据库可以通过 MCP；项目要求使用某种目录结构和测试命令，则写进 加载链接预览…。它们可以组合，但不应把所有内容塞进一个文件。

可执行脚本让 Skill 不只是建议

如果 Skill 只写“请检查文件并生成报告”，执行结果仍然依赖模型临场发挥。把确定性高的步骤做成脚本，能让 Agent 把判断力用在真正需要判断的地方。

例如：

• 脚本负责解析表格、校验 JSON、渲染 PDF；
• Skill 负责决定哪些字段重要、如何解释异常、什么时候需要人工确认；
• references/ 保存不适合重复写进主指令的详细规范。

这样既能减少重复劳动，也能让失败更容易定位：是脚本报错，还是 Agent 选错了流程？

Skill 的安全边界

Skill 可以携带脚本和资源，因此不能把它当作普通 Markdown 看待。发布或安装 Skill 时至少要检查：

1. 脚本是否会读取不必要的敏感文件；
2. 是否包含隐蔽的网络上传或外部命令；
3. 说明文字是否诱导 Agent 绕过用户确认；
4. allowed-tools 是否被误当成完整权限系统；
5. 参考资料中的指令是否会覆盖用户的明确要求。

规范中的 allowed-tools 仍是实验性字段，不同 Agent 的支持程度可能不同。真正的权限控制应该由宿主环境、沙箱和工具本身负责，而不是只依赖一段说明文字。

怎样把 Skill 做成精品

一个值得长期维护的 Skill 通常具备四个特点：

• 触发条件具体，明确“什么时候不该用”；
• 主流程短而完整，细节放入引用文件；
• 把高风险动作和人工确认点写清楚；
• 有可执行脚本和验证样例，而不是只有口号。

一句话总结：Skill 不是更长的 Prompt，而是一份可以被 Agent 发现、加载、执行和复用的工作流包。

来源

• Agent Skills 官方规范
• OpenAI Academy：Using skills