解析 OpenClaw AgentSkills：AI Agent 如何通过「技能包」实现专业化解析 AgentSkill

解析 AgentSkills：AI Agent 如何通过「技能包」实现专业化

📍 导航指南

根据你的背景，选择合适的阅读路径：

🤔 想了解为什么需要 Skills？ → 第一部分：从通用到专业 - 理解 AgentSkills 的设计动机
🔬 想看 Skill 的内部结构？ → 第二部分：Skill 解剖 - 掌握 SKILL.md、资源分类、渐进披露
🛠️ 想动手创建 Skill？ → 第三部分：创建流程 6 步法 - 从需求理解到打包分发
💡 想提炼设计哲学？ → 第四部分：设计哲学 - 三大核心原则与实践启示

第一部分：从通用到专业 🤔

Agent 的「知识诅咒」

你有没有遇到过这种场景：

让 Agent 帮你处理一个 PDF —— 旋转页面、提取文本、填写表单。Agent 每次都从头推理该用什么库、写一段差不多的代码、踩一遍差不多的坑。

或者让它帮你写一个 BigQuery 查询。它不知道你的表结构，不知道字段含义，花了一半 token 在"探索数据库长什么样"上。

这就是通用 Agent 的困境：它什么都能做，但什么都不够熟练。

这和人类新员工入职的情况一模一样 —— 一个聪明的应届生，能力很强，但缺乏领域特定的程序性知识（procedural knowledge）。他不知道公司的 API 规范是什么、数据库表结构长什么样、代码模板该怎么用。

解决方案？岗前培训。

Skills = Agent 的岗前培训手册

SKILL.md 原文对 Skills 的定义是：

Skills are modular, self-contained packages that extend Codex's capabilities by providing specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific domains or tasks—they transform Codex from a general-purpose agent into a specialized agent equipped with procedural knowledge that no model can fully possess.

逐句拆解：

原文	解读
modular, self-contained packages	模块化、自包含。一个 Skill 就是一个完整的文件夹，拿来即用，不依赖外部状态
specialized knowledge, workflows, and tools	不只是"知识"，还包括工作流（怎么做）和工具（用什么做）
"onboarding guides"	岗前培训手册 —— 这个比喻精准。不是教 Agent "什么是编程"，而是告诉它"我们公司怎么编程"
procedural knowledge that no model can fully possess	关键词：程序性知识。模型训练数据里不可能包含你公司的 API 规范、数据库 schema、业务逻辑

💡 通俗点说：Skills 就是把你的私有知识"注入"到 Agent 中，让它从"聪明的通才"变成"懂你业务的专家"。

Skills 提供什么？

SKILL.md 列出了 Skills 的四大能力：

1. Specialized workflows  - 特定领域的多步骤流程
2. Tool integrations      - 与特定文件格式或 API 的集成
3. Domain expertise       - 公司级知识、Schema、业务逻辑
4. Bundled resources      - 打包的脚本、参考文档和素材

我用一张表来对应人类世界的类比：

Skill 能力	人类类比	具体例子
Specialized workflows	标准操作流程（SOP）	"处理客户退款时，先查订单状态 → 核实原因 → 发起退款 → 通知客户"
Tool integrations	工具使用手册	"公司用 Jira 管任务，用 Confluence 写文档，用 Slack 沟通"
Domain expertise	业务知识培训	"我们的用户表叫 `dim_users`，金额字段用 NUMERIC 不用 FLOAT"
Bundled resources	工具箱 + 模板库	"这是代码模板，这是 API 文档，这是品牌素材包"

小结：AgentSkills 解决的核心问题是 —— 通用大模型缺乏你的私有程序性知识。Skills 通过模块化的"岗前培训包"，将领域知识、工作流和工具打包注入 Agent，实现从通用到专业的转变。

第二部分：Skill 解剖 🔬

一个 Skill 的完整结构

先看 SKILL.md 给出的标准目录：

skill-name/
├── SKILL.md              ← 必需：唯一的入口文件
└── Bundled Resources     ← 可选：三类打包资源
    ├── scripts/          - 可执行代码（Python/Bash 等）
    ├── references/       - 参考文档（按需加载到上下文）
    └── assets/           - 输出素材（模板、图片、字体等）

