什么是 Agent Skills？给你的 AI 装上"超能力"

你的 AI 助手什么都会一点，但什么都不精。Skills 改变了这件事。

你有没有想过，为什么有的人用 ChatGPT 写代码飞快，有的人用 AI 做数据分析得心应手，而你用同样的模型总觉得差点意思？

差的不是模型。差的是工具链。

OpenClaw 里的 Agent Skills，就是给 AI 助手装工具的标准方式。不是插件，不是 Prompt 工程的黑魔法，而是一套标准化的"能力扩展包"——每个 Skill 是一个文件夹，里面装着让 AI 学会做某件事的所有信息。

这篇文章会从底层原理讲到实际操作，带你彻底搞懂 Agent Skills 是什么、怎么用、怎么做。

一、先看一个真实的 Skill 长什么样

不讲概念，直接上代码。下面是一个真实的 Skill 文件夹结构：

weather/
└── SKILL.md          ← 唯一的文件，也是核心

一个 Skill 就是一个文件夹，里面放一个 SKILL.md。打开它：

---
name: weather
description: Get current weather and forecasts (no API key required).
metadata: {"openclaw":{"emoji":"🌤️","requires":{"bins":["curl"]}}}
---

# Weather

Two free services, no API keys needed.

## wttr.in (primary)

Quick one-liner:
curl -s "wttr.in/London?format=3"
# Output: London: ⛅️ +8°C

## Forecast (7-day)

curl -s "wttr.in/London?format=v2"

这个 Skill 教 AI 一件事：查天气。

它告诉 AI 三件事：

  1. 用 curl 调用 wttr.in 这个免费天气 API
  2. 怎么格式化输出（?format=3 是简短格式，?format=v2 是详细格式）
  3. 前提条件：系统里必须有 curl 这个命令行工具

就这么简单。一个 SKILL.md 文件，就是一个 Skill 的全部。

二、Skill 的本质：给 AI 看的"使用说明书"

传统软件插件（Plugin）是给程序用的——你写代码调用接口，程序执行。

Agent Skill 是给语言模型用的——你写 Markdown 文档，模型读了之后"学会"了怎么操作。

这是一个根本性的区别。

Skill 本质上是一个结构化的 Prompt，它被注入到 AI 的系统提示（System Prompt）里，让模型知道：

  • 这个工具能做什么（description 字段）
  • 什么时候该用它（可选的 read_when 触发条件）
  • 具体怎么操作（SKILL.md 正文里的指令和示例）
  • 需要什么前置条件（requires.bins、requires.env）

SKILL.md 的完整结构

每个 SKILL.md 包含两部分：YAML Frontmatter（头部元数据）和 Markdown 正文（操作指南）。

Frontmatter 示例：

---
name: weather                          # Skill 名称（必填）
description: Get current weather...    # 一句话描述（必填）
homepage: https://wttr.in/:help        # 可选：项目主页
metadata: {"openclaw":{...}}           # 可选：运行时元数据
---

正文部分： 就是普通的 Markdown，包含命令示例、参数说明、注意事项等。AI 会根据这些内容决定怎么使用对应工具。

metadata.openclaw 核心字段详解

metadata 是一个单行 JSON 对象（不是多行 YAML），里面 openclaw 字段控制 Skill 的加载和运行行为：

字段 类型 说明
emoji string 在 UI 中显示的 emoji 图标
os array 限制运行平台，如 ["darwin", "linux"]
requires.bins array 必须存在的命令行工具，如 ["curl", "jq"]
requires.anyBins array 至少需要其中一个，如 ["ffmpeg", "avconv"]
requires.env array 必须存在的环境变量，如 ["OPENAI_API_KEY"]
requires.config array 必须为真的配置路径，如 ["browser.enabled"]
primaryEnv string 主要 API Key 变量名，配合 apiKey 配置使用
install array 自动安装器配置（brew/npm/go/uv/下载）
always boolean 设为 true 则跳过所有加载过滤，始终加载

加载过滤（Gating） 是关键机制。OpenClaw 在启动时检查这些条件——如果系统里没有 curl，需要 curl 的 Skill 就不会被加载，AI 根本看不到它，自然也不会尝试调用。

可选的 Frontmatter 字段

除了必填的 name 和 description，还有这些可选字段：

