AI Agent Skill 系统：从概念定义到自定义开发实战

大模型很聪明，但你有没有想过——为什么 ChatGPT 只能聊天，而一些 AI Agent 却能操作工具、调用 API、执行脚本、完成真实任务？

答案就在 Skill 这个概念里。

今天这篇文章，我们从零开始拆解 AI Agent 的 Skill 系统：它是什么、由哪些部分组成、有什么标准、以及如何开发你自己的 Skill。

一、Skill 是什么？

Skill 是 Agent 的可执行能力单元。

它把"Agent 能做什么"从模糊的模型能力，转化为确定性的工作流。没有 Skill，Agent 只能聊天；有了 Skill，Agent 能操作工具、调用 API、执行脚本、完成实际任务。

打个比方：

• 大模型 = 大脑，负责理解和推理
• Skill = 手的操作手册，负责具体执行

为什么需要 Skill？

1. 模型不知道怎么用你的工具

每个环境有独特的 API、CLI、配置，模型不可能预知所有细节。

2. 模型不知道何时该用

触发条件需要明确描述，否则 Agent 会"想当然"地选错工具。

3. 模型不知道边界在哪

安全约束、错误处理需要硬编码，不能靠模型"自觉"。

4. 能力可复用

一次写好，多个 Agent 共享，不用每次重新教。

二、Skill 由哪些部分组成？

以业界最流行的 AgentSkills 规范为例，一个完整的 Skill 目录结构如下：

my-skill/
  SKILL.md          # 核心：元数据 + 指令（必须）
  scripts/          # 确定性的辅助脚本（可选）
  references/       # 延迟加载的参考文档（可选）
  assets/           # 模板、媒体资源（可选）
  agents/           # UI 元数据（可选）

2.1 SKILL.md — 核心文件（必须有）

这是 Skill 的灵魂，包含两个关键部分：

Frontmatter（元数据）：

---
name: pdf-tools
description: "Inspect, split, merge, OCR, redact, or convert PDFs with local CLI tools."
metadata: {"openclaw": {"requires": {"bins": ["qpdf"]}, "primaryEnv": "PDF_API_KEY"}}
---

• name：唯一标识符，小写字母+数字+连字符
• description：一句话描述，告诉 Agent 何时触发这个 Skill
• metadata：依赖条件、安装说明、平台限制

Markdown Body（指令）：

# PDF Tools

Use for PDF manipulation. Prefer deterministic scripts for page edits.

## Workflow

1. Inspect file/page count.
2. Choose exact operation.
3. Write output beside input unless user asked otherwise.
4. Render/verify changed pages.

## Safety

- Never overwrite the original file without explicit confirmation.

这是 Agent 执行任务时的操作手册。

2.2 scripts/ — 确定性脚本

放 Shell、Python 等脚本，Skill 指令中引用执行。

核心原则：确定性操作优先用脚本，而不是让模型"自由发挥"。

为什么？因为脚本是确定性的——同样的输入，永远得到同样的输出。而让模型自由发挥，每次结果可能不同，出错率更高。

2.3 references/ — 参考文档

长文档、API 参考、使用手册。只在需要时加载，避免消耗宝贵的上下文窗口。

这是一个很精妙的设计：把 Skill 的"触发信息"和"参考信息"分开。触发信息永远加载（轻量），参考信息按需加载（重量）。

2.4 assets/ — 资源文件

模板、配置样例、图片等输出资源。Skill 执行时可以引用这些模板来生成结果。

三、Skill 的标准是什么？

不是随便写个文档就能叫 Skill。一个合格的 Skill 需要满足以下五个标准：

标准 1：触发明确

description 必须让 Agent 能准确判断何时激活这个 Skill。

❌ description: "A tool for things"        # 太模糊，Agent 不知道何时用
✅ description: "Inspect, split, merge, OCR PDFs with local CLI tools"  # 明确具体

标准 2：依赖声明

Skill 必须声明它需要什么才能运行：

metadata: {
  "openclaw": {
    "requires": {
      "bins": ["ffmpeg"],           # 需要 PATH 上有 ffmpeg
      "env": ["GEMINI_API_KEY"],    # 需要环境变量
      "config": ["browser.enabled"] # 需要配置项开启
    },
    "os": ["darwin", "linux"]       # 平台限制
  }
}

不满足条件 → Skill 自动隐藏，不会出现在 Agent 的可用列表中。这避免了 Agent 试图使用一个无法运行的 Skill。

标准 3：指令精简

Skill 的指令应该只写模型不知道的：

• ✅ 命令语法、认证陷阱、安全规则、验证步骤
• ❌ 基础概念解释、通用编程知识