关键观察：整个 Skill 只有一个必需文件 —— SKILL.md。其他一切都是可选的。

这个设计选择非常刻意。它意味着：

最简单的 Skill 就是一个 Markdown 文件
复杂度是逐步叠加的，不是一开始就强制的
入门门槛极低：写个 Markdown 就是一个 Skill

SKILL.md：唯一的必需文件

SKILL.md 由两部分组成：

---
name: pdf-editor                    ← YAML frontmatter（元数据）
description: "处理 PDF 文件..."      ← 触发条件描述
---

# PDF Editor                        ← Markdown body（使用说明）

## 使用方法
...

Frontmatter：决定 Skill "什么时候上场"

Frontmatter 只有两个字段：name 和 description。

这里有一个容易被忽略的重要设计：

These are the only fields that Codex reads to determine when the skill gets used, thus it is very important to be clear and comprehensive in describing what the skill is, and when it should be used.

翻译一下：Codex 决定是否触发一个 Skill，只看 frontmatter 的 name 和 description。Body 部分在触发之前根本不会被读取。

这意味着 description 字段承担了极其关键的职责 —— 它是 Skill 的"简历摘要"，必须在有限的 token 里把"我是谁"和"什么时候该叫我"说清楚。

来看一个好的 description 示例（来自原文）：

description: >
  Comprehensive document creation, editing, and analysis
  with support for tracked changes, comments, formatting
  preservation, and text extraction. Use when Codex needs
  to work with professional documents (.docx files) for:
  (1) Creating new documents,
  (2) Modifying or editing content,
  (3) Working with tracked changes,
  (4) Adding comments, or any other document tasks

分析这个 description 的结构：

部分	内容	作用
第一句	"Comprehensive document creation, editing..."	我是谁 —— 能力概述
"Use when..."	"Use when Codex needs to work with..."	什么时候用我 —— 触发条件
编号列表	"(1) Creating... (2) Modifying..."	具体场景枚举 —— 提高匹配精度

💡 设计启示：description 不是给人看的文档说明，而是给 LLM 做语义匹配的触发器。写法应该像搜索引擎的 SEO 描述 —— 要覆盖所有可能的用户意图。

Body：触发后才加载的操作手册

原文明确指出：

Include all "when to use" information here [in description] - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Codex.

这是一个常见的反模式警告：不要在 body 里写"什么时候使用本 Skill"，因为 body 在触发后才加载，写了也没用。这和人类世界里"把重要电话号码写在锁在保险箱里的笔记本上"一样荒谬。

小结：SKILL.md 是 Skill 的唯一入口。Frontmatter（name + description）负责触发匹配，是 Skill 的"简历"；Body 负责操作指导，是触发后才展开的"培训手册"。

三类资源：scripts / references / assets

Skill 可以携带三类打包资源，每类有截然不同的定位：

资源类型	定位	是否需要读入上下文	典型场景
`scripts/`	可执行代码	不一定 —— 可直接执行	`rotate_pdf.py`、`validate_schema.sh`
`references/`	参考文档	是 —— 按需加载	`schema.md`、`api_docs.md`、`policies.md`
`assets/`	输出素材	否 —— 用于最终输出	`logo.png`、`template.pptx`、`font.ttf`

三者的核心区别在于与上下文窗口的关系：

scripts/    → 可以绕过上下文窗口（直接执行，不需要读）
references/ → 按需进入上下文窗口（读了才能用）
assets/     → 完全不进入上下文窗口（被复制/引用，不被"理解"）

这个分类不是随意的。它反映了一个深层设计考量：上下文窗口是稀缺资源，必须精打细算。

scripts/ 的精妙之处

原文说：

Benefits: Token efficient, deterministic, may be executed without loading into context

脚本可以不加载到上下文就直接执行。这意味着一个 500 行的 Python 脚本，不占用任何 token，就能完成任务。这是 scripts 相比 references 的最大优势。

但原文也留了一个后门：