字段 默认值 说明
user-invocable true 用户可以通过 /命令 手动触发
disable-model-invocation false 设为 true 则 AI 不会自动调用，只允许用户手动触发
command-dispatch - 设为 tool 则跳过模型，直接路由到工具
command-tool - 配合 command-dispatch，指定目标工具名
command-arg-mode raw 工具调用时的参数传递模式

三、Skill 从哪里来？三层加载机制

OpenClaw 从三个地方加载 Skill，按优先级从高到低：

第一层（最高优先）：工作空间 Skills
路径：~/.openclaw/workspace/skills/

你自己的、项目专用的 Skill 放在这里。同名会覆盖其他两层。

第二层：本地/托管 Skills
路径：~/.openclaw/skills/

所有 Agent 共享的 Skill 放在这里。适合多 Agent 场景下需要共用的工具。

第三层（最低优先）：内置 Skills
路径：随 npm 包安装的 skills/ 目录

OpenClaw 自带的 51 个 Skill，覆盖常见场景。

同名覆盖规则： 工作空间 > 本地 > 内置。比如你觉得内置的 github Skill 不够用，可以在 workspace/skills/github/SKILL.md 里写自己的版本，它会自动覆盖内置的。

还可以通过配置额外的加载目录：

{
  skills: {
    load: {
      extraDirs: ["/path/to/shared/skills"]  // 最低优先级
    }
  }
}

当前版本实际安装情况

以 OpenClaw 2026.3.24 为例，内置 51 个 Skills：

类别 Skills
通讯 discord, slack, imsg, bluebubbles, wacli
开发 github, gh-issues, coding-agent, mcporter
笔记 apple-notes, bear-notes, notion, obsidian
媒体 openai-whisper, openai-whisper-api, sag, video-frames, gifgrep
工具 weather, summarize, tmux, xurl, canvas
平台 1password, spotify-player, sonoscli, trello, things-mac
系统 healthcheck, node-connect, session-logs, skill-creator

用户按需安装的工作空间 Skills（14 个）：

Skill 用途
agent-browser 浏览器自动化（Rust + Node.js）
article-writing 文章写作（风格模仿）
github GitHub 操作（gh CLI）
memory-qdrant Qdrant 向量语义记忆
memory-setup-openclaw 记忆系统配置引导
self-improving-agent 自我学习和纠错
summarize 网页/PDF/视频摘要
tavily-search AI 优化搜索
vector-memory 自建向量记忆
weather 天气查询
find-skills Skill 发现
obsidian Obsidian 笔记管理
skillhub-preference Skill 安装偏好

四、怎么安装 Skill？

方法一：从 ClawHub 安装（推荐）

ClawHub 是 OpenClaw 的官方 Skill 注册中心，类似 npm 之于 Node.js。

# 搜索需要的 Skill
openclaw skills search "calendar"

# 安装到当前工作空间
openclaw skills install <skill-slug>

# 安装指定版本
openclaw skills install <skill-slug> --version 1.2.0

# 更新所有已安装的
openclaw skills update --all

# 查看本地已有的 Skills
openclaw skills list

# 查看哪些满足运行条件
openclaw skills list --eligible

# 查看某个 Skill 的详细信息
openclaw skills info <name>

# 检查运行条件
openclaw skills check

ClawHub 使用 semver 版本管理，安装后记录在 .clawhub/lock.json 里（类似 package-lock.json），支持回滚和版本锁定。

方法二：手动安装

直接把 Skill 文件夹放到对应目录即可：

# 放到工作空间（仅当前 Agent 可用）
mkdir -p ~/.openclaw/workspace/skills/my-skill
cat > ~/.openclaw/workspace/skills/my-skill/SKILL.md << 'SKILLEOF'
---
name: my-skill
description: A custom skill for doing X
---
# My Skill
Instructions here...
SKILLEOF

# 或放到本地目录（所有 Agent 共享）
mkdir -p ~/.openclaw/skills/my-skill
# 同样的操作

方法三：从 GitHub 克隆

git clone https://github.com/user/skill-repo ~/.openclaw/workspace/skills/my-skill

重要提示： Skill 的变更在下一个会话生效。当前会话已经加载了 Skill 列表，不会自动刷新。

五、配置 Skill

在 ~/.openclaw/openclaw.json 里可以精细控制每个 Skill：

