大模型Agent技能设计开发详解与最佳实践

一、Agent Skills 的本质定义

先讲几个关键认知：Agent Skills 并非颠覆物理定律的尖端技术，但在工程效率层面，它确实带来了“降维打击”的效果。其要解决的核心问题是——如何让 AI 在有限的上下文窗口内，只加载必要信息，而不是一次性塞入所有规则。

传统模式是：将全部指令、规则、示例写成一个巨型文本文件，每次启动对话就全量加载。假设该文件有 3000 行，约合 4 万 tokens。无论当前任务是否需要审校、配图、查资料，这 4 万 tokens 都得消耗。生成式 AI 的 Token 成本并不低廉，尤其在需要频繁迭代的高频场景下，这种“大水漫灌”的方式很快会成为效率瓶颈。

Agent Skills 则采用完全不同的策略——一种分层、按需加载的机制。通俗地说，就是“先给你目录，你需要哪一章，再递送内容”。下文将逐步拆解这套机制的具体实现。

二、opencode 中配置 Skill

那 Skills 到底如何配置？只有两条路径：本地路径和全局路径。

本地路径允许将 Skill 与特定代码仓库绑定。当其他开发者克隆项目后，也能立即使用这些为项目定制的 Skill。OpenCode 会从当前工作目录向上搜索，直至 Git 仓库根目录，并加载所有符合以下模式的 Skill 文件：

• .opencode/skill//SKILL.md
• .claude/skills//SKILL.md

全局路径则用于存放通用、与具体项目无关的 Skill。这些 Skill 定义在用户主目录下，对所有项目可见（注意，Windows 下全局路径实测为：C:Users用户名.configopencode\skills）：

• ~/.config/opencode/skill//SKILL.md
• ~/.claude/skills//SKILL.md
• ~/.agents/skills//SKILL.md

这里的 是一个目录名，必须与 Skill 本身的名称保持一致。这种目录结构确保每个 Skill 的定义都隔离在自己的文件夹内。结构示例如下：

三、Skills 内容设计

3.1 核心概念

几个关键概念需要厘清：

• SKILL.md：核心指令文件，必需。这是 Skills 的“大脑”。
• scripts/：可执行脚本，可选。当 SKILL.md 引用脚本时，opencode 会执行它。脚本代码本身不进入上下文，只有执行结果进入。这意味着你可以写一个 500 行的复杂脚本处理各种边界情况、错误逻辑，而 AI 只需知道“执行这个脚本”即可——Token 节约效果非常显著。
• references/：参考文档，可选。当任务需要更多信息时，opencode 会按需读取这些文档。这是渐进式披露策略，平时不加载。
• assets/：模板和资源，可选。例如报告模板、配置文件、样例数据。文件本身不进入上下文，只在输出时引用。

具体来说，这套机制分为三层：

第一层：元数据（Metadata）——始终加载

• 内容：SKILL.md 文件开头的 YAML 部分，仅两个字段：name 和 description。
• 加载时机：opencode 启动时即刻加载所有 Skills 的元数据。
• Token 成本：每个 Skill 约 100 tokens。即便安装 50 个 Skills，也仅 5000 tokens。
• 作用：让 opencode 知晓有哪些 Skills 可用，以及何时应该调用哪一个。

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

第二层：指令（Instructions）——触发时加载

• 内容：SKILL.md 的主体部分，详细的操作指南。
• 加载时机：当用户请求匹配某个 Skill 的 description 时，opencode 才加载该 Skill 的完整内容。
• Token 成本：通常在 3000-5000 tokens。
• 作用：指导 AI 具体执行步骤。

第三层：资源（Resources）——引用时加载

• 内容：scripts/ 目录里的脚本、references/ 目录里的参考文档、assets/ 目录里的模板。
• 加载时机：仅当 SKILL.md 中的指令引用这些文件时才加载。
• Token 成本：几乎无限——脚本执行后只有输出进入上下文，代码本身不占 Token。
• 作用：提供确定性的执行能力和详细的参考资料。

对比传统方式与 Skills 方式的 Token 消耗，差距一目了然：

• 传统方式：所有规则写在一个 xx.md 文件中，每次对话都加载。若有 3000 多行内容，约 4 万 tokens。不论是否需要，每次对话都烧 4 万 tokens。
• Skills 方式：
  • 平时只加载元数据：50 个 Skills × 100 tokens = 5000 tokens
  • 需要审校时，额外加载审校 Skill：+3000 tokens
  • 需要配图时，额外加载配图 Skill：+2000 tokens
  • 一次对话通常只用 1-2 个 Skills：总共约 10000 tokens

直接节省了 75% 的 Token 消耗。而且，这还没计入脚本的优势。

Skills 可以包含可执行脚本。例如，在一个“图片配图与上传”Skill 里有一个 Python 脚本，负责把图片上传至图床。当 opencode 执行这个脚本时，流程如下：

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

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

3.2 如何创建

创建 Skills 有两条途径。一种是直接手动编写，但说实话，既耗时又容易出错，且质量因人而异，波动较大。另一种是利用 opencode，借助官方开源的 skill-creator 来创建。举个例子，你只需告诉 opencode：“帮我创建一个 Skill，用来审校学术论文初稿。要检查事实准确性、去掉 AI 味、控制句子长度、使用学术用语。”它就会自动生成符合格式的文件。生成的过程和结果如下：

