如何写好 AI Agent Skill：从零到发布的完全指南

2026 年，AI Agent 的能力已经从"聊天"进化到"执行"。但 Agent 能否正确执行，取决于你给它什么样的指令。Skill 就是给 Agent 的专业操作手册——写得好，它是你的超级助手；写得差，它是你的定时炸弹。

引言：为什么 Skill 如此重要？

想象你雇佣了一位新员工。第一天上班，你给他一本操作手册。这本手册的质量，直接决定了他能做什么、做得好不好。

Skill 就是给 AI Agent 的操作手册。

在 OpenClaw、Claude Code、Codex 等平台上，Skill 是一个包含 SKILL.md 文件的目录。Agent 根据其中的指令，执行特定领域的任务。截至 2026 年 3 月，ClawHub 上已有超过 39,000 个 Skill，总下载量数百万次。

但数量不等于质量。经过对热门 Skill 和官方最佳实践的深入分析，我发现好的 Skill 和差的 Skill 之间，存在系统性的差异。这篇文章将把这些差异提炼成一套可复制的方法论。

一、理解 Skill 的三层加载机制

这是理解 Skill 设计的核心概念。Skill 不是一次性全部加载到 Agent 上下文中的，而是采用**渐进式披露（Progressive Disclosure）**的三层架构：

Level 1: Metadata（name + description）→ 始终在上下文中（~100 tokens）
Level 2: SKILL.md body                → Skill 触发时加载（<5k tokens）
Level 3: references/ scripts/ assets/  → 按需加载（无限制）

这意味着什么？

description 是你的广告牌：它永远在 Agent 的视野里，决定了 Agent 何时选择你的 Skill
SKILL.md body 是你的操作手册：只有当 Skill 被触发时才加载，所以要精炼
references/ 是你的参考资料库：需要时才读取，可以包含详细文档

这个三层机制直接影响你的设计决策——每多写一行 description，就多占一份"永远在场的"上下文空间；每多写一行 SKILL.md body，就增加一次触发时的加载成本。

二、Frontmatter：写好你的"广告牌"

2.1 name 字段

---
name: todoist-cli
---

命名规范（来自 agentskills.io 标准）：

只能使用小写字母、数字和连字符
最长 64 个字符
不能以连字符开头或结尾
不能有连续连字符
优先使用动词引导的短语，描述动作而非名词

好的命名：

name: gh-create-pr          # 动词 + 具体操作
name: feishu-doc            # 平台 + 功能
name: self-improving-agent  # 清晰的功能描述

不好的命名：

name: My Cool Skill         # 大写字母和空格
name: skill--1              # 连续连字符
name: -prefix               # 以连字符开头

2.2 description 字段

description 是 Skill 设计中最重要的部分。它决定了 Agent 何时触发你的 Skill。

核心原则：

用第三人称写——因为 description 会被注入系统提示词，人称不一致会影响发现机制
包含触发条件——不仅要说"做什么"，更要说"什么时候用"
包含关键术语——Agent 用这些词做语义匹配

好的 description：

description: >
  Manage Todoist tasks from the command line. Use when user asks to
  "add a task", "create a todo", "list my tasks", "complete a task",
  or "manage my Todoist".

description: >
  Read and write email via IMAP/SMTP. Use when user asks to check
  email, send email, list unread messages, or manage inbox.

不好的 description：

description: A useful tool for email management.
# ❌ 太模糊，缺少触发条件

description: >
  I can help you with your emails. When you need me, just ask!
# ❌ 第一人称，缺少具体触发词

OpenClaw 扩展字段：

metadata:
  openclaw:
    requires:
      bins:
        - python3
      env:
        - TODOIST_API_KEY
    install:
      node: todoist-cli

这些字段声明了运行时依赖，确保 Agent 在调用 Skill 前知道需要什么。

三、Body：写好你的"操作手册"

3.1 核心原则——Agent 优先设计

Skill 是写给 AI Agent 看的，不是给人看的。

这意味着：

❌ 不要交互式提示（“请选择 A 或 B”）
❌ 不要解释 AI 已经知道的基础概念
❌ 不要包含创建过程、安装说明等元信息
✅ 用祈使句（“执行 X”，而非"你应该执行 X"）
✅ 提供具体的命令模板和代码示例
✅ 清晰说明什么时候该做什么