{
  skills: {
    entries: {
      // 启用/禁用 Skill
      "github": { enabled: true },
      "sag": { enabled: false },

      // 提供 API Key（SecretRef 方式）
      "image-lab": {
        enabled: true,
        apiKey: {
          source: "env",
          provider: "default",
          id: "GEMINI_API_KEY"
        }
      },

      // 注入环境变量
      "my-custom-skill": {
        enabled: true,
        env: {
          API_ENDPOINT: "https://api.example.com",
          MODEL_NAME: "gpt-4"
        },
        config: {
          maxRetries: 3,
          timeout: 30
        }
      }
    },

    // 白名单模式：仅允许特定内置 Skills
    allowBundled: ["github", "weather", "discord"]
  }
}

环境变量注入机制： 当 Agent 运行开始时，OpenClaw 把 Skill 配置的 env 和 apiKey 注入到 process.env，运行结束后立即恢复原始环境。作用域是单次 Agent 运行，不是全局。

配置中的 apiKey 支持两种格式：

  • 直接写字符串："apiKey": "sk-xxx"（不推荐，明文存储）
  • SecretRef 对象："apiKey": { "source": "env", "provider": "default", "id": "MY_KEY" }（推荐）

六、自己动手做 Skill

最小可用 Skill

创建一个文件夹和一个文件就行：

mkdir -p ~/.openclaw/workspace/skills/my-translate

---
name: my-translate
description: Translate text between languages using translate-shell CLI
metadata: {"openclaw":{"requires":{"bins":["trans"]}}}
---

# 翻译工具

使用 `trans` 命令行工具进行翻译。

## 基本用法

# 自动检测语言，翻译为中文
trans :zh "Hello, world!"

# 英译日
trans en:ja "Good morning"

# 从文件翻译
trans :fr < input.txt

## 语言代码

使用 ISO 639-1 代码：zh（中文）、en（英文）、ja（日文）、ko（韩文）、
fr（法文）、de（德文）、es（西班牙文）...

重启会话后，AI 就学会了用 trans 命令做翻译。

带条件检查的 Skill

---
name: aws-cost-checker
description: Check AWS billing and cost data
metadata: {"openclaw":{"emoji":"💰","requires":{"bins":["aws"],"env":["AWS_ACCESS_KEY_ID","AWS_SECRET_ACCESS_KEY"]}}}
---

# AWS 账单检查

## 查看本月花费

aws ce get-cost-and-usage \
  --time-period Start=2026-03-01,End=2026-03-27 \
  --granularity MONTHLY \
  --metrics "UnblendedCost"

## 按服务分类

aws ce get-cost-and-usage \
  --time-period Start=2026-03-01,End=2026-03-27 \
  --granularity MONTHLY \
  --metrics "UnblendedCost" \
  --group-by Type=DIMENSION,Key=SERVICE

这个 Skill 只有在系统安装了 aws CLI 且配置了 AWS 凭证时才会被加载。不满足条件时，AI 根本不知道有这个工具存在。

带自动安装器的 Skill

---
name: gemini
description: Use Gemini CLI for coding assistance and Google search lookups.
metadata: {"openclaw":{"emoji":"♊️","requires":{"bins":["gemini"]},"install":[{"id":"brew","kind":"brew","formula":"gemini-cli","bins":["gemini"],"label":"Install Gemini CLI (brew)"}]}}
---

macOS 用户在 OpenClaw UI 里会看到"一键安装"按钮。支持的安装后端：

后端 适用场景
brew macOS Homebrew
node npm/pnpm/yarn/bun
go Go 工具链
uv Python uv 包管理器
download 直接下载压缩包（tar.gz/zip）

安装器还可以限制平台：

{
  "install": [
    {
      "id": "brew",
      "kind": "brew",
      "formula": "my-tool",
      "os": ["darwin"]
    },
    {
      "id": "download",
      "kind": "download",
      "url": "https://example.com/my-tool-linux.tar.gz",
      "os": ["linux"]
    }
  ]
}

七、实际案例：三个真实 Skill 的写法

案例 1：GitHub Skill（最简单的类型）

---
name: github
description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
---

