Agent Skills 设计详解：大模型开发中的技能封装与复用

第二层：指令（Instructions）

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

第三层：资源（Resources）

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

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

3. 脚本的优势

Skills 可以包含可执行脚本。例如'图片配图与上传'Skill 中包含 Python 脚本负责上传图片到图床。

当 OpenCode 执行脚本时：

1. 生成 bash 命令：python scripts/upload_image.py image.png
2. 脚本在本地执行
3. 只有执行结果（图床 URL）返回给系统

脚本代码本身不进入上下文。你可以写 500 行的 Python 脚本处理边界情况、错误处理和日志记录，系统只需知道'执行这个脚本'。这是 Skills 比传统 Prompt 更强的地方：可以封装确定性的执行能力。

四、如何创建

创建方法主要有两种：

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

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

1. 想清楚解决什么问题？是否重复性？是否有必要写 Skills？
2. 把工作流程写清楚。
3. 提供足够的 context 和参考资料。

基本结构

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

关键内容

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

1. 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 字符。应具体、明确，触发关键词很重要。
• 其他字段：如 license、compatibility、metadata 为可选。

2. Markdown 正文

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

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

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

五、案例拆解

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

1. 核心功能

• 提供技能创建工作流和最佳实践
• 定义结构和组成要素
• 实施渐进式披露原则优化上下文
• 包含工具脚本和模板文件
• 提供验证和打包功能

2. 设计原则

• 简洁性：上下文是公共资源，只添加真正需要的信息。偏好简洁示例而非冗长解释。
• 适当的自由度：根据任务脆弱性设置自由度。高自由度（文本指令）、中自由度（带参数伪代码）、低自由度（特定脚本）。
• 渐进式披露：三级加载系统管理上下文效率。

3. 结构分析

• SKILL.md（必需）：前导码（YAML）+ 正文（Markdown）。
• 捆绑资源（可选）：
  • scripts/：可执行代码，用于确定性任务。
  • references/：文档材料，按需加载。
  • assets/：输出文件（模板、图标），不加载到上下文。

4. 创建流程

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

5. 最佳实践

• 文件组织：避免深度嵌套引用，保持一级深度；超过 100 行的文件顶部加目录；避免重复信息。
• 写作指南：使用命令式/不定式形式，保持简洁。Frontmatter 的 description 包含'何时使用'，正文中不再重复此部分。避免不必要的辅助文档。

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