Scripts may still need to be read by Codex for patching or environment-specific adjustments

有时候 Agent 需要先读懂脚本、做一些环境适配后再执行。这说明 scripts 的"零 token"优势不是绝对的。

references/ 的使用原则

原文给了一条重要的实践指南：

If files are large (>10k words), include grep search patterns in SKILL.md

当参考文档超过 1 万词时，应该在 SKILL.md 里提供 grep 搜索模式，让 Agent 能精准定位需要的段落，而不是把整个文档塞进上下文。

还有一条关于去重的原则：

Information should live in either SKILL.md or references files, not both.

信息只能存在于一个地方。SKILL.md 放核心流程，references 放详细参考。不要两边都写。

小结：三类资源的设计围绕一个核心问题 —— 如何高效利用上下文窗口。scripts 可以零 token 执行，references 按需加载，assets 完全不占 token。这是对 LLM 有限上下文的精细化管理。

三级渐进披露：上下文窗口的精细管理

这是整个 SKILL.md 规范中我认为最精彩的设计。原文描述了一个三级加载系统：

Level 1: Metadata (name + description)  → 始终在上下文中    (~100 words)
Level 2: SKILL.md body                  → Skill 触发时加载  (<5k words)
Level 3: Bundled resources              → Agent 按需加载    (无上限*)

*scripts 可以不加载就执行，所以理论上无上限。

用一张图来理解这个层级：

┌─────────────────────────────────────────────┐
│           上下文窗口 (Context Window)         │
│                                             │
│  ┌───────────────────┐  ← 永远在这里         │
│  │ Level 1: Metadata │  (~100 words)        │
│  │ name + description│  所有 Skill 的元数据   │
│  └───────────────────┘                      │
│                                             │
│  ┌───────────────────┐  ← 触发时加载         │
│  │ Level 2: Body     │  (<5k words)         │
│  │ 操作指南 + 流程    │  只有被选中的 Skill    │
│  └───────────────────┘                      │
│                                             │
│  ┌───────────────────┐  ← 需要时才加载       │
│  │ Level 3: 资源      │  (按需)              │
│  │ references/某个文件 │  只加载需要的那一个    │
│  └───────────────────┘                      │
│                                             │
│  ┌ ─ ─ ─ ─ ─ ─ ─ ─ ─┐                     │
│    scripts/           │  ← 可能完全不进入     │
│  │ 直接执行，不占 token │    上下文窗口        │
│  └ ─ ─ ─ ─ ─ ─ ─ ─ ─┘                     │
└─────────────────────────────────────────────┘

为什么说这个设计精彩？因为原文点明了一个经常被忽略的事实：

The context window is a public good. Skills share the context window with everything else Codex needs: system prompt, conversation history, other Skills' metadata, and the actual user request.

上下文窗口是公共资源。你的 Skill 和系统提示词、对话历史、其他 Skill 的元数据、用户的请求，都在争夺同一块有限空间。

这和计算机科学中的内存管理、操作系统的虚拟内存有异曲同工之妙：

概念	操作系统类比	AgentSkills 对应
物理内存	RAM	上下文窗口
虚拟内存	磁盘交换	打包资源文件
页面调度	按需调页（demand paging）	三级渐进披露
常驻内存	内核代码	Level 1 元数据
可换出页	用户进程	Level 2-3 内容

💡 通俗点说：渐进披露就是上下文窗口的"虚拟内存"机制 —— 不是所有信息都需要同时驻留在有限的"内存"中，大部分内容可以放在"磁盘"上按需加载。

渐进披露实战模式

SKILL.md 给出了三种实战模式。我逐一分析：

模式一：高层指南 + 参考文档

# PDF Processing

## Quick start
Extract text with pdfplumber:
[code example]

## Advanced features
- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods

适用场景：Skill 有一个核心功能 + 多个高级功能。SKILL.md 只展示核心用法，高级功能按需跳转。

类比：像一本书的目录页 —— 快速上手在第一章，想深入再翻后面的章节。

模式二：按领域组织

