AI Agent 中的 Skills定义解析（详解作用与使用方法）

Skills 是 AI Agent 里的模块化能力包，用一份 SKILL.md 文件告诉 agent 这项能力干什么、什么时候用、怎么调、结果长什么样。它把 agent 从只会聊天的机器人变成能干活的员工：装上天气技能能查预报，装上邮件技能能收发邮件，装上代码技能能调起编码器。OpenClaw 内置 50 多种技能，社区 ClawHub 上还有数百个可装。下文拆解 Skills 的结构、加载机制和用法。

一、Skills 到底是什么

一个 Skill 就是一个目录，里面放指令、脚本和资源，agent 按需自动发现和加载。它的本质是过程性知识注入，不提供外部操作能力，只定义“任务该怎么做”的完整流程与判断标准。

组成	作用	是否必选
SKILL.md	指令主体，含 YAML frontmatter	必选
tools/	可执行脚本	可选
config.json	配置和 API 凭据	可选
资源文件	参考、模板	可选

SKILL.md 的 frontmatter 里 description 字段至关重要，OpenClaw 用它决定何时激活该技能。写得越具体，激活越准。

---
name: weather
description: Get weather forecasts and current conditions
---
# Weather Skill
Ask about weather in any location:
- "What's the weather in Tokyo?"
- "Will it rain tomorrow?"
## Commands
Run: curl wttr.in/<location>

二、加载机制与优先级

2.1 从哪里加载

OpenClaw 从多个来源加载技能，同名冲突按优先级覆盖。

<workspace>/skills：工作区技能，优先级最高；
<workspace>/.agents/skills：项目 agent 技能；
~/.agents/skills：个人 agent 技能，跨工作区；
~/.openclaw/skills：托管/本地共享技能；
捆绑技能：随安装包分发；
skills.load.extraDirs：额外目录，优先级最低。

工作区赢，然后依次往下覆盖。

2.2 渐进式公开

Skill 不把所有内容一次性塞进上下文，而是分三层按需加载。

层级	内容	占用
发现层	名称 + 描述	约 100 token
激活层	完整 SKILL.md	通常 < 5k token
执行层	脚本、模板、参考	按需读取，不占上下文

agent 像翻手册一样：先看目录，再翻相关章节，最后查附录。知识量理论无上限，因为按需检索而非一次性消费。

2.3 多 agent 的技能白名单

位置和可见性是两套控制。位置决定同名技能哪份赢，白名单决定 agent 能用哪些。

{
  "agents": {
    "defaults": { "skills": ["github", "weather"] },
    "list": [
      { "id": "writer" },
      { "id": "docs", "skills": ["docs-search"] },
      { "id": "locked-down", "skills": [] }
    ]
  }
}

locked-down 的空数组表示不用任何技能，writer 继承默认，docs 替换为 docs-search。

三、怎么用怎么造

3.1 列出、安装、启用

openclaw skills list 列出可用技能，或直接问 agent“你有哪些技能”；
clawhub install <slug> 从 ClawHub 市场装社区技能，或 git clone 到 ~/.openclaw/skills；
把技能目录放进工作区即启用，OpenClaw 自动发现加载；
用 openclaw doctor 查技能加载报错，修语法问题。

3.2 手动造一个技能

造一个 Todoist 集成技能，目录结构和 SKILL.md 如下。

my-skill/
├── SKILL.md          # 指令（必选）
├── tools/            # 脚本（可选）
│   └── check.sh
└── config.json       # 配置（可选）

---
name: todoist
description: Manage Todoist tasks - list, create, complete, and delete tasks
---
# Todoist Integration
When the user asks about tasks or todos, use the Todoist CLI.
## Available Commands
- `todoist list` — Show all tasks
- `todoist add "task name"` — Create a task
- `todoist complete <id>` — Mark a task as done
## Requirements
- Todoist CLI installed: `pip install todoist-cli`
- API token in `~/.todoist.cfg`

description 写“通过 WhatsApp 向任何联系人发送消息”比写“WhatsApp 集成”更利于激活，触发短语要在指令里点明。

3.3 安全红线

技能能执行任意代码，必须当不可信代码对待。安装前审查跑了哪些命令，优先选官方和已验证技能，不赋超出所需的权限，定期查日志发现意外行为。OpenClaw 的危险代码扫描器在安装时跑，critical 发现默认阻断，suspicious 仅告警。

常见问题（FAQ）

Q1：Skills 和 Tools 有什么区别？

Tools 是动手干活的工具，Skills 是教你怎么用、按什么步骤干。

Q2：技能没被激活怎么办？

检查目录位置、SKILL.md frontmatter，用 doctor 查语法。

Q3：第三方技能能直接装吗？

能，但要当不可信代码，先审查再启用，优先沙箱跑。