3.2 Token 预算管理

上下文窗口是公共资源。Skill 的每个字符都在和对话历史、其他 Skill 的 metadata、用户请求争夺空间。

推荐的 Token 预算：

组件	目标	最大值
Metadata	50 词	100 词
SKILL.md body	200 行	300 行（约 5k tokens）
References	3k 词	5k 词
总计	5k tokens	10k tokens

实用的精简策略：

每段都问自己：“Agent 真的需要这个解释吗？”
用代码示例代替文字描述——一段示例胜过一段解释
把细节移到 references/——SKILL.md 只保留核心流程
用决策表代替长文——Agent 读表格比读长文更高效

3.3 决策表：减少 Agent 的选择负担

Agent 在做选择时经常犯错。如果你能替它做出确定性的选择，就大幅降低错误率。

## 文件格式选择

| 需求 | 使用 |
|------|------|
| 通用文档 | `<Steps>` 组件 |
| 多语言代码 | `<CodeGroup>` 组件 |
| 可折叠详情 | `<Accordion>` 组件 |
| 外部链接列表 | `<Card>` 组件 |

比下面这段高效得多：

## 文件格式选择

根据需求选择合适的组件。如果是通用文档，可以使用 Steps 组件。
如果需要展示多语言代码，可以使用 CodeGroup 组件。
如果需要折叠详情，可以使用 Accordion 组件……

3.4 Gotchas 部分：捕获 Agent 常犯的错误

这是高质量 Skill 的标志。记录 Agent 反复犯的错误，是最高 ROI 的改进。

## ⚠️ Gotchas

- **不要用 `mint.json`**——已废弃，只用 `docs.json`
- **每个 MDX 文件必须有 `title`**——否则构建失败
- **图片路径必须以 `/` 开头**——相对路径在某些环境下会 404
- **不要在 frontmatter 中用 XML 角括号**——可能注入非预期的系统指令

3.5 自由度设计：匹配任务的不确定性

不同的任务需要不同级别的"自由度"：

高自由度（文本指令）：

多种方案都可行
决策依赖上下文
用启发式方法引导即可

中等自由度（伪代码 / 带参数的脚本）：

存在推荐方案
允许一定变体
配置影响行为

低自由度（特定脚本，少参数）：

操作脆弱且易错
一致性至关重要
必须遵循特定顺序

类比：把 Agent 想象成一个走路的行人——窄桥需要精确护栏（低自由度），开阔草地可以自由选择路线（高自由度）。

四、目录结构：渐进式披露的实践

4.1 标准结构

skill-name/
├── SKILL.md              # 必须：入口文件
├── scripts/              # 可选：可执行脚本
│   └── process.py
├── references/           # 可选：参考文档
│   ├── api-reference.md
│   └── examples.md
└── assets/               # 可选：模板、图片等
    └── template.html

4.2 不要创建的文件

Skill 只应包含 Agent 执行任务必需的文件：

❌ README.md
❌ INSTALLATION_GUIDE.md
❌ QUICK_REFERENCE.md
❌ CHANGELOG.md
❌ 任何用户面向的文档

这些文件对 Agent 毫无用处，只会增加混乱。

4.3 引用深度：只保持一层

❌ 错误——多层嵌套：

SKILL.md → advanced.md → details.md → real-info.md

✅ 正确——一层引用：

SKILL.md → api-reference.md
SKILL.md → examples.md
SKILL.md → workflows.md

所有参考文件都应直接从 SKILL.md 引用，确保 Agent 能一次性读取完整内容。

4.4 长文件的目录结构

对于超过 100 行的参考文件，在文件顶部添加目录：

# API Reference