bigquery-skill/
├── SKILL.md (overview and navigation)
└── reference/
    ├── finance.md    (revenue, billing metrics)
    ├── sales.md      (opportunities, pipeline)
    ├── product.md    (API usage, features)
    └── marketing.md  (campaigns, attribution)

适用场景：Skill 覆盖多个互不相关的领域。用户问销售数据时，不需要加载财务文档。

关键设计：每次只加载一个领域的文档，避免"知识污染"。

这个模式也适用于多框架/多供应商的场景：

cloud-deploy/
├── SKILL.md
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

用户选了 AWS，就只加载 aws.md。不会让 GCP 和 Azure 的信息干扰决策。

模式三：条件展开

# DOCX Processing

## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

适用场景：基本操作写在 SKILL.md 里，只有遇到特定复杂场景时才展开详细文档。

类比：像医疗诊断指南 —— 常见症状直接给方案，罕见情况才翻查专科手册。

重要约束

原文给出两条硬性约束：

避免深层嵌套 —— 所有 reference 文件直接从 SKILL.md 链接，只有一层深度
长文件加目录 —— 超过 100 行的 reference 文件，顶部必须加目录（Table of Contents）

第一条避免了"引用链"问题（A 引用 B，B 引用 C，Agent 迷路了）。第二条让 Agent 在打开大文件时能快速定位。

小结：渐进披露是 AgentSkills 的核心架构思想。通过三级加载（元数据 → body → 资源），实现了上下文窗口的精细管理。三种实战模式（高层指南、领域分割、条件展开）覆盖了绝大多数场景。核心原则：只在需要时加载需要的内容。

第三部分：创建流程 6 步法 🛠️

SKILL.md 给出了一个清晰的 6 步创建流程。我会逐步拆解每一步的设计意图和实践要点。

Step 1：用具体案例理解需求

原文说：

To create an effective skill, clearly understand concrete examples of how the skill will be used.

这一步看似简单，实则是整个流程的基石。原文特别强调了 concrete examples（具体案例）这个词。

为什么强调"具体"？因为抽象的需求描述容易产生理解偏差。

来看一个对比：

抽象需求	具体案例
"我需要一个处理图片的 Skill"	"用户会说：'去掉这张照片的红眼'、'把这张图旋转 90 度'、'调整亮度让脸更清楚'"
"我需要一个查询数据库的 Skill"	"用户会问：'今天有多少用户登录了？'、'上周销售额 top 10 的产品是什么？'"

具体案例能回答三个关键问题：

功能边界 —— Skill 应该支持哪些操作？不支持哪些？
触发模式 —— 用户会用什么样的自然语言来表达需求？
输入输出 —— 用户会提供什么输入？期望得到什么输出？

原文给出的提问模板很实用：

- "What functionality should the [skill-name] skill support?"
- "Can you give some examples of how this skill would be used?"
- "What would a user say that should trigger this skill?"

还有一条重要的交互原则：

To avoid overwhelming users, avoid asking too many questions in a single message.

不要一次性问太多问题。先问最重要的，根据回答再追问。这是对用户认知负荷的尊重。

小结：Step 1 的核心是收集具体案例，而不是抽象需求。具体案例能明确功能边界、触发模式和输入输出，为后续步骤提供清晰的设计依据。

Step 2：规划可复用资源

有了具体案例后，下一步是分析"哪些东西可以复用"。

原文给出的分析框架是：

Considering how to execute on the example from scratch

Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly

翻译一下：先想"如果从零开始做这个任务，我会怎么做"，然后问"哪些部分每次都要重复，可以提前准备好"。

原文给了三个精彩的例子，我逐一分析：

例子 1：PDF 旋转 Skill

用户需求："Help me rotate this PDF"

从零分析：
1. 旋转 PDF 需要用 PyPDF2 或 pdfplumber 库
2. 每次都要写差不多的代码：打开文件 → 旋转页面 → 保存

可复用资源：
→ scripts/rotate_pdf.py（封装好的旋转脚本）

设计启示：当一个操作需要重复编写相似代码时，用 script 封装。

例子 2：前端 Web 应用 Skill

用户需求："Build me a todo app" / "Build me a dashboard"