模型已经会写 Python，你不需要教它什么是函数。但你需要告诉它：调用这个 API 时必须带 Authorization header，频率限制是每分钟 30 次。

标准 4：安全边界

• 不允许任意命令注入
• 危险操作需要确认
• 私密信息不进 prompt
• 敏感操作（删除、覆盖）需要二次确认

标准 5：可验证

• 提供 skills list 验证加载
• 提供端到端测试方式
• 每次 Skill 变更后都能确认生效

四、Skill 的加载机制

了解 Skill 的加载机制，有助于你设计出更好的 Skill。

4.1 加载优先级

Skill 从多个位置加载，高优先级覆盖低优先级：

同一个 Skill 名字出现在多个位置时，优先级高的生效。

4.2 门控过滤

Skill 不是加载了就能用，还需要通过"门控"检查：

1. 平台检查：os 字段匹配当前操作系统
2. 二进制检查：bins 字段中的命令在 PATH 中存在
3. 环境变量检查：env 字段中的变量已设置
4. 配置检查：config 字段中的配置项已开启

全部通过 → Skill 可用；任一不通过 → 自动隐藏。

4.3 快照与刷新

Skill 在会话启动时快照，后续复用。变更需要新会话或手动刷新才能生效。

这个设计保证了会话内 Skill 列表的稳定性，避免中途变更导致的不一致。

五、如何开发你自己的 Skill？

接下来，我们通过一个完整的实战案例，手把手教你开发一个 Skill。

Step 1：创建目录

mkdir -p ~/.openclaw/workspace/skills/stock-query

Step 2：编写 SKILL.md

---
name: stock-query
description: "Query real-time stock prices and market data from East Money API."
metadata: {"openclaw": {"requires": {"env": ["EM_API_KEY"]}, "primaryEnv": "EM_API_KEY"}}
---

# Stock Query

Use when the user asks about stock prices, market trends, or financial data.

## Workflow

1. Parse the user's query for stock codes or company names.
2. Run `{baseDir}/scripts/query.py` with the stock code.
3. Format the result as a readable summary.
4. If the stock code is ambiguous, ask the user to clarify.

## Safety

- Only query publicly available market data.
- Never execute trades.
- Rate limit: max 30 requests per minute.

注意 {baseDir}——这是 Skill 目录的路径占位符，运行时自动替换为实际路径。

Step 3：添加脚本

#!/usr/bin/env python3
"""Query stock data from East Money API"""
import os
import sys
import json
import requests

API_KEY = os.environ.get("EM_API_KEY")
if not API_KEY:
    print("Error: EM_API_KEY not set")
    sys.exit(1)

code = sys.argv[1]
resp = requests.get(
    f"https://api.eastmoney.com/stock",
    params={"q": code, "key": API_KEY},
    timeout=10
)
print(json.dumps(resp.json(), ensure_ascii=False, indent=2))

Step 4：配置环境变量

在 openclaw.json 中：

{
  "skills": {
    "entries": {
      "stock-query": {
        "enabled": true,
        "env": {
          "EM_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Step 5：加载和测试

# 新建会话让 Skill 生效
/new

# 验证 Skill 已加载
openclaw skills list

# 测试触发——直接在对话中问：
# "查一下贵州茅台的股价"

Step 6：发布到 Skill 市场（可选）

clawhub login
clawhub publish stock-query

六、Skill 设计的 5 个实战原则

七、Skill vs Plugin vs Tool：三者关系

很多人分不清 Skill、Plugin、Tool 的区别，这里厘清一下：

• Tool 是能力的基础设施
• Skill 是使用能力的知识
• Plugin 是分发能力的载体

没有 Skill 的 Tool 就像没有说明书的工具——Agent 知道有这个工具，但不知道什么时候用、怎么用、注意什么。

八、总结

Skill 是把 AI 从"会说话"变成"会干活"的关键桥梁。

它解决的核心问题是：让 Agent 知道什么时候出手、怎么出手、边界在哪。

一个设计良好的 Skill 系统，应该做到：

1. 触发精准 — Agent 不犹豫，该出手时出手
2. 执行可靠 — 确定性操作用脚本，不确定性交给模型
3. 安全可控 — 依赖显式声明，危险操作有约束
4. 上下文高效 — 轻量触发信息常驻，重量参考按需加载
5. 可复可扩展 — 一次写好，多处共享，市场分发

当你在构建自己的 AI Agent 时，请记住：Skill 不是可选项，而是 Agent 从"聊天机器人"升级为"生产力工具"的必经之路。

觉得有用？点赞收藏，下期我们聊聊如何设计一个生产级的 Skill 系统。