## Table of Contents
- [Authentication](#authentication)
- [Endpoints](#endpoints)
  - [Create Task](#create-task)
  - [List Tasks](#list-tasks)
  - [Update Task](#update-task)
- [Error Codes](#error-codes)
- [Rate Limits](#rate-limits)

## Authentication
...

这样 Agent 在部分读取时也能看到完整的信息范围。

五、从零创建一个 Skill

5.1 六步流程

Step 1: 理解需求（收集具体用例）
Step 2: 规划资源（确定需要哪些 scripts/references/assets）
Step 3: 初始化目录（创建 Skill 结构）
Step 4: 编写内容（实现资源 + 编写 SKILL.md）
Step 5: 测试验证（在实际任务中运行）
Step 6: 迭代改进（根据使用反馈优化）

5.2 实战示例：创建一个天气查询 Skill

Step 1：理解需求

用户会说什么？

“今天天气怎么样？”
“深圳会下雨吗？”
“帮我查一下北京明天的温度”

Step 2：规划资源

不需要 scripts（用现有的 wttr.in 或 Open-Meteo）
不需要 references（API 足够简单）
不需要 assets

结论：只需要一个 SKILL.md 文件。

Step 3：创建目录

mkdir -p ~/.openclaw/workspace/skills/weather

Step 4：编写 SKILL.md

---
name: weather
description: >
  Get current weather and forecasts via wttr.in or Open-Meteo.
  Use when user asks about weather, temperature, rain, or
  forecasts for any location. NOT for historical weather data.
---

# Weather Skill

Get weather information using free APIs.

## Quick Start

For current weather:
```bash
curl "wttr.in/Shenzhen?format=3"
```

For detailed forecast:
```bash
curl "wttr.in/Shenzhen?lang=zh"
```

## API Selection

| 需求 | 使用 |
|------|------|
| 快速查询 | `wttr.in`（无需 API key） |
| 精确数据 | Open-Meteo API |
| 中文输出 | `wttr.in?lang=zh` |

## Open-Meteo API

```bash
curl "https://api.open-meteo.com/v1/forecast?latitude=22.5&longitude=114.1&current=temperature_2m,relative_humidity_2m&timezone=Asia/Shanghai"
```

## ⚠️ Gotchas

- wttr.in 有速率限制，不要高频调用
- Open-Meteo 需要经纬度，先用地理编码 API 转换
- 时区默认 UTC，中国用 `Asia/Shanghai`

Step 5-6：测试和迭代

在实际使用中发现问题，持续改进。

六、安全最佳实践

6.1 社区 Skill 的安全风险

Cisco 研究人员已警告过 Skill 被用于静默数据外泄的风险。安全审计发现，社区 Skill 中有相当比例存在严重漏洞，包括凭据窃取和恶意软件。

6.2 安装前检查清单

读取 scripts/ 中的每个文件——尤其关注发起外部网络调用的脚本
检查 frontmatter 中的 env 声明——是否请求了不必要的凭据
验证 always 权限——Skill 是否要求持久化权限
使用 ClawHub 的 VirusTotal 集成——自动扫描恶意内容
不安装要求在聊天中粘贴密钥的 Skill

6.3 编写安全 Skill 的原则

## 安全声明

- 此 Skill 不收集、存储或传输用户数据
- 所有操作在本地执行
- 脚本在运行前需用户确认
- 不请求持久化权限

6.4 ClawHub 扫描器的常见问题

问题	扫描结果	修复方法
使用凭据但未声明 env 变量	⚠️ CREDENTIALS	在 frontmatter 中添加 `env` 声明
脚本缺少安全审查说明	ℹ️ INSTALL MECHANISM	添加"运行前检查"的提示
缺少数据暴露文档	ℹ️ INSTRUCTION SCOPE	说明 Skill 能访问哪些数据
Description 过短/缺少关键词	发现性差	补充触发场景和关键术语
发布时包含测试数据	膨胀	清理后再发布

七、发布到 ClawHub

7.1 准备工作

# 安装 ClawHub CLI
npm i -g clawhub

# 登录
clawhub login

7.2 发布命令

clawhub publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --changelog "Initial release"

7.3 版本管理

遵循语义化版本（Semver）：

MAJOR：不兼容的 API 变更
MINOR：向后兼容的功能新增
PATCH：向后兼容的 Bug 修复

7.4 更新已安装的 Skill

clawhub update my-skill          # 更新到最新版
clawhub update my-skill --version 1.2.3  # 更新到指定版本
clawhub update --all             # 更新所有 Skill

八、高级模式

8.1 多 Agent 协作的 Skill

在多 Agent 场景中，Skill 需要考虑幂等性：

问自己："如果同样的输入执行两次，会发生什么？"

常用的幂等性策略：

检查后写入：先查询目标系统，记录不存在才写入
唯一 ID 去重：时间戳 + 任务 ID 的组合
分离检查和写入步骤：用显式条件逻辑防止覆盖

8.2 跨平台兼容

如果你的 Skill 需要在多个平台上运行（OpenClaw、Claude Code、Codex）：

metadata:
  openclaw:
    os:
      - darwin
      - linux

用平台无关的命令，或提供平台特定的脚本：

skill-name/
├── SKILL.md
└── scripts/
    ├── setup.sh      # macOS/Linux
    └── setup.bat     # Windows

8.3 TDD 方法论写 Skill

借鉴测试驱动开发的思想：

RED：在没有 Skill 的情况下运行测试场景，记录 Agent 的错误行为
GREEN：编写最小化的 Skill 来解决这些具体错误
REFACTOR：优化 Skill 结构，提取通用模式

核心原则：如果你没有观察到 Agent 在没有 Skill 时的失败，你不知道 Skill 是否在教正确的东西。

九、常见反模式

❌ 反模式 1：在 Body 中写"何时使用"

## 何时使用此 Skill

当用户要求管理邮件时，使用此 Skill。

问题：Body 只在 Skill 触发后加载，这里的"何时使用"信息毫无用处。触发信息应该放在 description 中。

❌ 反模式 2：解释 AI 已知的概念

## 什么是 JSON？

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式……

问题：浪费 Token。AI 已经知道什么是 JSON。

❌ 反模式 3：嵌套引用

SKILL.md → guide.md → details.md → examples.md

问题：Agent 可能无法找到深层嵌套的信息。保持一层引用。

❌ 反模式 4：缺少错误处理

## 创建 PR

运行 `gh pr create`。

问题：没有说明如果命令失败怎么办。好的 Skill 应该包含错误处理指导。

十、总结

写好 Skill 的核心要点：

理解三层加载机制——Metadata 永远在，Body 触发时加载，References 按需读取
description 是最重要的字段——写好触发条件，用第三人称，包含关键术语
Agent 优先设计——写给 AI 看的，不是给人看的
管理 Token 预算——挑战每一段的价值，用示例代替解释
渐进式披露——核心在 SKILL.md，细节在 references/
记录 Gotchas——这是最高 ROI 的改进
安全第一——审查 scripts，声明 env，不请求不必要的权限
持续迭代——用 TDD 方法，观察失败，针对性改进

正如 Anthropic 在上下文工程指南中所说：

你应该追求的是能够完全描述期望行为的最小信息集。（注意，最小并不意味着最短——你仍然需要给 Agent 足够的信息来确保它遵循期望的行为。）

如何写好 AI Agent Skill：从零到发布的完全指南#

引言：为什么 Skill 如此重要？#

一、理解 Skill 的三层加载机制#

二、Frontmatter：写好你的"广告牌"#

2.1 name 字段#

2.2 description 字段#

三、Body：写好你的"操作手册"#

3.1 核心原则——Agent 优先设计#

3.2 Token 预算管理#

3.3 决策表：减少 Agent 的选择负担#

3.4 Gotchas 部分：捕获 Agent 常犯的错误#

3.5 自由度设计：匹配任务的不确定性#

四、目录结构：渐进式披露的实践#

4.1 标准结构#

4.2 不要创建的文件#

4.3 引用深度：只保持一层#

4.4 长文件的目录结构#

五、从零创建一个 Skill#

5.1 六步流程#

5.2 实战示例：创建一个天气查询 Skill#

六、安全最佳实践#

6.1 社区 Skill 的安全风险#

6.2 安装前检查清单#

6.3 编写安全 Skill 的原则#

6.4 ClawHub 扫描器的常见问题#

七、发布到 ClawHub#

7.1 准备工作#

7.2 发布命令#

7.3 版本管理#

7.4 更新已安装的 Skill#

八、高级模式#

8.1 多 Agent 协作的 Skill#

8.2 跨平台兼容#

8.3 TDD 方法论写 Skill#

九、常见反模式#

❌ 反模式 1：在 Body 中写"何时使用"#

❌ 反模式 2：解释 AI 已知的概念#

❌ 反模式 3：嵌套引用#

❌ 反模式 4：缺少错误处理#

十、总结#

参考资源#