从零分析：
1. 每次都要写 HTML 骨架、引入 React、配置 Webpack
2. 这些样板代码（boilerplate）每次都一样

可复用资源：
→ assets/hello-world/（包含 HTML/React 项目模板）

设计启示：当任务需要从模板开始时，用 assets 提供起点。

例子 3：BigQuery 查询 Skill

用户需求："How many users have logged in today?"

从零分析：
1. 需要知道用户表叫什么、字段叫什么
2. 每次都要重新探索数据库 schema

可复用资源：
→ references/schema.md（记录表结构和字段含义）

设计启示：当任务需要领域知识时，用 references 提供文档。

原文总结了这个分析过程：

To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.

这一步的输出是一个清单：这个 Skill 需要哪些 scripts、哪些 references、哪些 assets。

小结：Step 2 是从具体案例中提炼可复用资源。分析框架是"从零执行 → 识别重复部分"。三类资源的选择依据：重复代码用 scripts，模板用 assets，领域知识用 references。

Step 3：初始化骨架

到这一步，终于开始动手创建 Skill 了。

原文强调：

When creating a new skill from scratch, always run the init_skill.py script.

为什么要用脚本初始化，而不是手动创建文件夹？原文给出的理由是：

The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.

关键词：efficient（高效）和 reliable（可靠）。脚本能保证：

目录结构符合规范
SKILL.md 的 frontmatter 格式正确
不会遗漏必需的文件

脚本的用法很简洁：

scripts/init_skill.py <skill-name> --path <output-directory> \
  [--resources scripts,references,assets] \
  [--examples]

参数说明：

参数	作用	示例
`<skill-name>`	Skill 名称（小写短横线）	`pdf-editor`
`--path`	输出目录	`skills/public`
`--resources`	需要哪些资源目录（可选）	`scripts,references`
`--examples`	是否生成示例文件（可选）	加上这个参数会生成占位文件

原文给了一个重要的命名规范：

Use lowercase letters, digits, and hyphens only; normalize user-provided titles to hyphen-case (e.g., "Plan Mode" -> plan-mode).

命名风格：kebab-case（短横线分隔）。这和 URL slug、npm 包名的惯例一致。

还有一条长度约束：

When generating names, generate a name under 64 characters.

名字不要超过 64 个字符。这是文件系统兼容性的考量（某些旧系统对路径长度有限制）。

脚本执行后会生成什么？

my-skill/
├── SKILL.md          ← 带 TODO 占位符的模板
└── scripts/          ← 如果指定了 --resources scripts
    └── example.py    ← 如果指定了 --examples

原文特别提醒：

If you used --examples, replace or delete placeholder files.

示例文件只是占位符，要么替换成真实内容，要么删掉。不要把占位符留在最终的 Skill 里。

小结：Step 3 用 init_skill.py 脚本初始化 Skill 骨架。脚本保证了结构规范和格式正确。命名遵循 kebab-case，长度不超过 64 字符。生成的示例文件需要替换或删除。

Step 4：编写内容

这是整个流程中最核心的一步。原文开篇就点明了一个关键视角：

Remember that the skill is being created for another instance of Codex to use.

你在为"另一个 Codex 实例"写文档。这个视角转换很重要 —— 不是写给人看的教程，而是写给 AI Agent 的操作手册。

原文给出的指导原则是：

Include information that would be beneficial and non-obvious to Codex.

关键词：non-obvious（非显而易见的）。

什么是"非显而易见"的信息？

显而易见（不需要写）	非显而易见（必须写）
Python 的基本语法	你公司的 API 调用规范
如何使用 for 循环	数据库表之间的关联关系
Git 的基本命令	代码审查的特定流程

💡 通俗点说：Codex 已经知道"怎么编程"，你要告诉它的是"怎么按你们公司的方式编程"。

先实现资源文件

原文建议的顺序是：

Start with the reusable resources identified above: scripts/, references/, and assets/ files.

先写资源文件，再写 SKILL.md。为什么？因为 SKILL.md 要引用这些资源，先把资源准备好，写 SKILL.md 时才知道该怎么引用。

原文还有一条重要的质量要求：

Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected.