# GitHub Skill

Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo`
when not in a git directory.

## Pull Requests

Check CI status on a PR:
gh pr checks 55 --repo owner/repo

List recent workflow runs:
gh run list --repo owner/repo --limit 10

View logs for failed steps:
gh run view <run-id> --repo owner/repo --log-failed

特点： 没有任何额外依赖（gh CLI 自己处理认证），也没有 metadata 配置。纯粹是"教 AI 怎么用一个已有工具"。

案例 2：Agent Browser（带权限控制）

---
name: Agent Browser
description: A fast Rust-based headless browser automation CLI with Node.js fallback that enables AI agents to navigate, click, type, and snapshot pages via structured commands.
metadata: {"openclaw":{"emoji":"🌐","requires":{"bins":["node","npm"]}}}
allowed-tools: Bash(agent-browser:*)
---

# Browser Automation with agent-browser

## Quick start

agent-browser open <url>        # Navigate to page
agent-browser snapshot -i       # Get interactive elements with refs
agent-browser click @e1         # Click element by ref
agent-browser fill @e2 "text"   # Fill input by ref
agent-browser close             # Close browser

## Core workflow

1. Navigate: `agent-browser open <url>`
2. Snapshot: `agent-browser snapshot -i` (returns elements with refs)
3. Interact using refs from the snapshot
4. Re-snapshot after navigation or significant DOM changes

特点： 使用 allowed-tools: Bash(agent-browser:*) 声明权限——这个 Skill 只能调用 agent-browser 相关的 Bash 命令，不能执行其他任意命令。

案例 3：Self-Improvement（纯知识型，不调用工具）

---
name: self-improvement
description: "Captures learnings, errors, and corrections to enable continuous improvement."
---

# Self-Improvement Skill

Log learnings and errors to markdown files for continuous improvement.

## Quick Reference

| Situation | Action |
|-----------|--------|
| Command/operation fails | Log to `.learnings/ERRORS.md` |
| User corrects you | Log to `.learnings/LEARNINGS.md` with category `correction` |
| User wants missing feature | Log to `.learnings/FEATURE_REQUESTS.md` |
| API/external tool fails | Log to `.learnings/ERRORS.md` with integration details |
| Knowledge was outdated | Log to `.learnings/LEARNINGS.md` with category `knowledge_gap` |
| Found better approach | Log to `.learnings/LEARNINGS.md` with category `best_practice` |

## Promotion Rules

Broadly applicable learning → promote to `AGENTS.md` or `MEMORY.md`
Workflow improvements → promote to `AGENTS.md`
Tool gotchas → promote to `TOOLS.md`
Behavioral patterns → promote to `SOUL.md`

特点： 这个 Skill 不调用任何外部工具。它教 AI 一套自我反思的工作流——遇到错误时记录到文件、被纠正时学习。这是 Skill 的高级用法：不只教"怎么做"，还教"怎么思考"。

八、Skill 的安全模型

Skill 安全不是小事。一个恶意 Skill 可以：

  • 在 SKILL.md 里注入有害的 Prompt 指令
  • 窃取环境变量里的 API Key
  • 诱导 AI 执行破坏性命令

OpenClaw 的四层防护

第一层：加载过滤
requires.bins、requires.env、requires.config 在加载时检查。不满足条件的 Skill 根本不会进入系统提示，AI 完全不知道它的存在。

第二层：环境隔离
Skill 的 env 配置只在单次 Agent 运行时注入，运行结束立即恢复原始 process.env。不是全局环境修改。

第三层：路径安全
工作空间 Skill 的解析路径必须在配置的根目录内。防止通过符号链接逃逸到其他目录。

第四层：沙箱模式
可以在 Docker 沙箱中运行 Agent，限制文件系统和网络访问。requires.bins 在沙箱内部也需要检查——宿主机有 curl 不代表沙箱里也有，需要通过 setupCommand 安装。

用户安全实践

  • 安装前阅读 SKILL.md 内容。Skill 本质上是可执行的 Prompt，和运行代码一样需要审查。
  • 第三方 Skill 视为不可信。不要盲目安装来源不明的 Skill。
  • Secrets 不要写在 SKILL.md 里。使用 apiKey 配置或环境变量注入。
  • 用 allowBundled 白名单控制内置 Skills，只启用需要的。
  • 沙箱隔离用于高风险场景。参见 agents.defaults.sandbox 配置。

九、多 Agent 场景下的 Skills

在多 Agent 配置中，Skills 按作用域分层：

~/.openclaw/workspace-coding/skills/    ← coding Agent 独有
~/.openclaw/workspace-writing/skills/   ← writing Agent 独有
~/.openclaw/skills/                     ← 所有 Agent 共享
层级 路径 作用域 典型用途
工作空间 <workspace>/skills/ 仅对应 Agent 专业工具
本地 ~/.openclaw/skills/ 所有 Agent 通用工具
额外目录 skills.load.extraDirs 所有 Agent 团队共享
内置 npm 包内 所有 Agent 基础能力

同名 Skill 按优先级覆盖：工作空间 > 本地 > 额外目录 > 内置。

这种设计让不同 Agent 可以有完全不同的能力组合：coding Agent 装 GitHub、浏览器自动化工具；writing Agent 装文章写作、翻译工具；它们互不干扰，共用的工具放在 ~/.openclaw/skills/ 下。

十、Skill vs Plugin vs Prompt Engineering

维度 Skill Plugin Prompt Engineering
本质 给 AI 看的文档 给程序跑的代码 直接写 Prompt
格式 SKILL.md + 文件夹 JS/TS 代码 + npm 包 纯文本
安装方式 复制文件夹 / ClawHub npm install 写进 system prompt
加载机制 系统提示注入 代码级集成 手动粘贴
生命周期 会话级别刷新 进程级别 每次对话
可分享 ✅ ClawHub ✅ npm ❌ 复制粘贴
可版本化 ✅ semver ✅ npm version ❌
权限控制 requires.bins/env/config 代码级 API 无

一句话总结：Plugin 是给程序加功能，Skill 是给 AI 加知识，Prompt Engineering 是临时调教。

十一、ClawHub：Skill 的 npm

ClawHub 是 OpenClaw 的官方 Skill 注册中心。

核心功能

  • 语义搜索：用 embedding 做向量搜索，不只是关键词匹配
  • 版本管理：semver + changelog + tag，支持回滚
  • 社区反馈：Star、评论、举报机制
  • 安全审核：举报超 3 次自动下架，有专门审核团队
  • 发布同步：支持单个发布和批量同步

安装方式对比

# OpenClaw 原生命令（推荐日常使用）
openclaw skills install <slug>
openclaw skills update --all

# ClawHub CLI（适合发布和批量管理）
npm i -g clawhub
clawhub install <slug>
clawhub publish ./my-skill --slug my-skill --version 1.0.0
clawhub sync --all

发布流程

# 1. 准备 Skill 目录
mkdir my-awesome-skill && cd my-awesome-skill
# 写好 SKILL.md 和相关文件...

# 2. 登录 ClawHub
clawhub login

# 3. 发布
clawhub publish . \
  --slug my-awesome-skill \
  --name "My Awesome Skill" \
  --version 1.0.0 \
  --tags latest

# 4. 批量同步本地所有 Skills
clawhub sync --all

社区生态

截至 2026 年 3 月，围绕 OpenClaw Skills 的社区项目包括：

  • awesome-openclaw-agents：162 个生产级 Agent 模板，涵盖 19 个类别
  • edict：基于中国古典"十二部制"的多 Agent 编排系统（13k+ Stars）
  • Star-Office-UI：像素风办公室可视化，每个 Agent 是一个角色（6k+ Stars）
  • OpenMOSS：自组织多 Agent 协作平台

十二、总结

Agent Skills 做了一件看似简单但影响深远的事：把"怎么使用某个工具"这件事标准化了。

以前，你得手把手告诉 AI “用 curl 调 wttr.in，参数格式是…”，每次对话都要重复。

现在，装一个 Skill，AI 永远记住了。

它的核心价值不在于技术多复杂，而在于三个特性：

  • 可复用：写一次，所有会话都能用
  • 可分享：发布到 ClawHub，全世界的 AI 都能学会
  • 可版本化：semver 管理，随时回滚

下次当你觉得"AI 应该会做这件事但就是做不好"的时候，别急着骂模型不行。先看看：有没有一个 Skill 可以装？

快速上手

# 查看已安装的 Skills
openclaw skills list

# 搜索你需要的
openclaw skills search "翻译"
openclaw skills search "pdf"

# 安装
openclaw skills install <skill-slug>

# 检查运行条件
openclaw skills check

# 开新会话生效
项目 内容
作者 胡小纯
发布日期 2026-03-27
联系微信 hu–xiaochun
个人主页 https://胡小纯.cn
备用主页 https://xn–yets91feqb.cn/

技术没有捷径，但有方向

# 人工智能
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

【花雕动手做】行空板 K10 系列实验之人工智能调用语音合成（TTS）模块

avatar AI Agent技术社区
cover

Havenlon 对抗性完整（一）：不是谁可信，而是谁可能变坏

avatar AI Agent技术社区
cover

苏州企业AI Agent智能体从概念到落地：2026年开发者必须关注的技术范式与工程实践

avatar AI Agent技术社区