Agent Skills 设计详解：构建可复用的 AI 智能体工作流

第一层：元数据（Metadata）

• 内容：SKILL.md 开头的 YAML 部分，含 name 和 description。
• 时机：启动时加载所有 Skills 的元数据。
• 成本：约 100 tokens/Skill。即使装 50 个，也仅 5000 tokens。
• 作用：让系统知道有哪些可用技能。

--- name: ai-proofreading description: 系统化降低 AI 检测率，增加人味。使用场景：审校文章、降低 AI 味、初稿完成后。 ---

第二层：指令（Instructions）

• 内容：SKILL.md 主体，详细操作指南。
• 时机：用户请求匹配某个 Skill 的 description 时加载。
• 成本：通常 3000-5000 tokens。
• 作用：告诉 Agent 具体怎么做。

第三层：资源（Resources）

• 内容：scripts、references、assets 中的文件。
• 时机：仅在指令引用时加载。
• 成本：脚本执行后只有输出进入上下文，代码本身不占 Token。
• 作用：提供确定性执行能力和参考资料。

这种设计非常高效。传统方式将所有规则写在一个文件中，每次对话都加载，若有 3000 多行内容可能消耗 4 万 tokens。而 Skills 方式平时只加载元数据，需要时额外加载对应技能，一次对话通常只用 1-2 个，总消耗约 1 万 token，节省了 75% 的 Token 消耗。

此外，脚本的执行优势在于可以封装复杂逻辑。例如上传图床的 Python 脚本，OpenCode 只需生成命令执行，无需理解每一行代码，这是比传统 Prompt 更强的地方。可以封装确定性的执行能力。

创建流程

创建方法主要有两种：

1. 直接手撸：费时费力，质量波动大。
2. 利用工具：借助官方开源的 skill-creator 创建。例如告诉 OpenCode：'帮我创建一个 Skill，用来审校学术论文初稿。要检查事实准确性、去掉 AI 味、控制句子长度'。它会帮你生成符合格式的文件。

无论哪种方式，创建前需明确：

• 想清楚要解决什么问题？是否重复性高？
• 把工作流程写清楚。
• 提供足够的 context 和参考资料。

基本结构

一个 Skill 就是一个文件夹，里面至少有一个 SKILL.md 文件，且文件夹命名要与 SKILL.md 中 YAML Frontmatter 的 name 字段完全一致。

关键内容

每个 SKILL.md 由两部分组成：YAML Frontmatter 和 Markdown 正文。

YAML Frontmatter

位于文件顶端，用 --- 分隔，定义元数据。Agent 通过这些发现和理解 Skill 用途。合法文件必须包含 name 和 description。

--- name: git-release description: Create consistent releases and changelogs license: MIT compatibility: opencode metadata: audience: maintainers workflow: github ---

• name：1-64 字符，小写字母、数字和单个连字符，不能以连字符开头或结尾，无连续连字符。最重要的是必须与目录名相同。
• description：1-1024 字符，具体明确，触发关键词很重要。

Markdown 正文

使用标准 Markdown 语法，详细说明：

• 使用场景
• 核心目标
• 执行逻辑
• 示例输入/输出
• 注意事项等

建议控制在 500 行以内，如需更多内容，放到 references/ 目录下。这部分类似于 Prompt 设计规则，编写越清晰，Agent 执行效果越好。

案例拆解：skill-creator

为了深入理解，我们以官方发布的 skill-creator 为例进行拆解。这是一个元技能，专门指导如何创建其他技能，将 Agent 转变为具备特定领域专业知识的专业代理。

核心功能

1. 提供技能创建的工作流程和最佳实践
2. 定义技能和组成要素
3. 实施渐进式披露设计原则
4. 包含工具脚本和模板文件
5. 提供验证和打包功能

设计原则

简洁性原则

上下文窗口是公共资源，技能应只添加真正需要的信息。偏好简洁示例而非冗长解释。

适当的自由度

根据任务脆弱性设置自由度：

• 高自由度：基于文本指令，多种方法有效。
• 中自由度：带参数伪代码或脚本，存在首选模式。
• 低自由度：特定脚本，一致性至关重要。

渐进式披露

通过三级加载系统管理上下文效率：

1. 元数据（名称 + 描述）：始终在上下文中。
2. SKILL.md 正文：触发后加载。
3. 捆绑资源：按需加载。

结构分析

SKILL.md（必需）

• 前导码（YAML）：包含 name 和 description，是触发机制。
• 正文（Markdown）：使用说明和指南，触发后加载。

捆绑资源（可选）

创建流程

1. 理解技能：通过示例明确支持的功能和场景。
2. 规划内容：识别重复性工作，规划 scripts、references 和 assets。
3. 初始化：运行 init_skill.py 创建目录结构和模板。
4. 编辑实现：更新 SKILL.md，遵循设计模式。
5. 打包验证：运行 package_skill.py 创建可分发文件。
6. 迭代优化：基于反馈持续改进。

最佳实践

文件组织

• 避免深度嵌套引用，保持一级深度。
• 结构化长文件，顶部包含目录。
• 避免重复，信息只存在于一处。

写作指南

• 使用命令式/不定式形式，保持简洁。
• description 字段包含'何时使用'，正文中不再重复。
• 避免不必要的辅助文档文件。

该技能体现了软件工程的最佳实践，包括关注点分离、渐进式披露和资源优化，为创建高质量、可维护的技能提供了完整解决方案。