但无论采用哪种方式，动手之前有几个前提条件必须想清楚：

1. 明确要解决什么问题？这个问题是否重复出现？有没有必要写成 Skills？
2. 把工作流程写清楚
3. 提供足够的上下文和参考资料

3.3 基本结构

3.4 关键内容

3.4.1 YAML Frontmatter

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---
## What I do
- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me
Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

在上面的例子中，name 和 description 是必填项，直接决定 Agent 如何识别和选择 Skill。而 license、compatibility 和 metadata 等字段可选，用于提供额外信息。

关于 name 的规则：

• 长度在 1 到 64 个字符之间
• 只能包含小写字母、数字和单个连字符 -
• 不能以连字符开头或结尾
• 不能包含连续的连字符
• 最重要的一点：必须与存放 SKILL.md 文件的目录名完全相同

关于 description 的规则：

• 长度限制在 1 到 1024 个字符之间
• 描述应具体、明确，准确传达 Skill 的核心用途
• 触发关键词至关重要——这是 Agent 判断“何时该用这个 Skill”的核心依据

3.4.2 Markdown 正文

正文部分需要包含以下内容：

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

建议控制在 500 行以内。如果需要更多内容，放到 references/ 目录下，走渐进式披露的路线。这其实很像 Prompt 的设计规则——写得越清晰，AI 的执行效果就越好。

四、Skills 案例拆解

4.1 skill-creator 概述

这个技能的主要功能包括：

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

4.2 核心设计原则

4.2.1 简洁性原则

这一原则的核心是：让每个 Skill 只做一件事，并且做到最好。

4.2.2 适当的自由度

自由度是指 Skill 运行时，Agent 可以发挥的灵活空间。具体可以分为三个层级：

• 高自由度（基于文本的指令）：多种方法有效，决策依赖上下文。适合策略性任务。
• 中自由度（带参数的伪代码或脚本）：存在首选模式，允许一定变化。适合半结构化任务。
• 低自由度（特定脚本，少量参数）：操作脆弱易错，一致性至关重要。适合确定性任务。

4.2.3 渐进式披露

这是 Skills 最核心的设计哲学。它完美体现了“每次只给你需要的那部分”的工程思想：

1. 元数据（名称+描述）：始终在上下文中，约 100 词，用于技能触发判断
2. SKILL.md 正文：技能触发时加载，限制在 5000 词以内，包含核心工作流程
3. 捆绑资源：根据需要加载，无限容量，因为脚本可不读入上下文

4.3 技能结构分析

4.3.1 SKILL.md（必需文件）

• 前导码（YAML）：包含 name 和 description 字段，是技能触发的主要机制
• 正文（Markdown）：技能的使用说明和指南，仅在技能触发后加载

4.3.2 捆绑资源（可选）

4.4 渐进式披露设计

4.4.1 三级加载系统

再强调一遍这套系统的关键数据：

1. 第一级：元数据（名称+描述）——始终保持在上下文中，约 100 词，用于技能触发判断
2. 第二级：SKILL.md 正文——仅在技能触发后加载，限制在 5000 词以内，包含核心工作流程
3. 第三级：捆绑资源——根据任务需要按需加载，脚本可直接执行而不读入上下文

4.4.2 设计模式

• 高级指南与参考文件模式：在 SKILL.md 中提供核心工作流程，详细内容放在参考文件中
• 特定领域组织模式：按领域组织内容，避免加载不相关上下文
• 条件详细信息模式：显示基本内容，链接到高级内容，按需加载

4.5 技能创建流程

标准流程分为六步：

1. 步骤1：通过具体示例理解 skills
2. 步骤2：规划可重用 skills 内容
3. 步骤3：初始化 skills
4. 步骤4：编辑 skills
5. 步骤5：打包 skills
6. 步骤6：迭代优化

4.6 设计模式与最佳实践

4.6.1 技能文件组织

• 避免深度嵌套引用：参考文件应直接从 SKILL.md 链接，保持一级深度
• 结构化长文件：超过 100 行的文件应在顶部包含目录
• 避免重复：信息应位于 SKILL.md 或参考文件中，不能同时存在

4.6.2 写作指南

• 前导码 description 字段应包含所有“何时使用此技能”的信息
• 正文中不应包含“何时使用”部分，因为仅在触发后加载
• 避免使用不必要的辅助文档文件（README.md、CHANGELOG.md 等），它们会额外消耗 Token，且没有实际收益

4.7 总结

综合来看，这套技能体系的核心价值可以用三个关键词概括：

• 模块化设计：通过渐进式披露优化上下文使用效率
• 标准化流程：六步创建流程确保技能质量一致性
• 资源重用：scripts、references、assets 资源减少重复工作
• 质量控制：验证和打包脚本确保技能符合标准

这个技能本身也体现了软件工程的最佳实践，包括关注点分离、渐进式披露、资源优化和迭代开发。它为创建高质量、可维护的技能提供了完整解决方案。如果你正在做 AI 驱动的自动化工具开发，这套思路值得花时间深入理解。