脚本必须实际运行测试。不能写完就打包，要确保能跑通。

但原文也给了一个务实的例外：

If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.

如果有很多相似的脚本，测试代表性样本即可。这是效率和质量的平衡。

编写 SKILL.md

原文给出了一条写作规范：

Writing Guidelines: Always use imperative/infinitive form.

使用祈使句/不定式。

什么意思？看对比：

❌ 错误（陈述句）	✅ 正确（祈使句）
"This skill rotates PDFs"	"Rotate PDFs with this skill"
"You can use this to query data"	"Query data using BigQuery"
"The script will validate..."	"Validate schemas with the script"

祈使句更直接、更像"指令"。这符合 Agent 的使用场景 —— 它在寻找"该做什么"，而不是"这是什么"。

Frontmatter 的写法

原文再次强调了 description 的重要性：

This is the primary triggering mechanism for your skill, and helps Codex understand when to use the skill.

description 是主要的触发机制。写法要点：

包含能力和触发条件 —— "我能做什么" + "什么时候用我"
所有触发信息都写在这里 —— 不要写在 body 里
枚举具体场景 —— 用编号列表提高匹配精度

原文给的示例很好：

description: >
  Comprehensive document creation, editing, and analysis
  with support for tracked changes, comments, formatting
  preservation, and text extraction. Use when Codex needs
  to work with professional documents (.docx files) for:
  (1) Creating new documents,
  (2) Modifying or editing content,
  (3) Working with tracked changes,
  (4) Adding comments, or any other document tasks

分析这个结构：

第一句：能力概述（"Comprehensive document creation..."）
"Use when..."：明确触发条件
编号列表：具体场景枚举

原文还有一条禁令：

Do not include any other fields in YAML frontmatter.

只能有 name 和 description 两个字段。不要自己发明新字段。

Body 的写法

Body 的职责是：

Write instructions for using the skill and its bundled resources.

写使用说明。包括：

如何使用打包的脚本
如何查阅参考文档
工作流的步骤
注意事项和最佳实践

原文推荐参考两个设计模式文档：

场景	参考文档
多步骤流程	`references/workflows.md`
特定输出格式/质量标准	`references/output-patterns.md`

这两个文档包含了经过验证的最佳实践。

小结：Step 4 是内容编写的核心步骤。关键原则：为另一个 Codex 实例写文档，聚焦非显而易见的信息。先实现资源文件并测试，再编写 SKILL.md。Frontmatter 的 description 是触发机制，必须包含所有触发信息。Body 用祈使句写使用说明。

Step 5：打包分发

Skill 开发完成后，需要打包成 .skill 文件分发给用户。

原文说：

The packaging process automatically validates the skill first to ensure it meets all requirements.

打包过程会自动验证。这是一个质量门禁 —— 不符合规范的 Skill 无法打包。

打包脚本的用法：

scripts/package_skill.py <path/to/skill-folder>

# 或指定输出目录
scripts/package_skill.py <path/to/skill-folder> ./dist

打包脚本会做什么？原文列出了验证项（虽然在我读取的片段中被截断了，但从上下文可以推断）：

检查 SKILL.md 是否存在
验证 frontmatter 格式（name 和 description 是否存在）
检查资源文件是否有效
生成 .skill 压缩包

打包后的 .skill 文件就是最终的交付物，用户可以直接导入使用。

小结：Step 5 用 package_skill.py 打包 Skill。打包过程自动验证规范，确保质量。输出的 .skill 文件是可分发的最终产物。

Step 6：迭代优化

原文标题是：

Iterate based on real usage

基于真实使用场景迭代。这一步经常被忽略，但非常重要。

为什么需要迭代？因为：

触发精度问题 —— 用户的实际表达可能和你预想的不一样，导致 Skill 没被触发
信息缺失 —— 使用中发现某些关键信息没写在 Skill 里，Agent 每次都要重新推理
资源冗余 —— 某些打包的资源从来没被用到，占用空间

迭代的数据来源：

用户反馈："为什么这个 Skill 没触发？"
Agent 日志：Skill 被触发后，Agent 的执行路径是什么？
使用频率：哪些资源被频繁访问？哪些从未被用？

迭代的常见优化：

问题	优化方向
Skill 触发率低	扩充 description 的触发关键词
Agent 反复问同样的问题	把答案加到 references 里
某个 reference 文件太大	拆分成多个小文件，按需加载
某些资源从未被用	删除冗余资源

原文虽然没有详细展开这一步，但它的存在提醒了一个重要事实：Skill 不是一次性工程，而是持续演进的产品。

小结：Step 6 是基于真实使用的迭代优化。通过用户反馈、Agent 日志和使用数据，持续改进触发精度、补充缺失信息、删除冗余资源。Skill 是演进的产品，不是一次性工程。

第四部分：设计哲学 💡

读完整个 SKILL.md 规范后，我提炼出三条贯穿始终的设计哲学。

原则一：简洁是公德

原文反复强调一个词：concise（简洁）。

为什么简洁如此重要？因为上下文窗口是公共资源。

原文说：

The context window is a public good. Skills share the context window with everything else Codex needs.

你的 Skill 越冗长，留给其他内容的空间就越少。这不只是你自己的问题，而是影响整个系统的"公德"问题。

简洁体现在哪些地方？

层面	简洁要求	反例（冗余）
Metadata	description ~100 words	写了 500 字的详细说明
SKILL.md body	<5k words	把所有细节都写在 body 里
References	按需加载，只读需要的部分	一次性加载整个 10MB 文档
信息去重	信息只存在一个地方	SKILL.md 和 references 重复写

原文给出的一条实践指南：

Information should live in either SKILL.md or references files, not both.

不要重复。核心流程写在 SKILL.md，详细参考放在 references。

💡 通俗点说：写 Skill 就像写微博 —— 在有限的字数里把事情说清楚，是一种能力。冗长不是详细，而是噪音。

原则二：自由度匹配

这是我从 SKILL.md 的结构设计中读出的隐含原则。

观察这个设计：

必需：SKILL.md（只有这一个）
可选：scripts/、references/、assets/（全部可选）

最简单的 Skill 就是一个 Markdown 文件。复杂度是逐步叠加的。

这个设计体现了什么哲学？自由度匹配任务复杂度。

任务复杂度	Skill 结构	例子
简单提示	只有 SKILL.md	"写代码时遵循 Google Style Guide"
需要脚本	SKILL.md + scripts/	PDF 处理（旋转、提取）
需要知识	SKILL.md + references/	BigQuery 查询（schema 文档）
需要模板	SKILL.md + assets/	前端应用（项目模板）
复杂系统	SKILL.md + 三类资源	企业级工作流

这和软件设计中的"最小惊讶原则"一脉相承 —— 不要强迫用户为简单任务付出复杂代价。

原文没有明说这一点，但设计选择已经说明了一切：

The only required file is SKILL.md.

只有一个必需文件。这是对"简单任务应该简单"的尊重。

原则三：渐进披露

这是整个规范最核心的架构思想。

原文用三级加载系统实现了渐进披露：

Level 1: Metadata        → 始终在上下文（~100 words）
Level 2: SKILL.md body   → 触发时加载（<5k words）
Level 3: Resources       → 按需加载（无上限）

这个设计背后的哲学是：信息应该在需要的时候、以需要的粒度出现。

类比到人类世界：

场景	渐进披露	反例（一次性倾倒）
餐厅点菜	先看菜单（菜名） → 选中后看详情（做法、食材）	服务员一次性背诵所有菜的详细做法
图书馆找书	先看目录（章节名） → 翻到章节看内容	把所有书的内容打印出来让你找
使用 API	先看 API 列表 → 选中后看详细文档	把所有 API 的完整文档塞给你

原文对这个原则的表述是：

Progressive disclosure allows Skills to provide comprehensive information while respecting the context window as a shared resource.

渐进披露让 Skill 既能提供全面信息，又能尊重上下文窗口这个共享资源。

这是一个精妙的平衡 —— 不是"要么全给，要么不给"，而是"按需给，给得刚好"。

小结：三大设计哲学 —— 简洁是公德（上下文窗口是公共资源），自由度匹配（复杂度逐步叠加），渐进披露（信息按需出现）。这三条原则共同构成了 AgentSkills 的架构基石。

FAQ：常见问题

Q1: Skill 和 Prompt 有什么区别？

A: Prompt 是一次性指令，Skill 是可复用的知识包。

维度	Prompt	Skill
生命周期	单次对话	持久存在
触发方式	用户手动输入	自动语义匹配
内容组织	纯文本	结构化（文档+脚本+素材）
复用性	需要每次重新输入	一次创建，多次使用

Prompt 适合临时需求，Skill 适合重复场景。

Q2: 什么时候应该创建一个新 Skill？

A: 当你发现自己在重复做同样的事情时。

判断标准：

✅ 这个任务会重复执行（每周、每月、每个项目）
✅ 任务需要特定的领域知识（公司 API、数据库 schema）
✅ 任务有固定的工作流（多个步骤，顺序固定）
❌ 这是一次性任务
❌ 任务完全通用，不需要私有知识

Q3: Skill 的 description 应该写多长？

A: 原文建议 ~100 words。

关键不是字数，而是覆盖所有触发场景。宁可多写几个场景枚举，也不要模糊概括。

好的 description 结构：

一句话能力概述（20-30 words）
"Use when..." 触发条件（30-40 words）
具体场景枚举（30-40 words）

Q4: scripts 和 references 怎么选？

A: 看是否需要读入上下文。

场景	选择	原因
固定逻辑，不需要理解	scripts	可以直接执行，零 token
需要 Agent 理解后决策	references	必须读入上下文
复杂计算（如数据处理）	scripts	确定性强，不需要 LLM 推理
业务规则（如审批流程）	references	Agent 需要理解规则后判断

经验法则：能用 scripts 就用 scripts，省 token。

Q5: 一个 Skill 可以有多大？

A: 没有硬性上限，但要遵循渐进披露。

组件	建议大小	超过时的处理
Metadata	~100 words	无法压缩，必须精简
SKILL.md body	<5k words	拆分到 references
单个 reference	<10k words	提供 grep 搜索模式
Scripts	无上限	可以不加载就执行

关键原则：不是"能塞多少"，而是"需要多少"。

Q6: 如何测试 Skill 的触发精度？

A: 用真实用户表达测试。

测试方法：

收集 10-20 个用户可能的真实表达
逐个测试是否触发了正确的 Skill
未触发的表达 → 补充到 description
误触发的表达 → 调整 description 或其他 Skill

不要只用自己想象的表达测试，要用真实用户的语言。

结语

回到开头的问题：如何让通用 Agent 变成领域专家？

AgentSkills 给出的答案是：通过模块化的知识包，将程序性知识注入 Agent。

这篇文章解析了 AgentSkills 规范的四个层面：

动机层（第一部分）：通用 Agent 缺乏私有程序性知识，Skills 是岗前培训手册
结构层（第二部分）：SKILL.md + 三类资源，三级渐进披露管理上下文窗口
流程层（第三部分）：6 步创建法，从具体案例到打包分发
哲学层（第四部分）：简洁是公德、自由度匹配、渐进披露

如果只记住一句话，那就是：

Skills 不是给 Agent 增加功能，而是给 Agent 注入你的工作方式。

通用大模型已经很强大，它缺的不是"能力"，而是"你的上下文" —— 你的 API 规范、你的数据库结构、你的业务流程、你的代码模板。

AgentSkills 提供了一套优雅的机制，让这些私有知识能够：

模块化打包（一个文件夹就是一个 Skill）
按需加载（三级渐进披露）
自动触发（语义匹配，不需要手动调用）
持续演进（基于真实使用迭代）

这是 AI Agent 从"通用工具"走向"专业助手"的关键一步。

参考资源

AgentSkills 官方规范 - 完整的 SKILL.md 文档
Codex AgentSkills 仓库 - 官方 Skills 示例
渐进披露设计模式 - Nielsen Norman Group 的经典文章

写于: 2026-03-25 字数: ~8000 字 阅读时长: 20-25 分钟