Skill（技能）是 AI Agent 的能力单元，描述了 Agent 能做什么、怎么做、以及需要什么上下文。Skill 将 AI 的能力从"通用对话"扩展到"专业化任务执行"。
本文系统性地介绍 Skill 的设计理念、组成结构、工作原理、开发规范以及生态体系，帮助开发者构建高质量的 AI 技能。
Skill 是一个结构化的能力描述，包含三个核心维度：
类比理解：
| 类比 | 说明 |
|---|---|
| 人类技能 | 像"做饭"——需要食材（输入）、厨具（工具）、菜谱（步骤） |
| 软件插件 | 像 VS Code 扩展——提供特定功能，可按需安装 |
| 微服务 | 像独立的业务模块——有明确接口，可独立部署和调用 |
| 维度 | 传统插件 | AI Skill |
|---|---|---|
| 交互方式 | 用户手动触发 | AI 自主判断何时使用 |
| 上下文感知 | 无 | 基于当前对话状态自动获取上下文 |
| 组合能力 | 独立运行 | 多个 Skill 可以链式组合 |
| 自适应 | 固定行为 | 可以根据输入动态调整执行策略 |
| 描述方式 | API 接口 | 自然语言描述 + 结构化定义 |
在现代 AI Agent 架构中，Skill 位于应用层与工具层之间：
┌─────────────────────────────────────┐
│ 用户交互层 │
│ (对话界面、API 调用、触发器) │
├─────────────────────────────────────┤
│ Agent 决策层 │
│ (意图识别、Skill 匹配、任务规划) │
├─────────────────────────────────────┤
│ ┌─────────┐ ┌─────────┐ ┌────────┐ │
│ │ Skill 1 │ │ Skill 2 │ │Skill 3 │ │ ← Skill 层
│ │ 天气查询 │ │ Git提交 │ │Wiki发布│ │
│ └────┬────┘ └────┬────┘ └───┬────┘ │
├───────┼───────────┼──────────┼──────┤
│ │ MCP 协议层 │ │
├───────┼───────────┼──────────┼──────┤
│ ┌────┴────┐ ┌───┴────┐ ┌───┴────┐ │
│ │ 天气API │ │ Git CLI│ │Wiki API│ │ ← 工具层
│ └─────────┘ └────────┘ └────────┘ │
└─────────────────────────────────────┘
Skill 的核心价值在于：将底层工具封装为语义化的业务能力，让 AI 能够自主理解和调用。
一个完整的 Skill 通常包含以下文件结构：
skill-name/
├── SKILL.md # 技能描述文件（核心，必须）
├── README.md # 使用说明与文档
├── scripts/ # 辅助脚本
│ └── helper.py
└── references/ # 参考资料
└── example.md
SKILL.md 是 Skill 的"身份证"和"使用说明书"，采用 YAML Frontmatter + Markdown 的混合格式：
---
name: git-commit
version: 1.2.0
skills:
- self-improving-agent
author: hugogu
description: |
智能 Git 提交助手，自动分析变更内容生成符合
Conventional Commits 规范的提交信息。
---
# Git Commit Skill
## 描述
智能 Git 提交助手，自动分析变更内容生成符合 Conventional Commits 规范的提交信息。
## 适用场景
- 用户说"commit"、"提交"、"保存到 git"
- 需要分析当前 git diff 内容
- 需要生成规范的提交消息
## 执行步骤
1. 检查 git status，获取变更文件列表
2. 读取 git diff，分析变更类型（feat/fix/docs等）
3. 生成符合 Conventional Commits 格式的消息
4. 执行 git commit --author="..."
## 工具
- `git status`
- `git diff`
- `git log`
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scope | string | 否 | 变更范围（如 auth、api） |
| breaking | bool | 否 | 是否包含破坏性变更 |
| amend | bool | 否 | 是否修改上次提交 |
## 示例
### 示例 1：常规功能提交
feat(auth): add OAuth2 login support
### 示例 2：修复提交
fix(api): resolve race condition in payment callback
## 依赖
- git >= 2.30
- 工作目录必须是 git 仓库
- 已配置 git user.name 和 user.email
## 注意事项
- 如果存在未跟踪的大文件，会提示用户确认
- 生成提交信息后需用户确认再执行
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
name |
✅ | string | Skill 唯一标识，kebab-case 命名 |
version |
❌ | string | 语义化版本号（如 1.2.0） |
description |
✅ | string | 自然语言描述，AI 用此判断是否匹配当前任务 |
skills |
❌ | array | 依赖的其他 Skill 名称列表 |
author |
❌ | string | 作者信息 |
tools |
❌ | array | 需要的工具列表（如 git、curl） |
parameters |
❌ | array | 可配置参数及其类型、说明 |
examples |
❌ | array | 使用示例，帮助 AI 理解调用方式 |
dependencies |
❌ | array | 环境依赖（如特定软件版本） |
README.md 面向人类用户，提供更详细的文档：
# Git Commit Skill
## 安装
```bash
# 通过 ClawHub 安装
openclaw skill install git-commit
# 手动安装
git clone https://github.com/hugogu/git-commit-skill ~/.openclaw/skills/git-commit
用户: 提交当前变更
Agent: 检测到 3 个文件变更，生成提交信息：
feat(auth): add OAuth2 login support
确认提交？(y/n)
用户: 提交，范围是 api，包含破坏性变更
Agent: 生成提交信息：
feat(api)!: redesign payment webhook interface
BREAKING CHANGE: webhook payload format changed
在 ~/.openclaw/config.yml 中设置默认参数：
skills:
git-commit:
default_scope: ""
auto_commit: false # 是否跳过确认直接提交
Q: 如何自定义提交信息模板？
A: 修改 SKILL.md 中的示例部分，Agent 会学习你的风格。
Q: 支持多语言提交信息吗？
A: 支持，在描述中指定语言偏好即可。
---
## 3. Skill 的工作原理
### 3.1 匹配过程
当用户发送请求时，Agent 通过以下流程选择 Skill：
用户请求 → 语义匹配 → 选择最相关的 Skill → 加载 SKILL.md → 按步骤执行
**匹配依据的三层模型**：
1. **语义相似度层**
- Skill 描述中的关键词与用户请求的相似度
- 使用向量嵌入计算语义距离
- 示例：用户说"发布文章"→匹配 wiki-publisher Skill
2. **上下文感知层**
- 当前工作目录（如在代码目录 → 优先代码类 Skill）
- 历史对话主题（如刚讨论过 Docker → 优先 docker-deploy）
- 用户角色和偏好（如开发者 vs 产品经理）
3. **经验反馈层**
- 历史使用频率（常用 Skill 优先）
- 成功率统计（高成功率 Skill 优先）
- 用户显式反馈（点赞/踩影响排序）
### 3.2 执行过程
Skill 的执行是一个**状态机流程**：
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 解析 │ → │ 收集 │ → │ 执行 │ → │ 处理 │ → │ 更新 │
│ SKILL.md│ │ 上下文 │ │ 工具调用 │ │ 结果 │ │ 状态 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
理解任务目标 读取环境变量 按步骤调用 生成回复 记录执行
拆解执行步骤 访问文件系统 工具/脚本 格式化输出 更新历史
查询历史记录 反馈统计
**详细执行流程**：
1. **解析阶段**
- 读取 SKILL.md 的 YAML Frontmatter 获取元数据
- 解析 Markdown 内容，提取执行步骤
- 识别需要的工具和参数
2. **上下文收集阶段**
- 读取环境变量（如 `WIKI_KEY`、`OPENAI_API_KEY`）
- 访问文件系统（如 `~/.openclaw/workspace/`）
- 查询历史记录和对话状态
- 验证依赖是否满足（如 git 版本检查）
3. **执行阶段**
- 按步骤顺序执行，每步对应一个工具调用或判断
- 支持条件分支（如"如果存在冲突，则执行解决步骤"）
- 支持循环（如"对每个文件执行格式化"）
4. **结果处理阶段**
- 汇总工具执行结果
- 格式化输出（如生成 Markdown 表格）
- 错误处理和重试逻辑
5. **状态更新阶段**
- 记录执行结果到历史
- 更新 Skill 使用统计
- 触发后续 Skill（如执行完 git-commit 后自动调用 message-send 通知）
### 3.3 链式组合
多个 Skill 可以组合完成复杂任务，形成**Skill Pipeline**：
用户: "帮我发布这篇文章到 Wiki"
┌─────────────────────────────────────────────────────────────┐
│ Skill Pipeline │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Skill 1 │ → │ Skill 2 │ → │ Skill 3 │ │
│ │ wiki-publisher│ │ git-commit │ │ message-send │ │
│ │ │ │ │ │ │ │
│ │ 1. 读取文件 │ │ 1. git add │ │ 1. 构建消息 │ │
│ │ 2. 格式化内容 │ │ 2. git commit│ │ 2. 发送通知 │ │
│ │ 3. 创建页面 │ │ 3. git push │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ 依赖关系: wiki-publisher → git-commit → message-send │
│ （在 SKILL.md 的 skills 字段声明） │
└─────────────────────────────────────────────────────────────┘
**组合模式**：
| 模式 | 说明 | 示例 |
|------|------|------|
| **串行** | 按顺序执行，前一个输出作为后一个输入 | 读取文件 → 格式化 → 发布 |
| **并行** | 多个 Skill 同时执行，结果合并 | 同时查询天气和股价 |
| **条件** | 根据结果选择分支 | 如果发布成功则通知，失败则回滚 |
| **循环** | 对集合中的每个元素执行 | 批量发布多篇文章 |
---
## 4. 如何编写 Skill
### 4.1 设计原则
编写高质量 Skill 需遵循五项核心原则：
1. **单一职责原则（SRP）**
- 一个 Skill 只做一件事，做好一件事
- 反例：一个 Skill 既处理 Git 提交又发送邮件
- 正例：git-commit 只处理提交，message-send 只处理通知
2. **自描述原则**
- 通过 SKILL.md 让 AI 能自主判断何时使用
- 描述必须包含触发条件和排除条件
- 示例优于抽象说明
3. **可组合原则**
- 设计时考虑与其他 Skill 的协作
- 输入输出格式标准化（如统一使用 Markdown）
- 声明依赖关系，避免循环依赖
4. **容错性原则**
- 处理边界情况和错误，给出明确反馈
- 提供回退策略（如 API 失败时使用缓存）
- 验证输入参数，防止注入攻击
5. **渐进式原则**
- 从简单版本开始（MVP），逐步增强
- 先解决核心场景，再处理边缘情况
- 通过用户反馈迭代优化
### 4.2 编写步骤
步骤 1: 明确 Skill 的目标场景
↓
步骤 2: 定义输入（用户请求、环境上下文）
↓
步骤 3: 定义输出（执行结果、返回给用户的内容）
↓
步骤 4: 拆解执行步骤（每个步骤对应一个工具调用或判断）
↓
步骤 5: 编写 SKILL.md 描述文件
↓
步骤 6: 测试并迭代优化
**详细说明**：
**步骤 1：明确目标场景**
- 回答三个问题：谁在什么情况下需要做什么？
- 示例："开发者在代码变更后需要快速生成规范的提交信息"
**步骤 2：定义输入**
- 用户输入：自然语言请求、文件路径、参数
- 环境输入：工作目录、环境变量、配置文件
- 隐式输入：历史对话、用户偏好
**步骤 3：定义输出**
- 直接输出：执行结果、生成的内容
- 副作用：文件修改、API 调用、通知发送
- 状态变更：历史记录更新、统计数据
**步骤 4：拆解执行步骤**
- 每个步骤必须是**原子操作**（不可再分）
- 步骤之间通过**数据流**连接
- 支持条件判断和异常处理
**步骤 5：编写 SKILL.md**
- 参考模板（见 2.1 节）
- 使用自然语言描述，避免技术黑话
- 提供至少 2 个具体示例
**步骤 6：测试迭代**
- 单元测试：每个步骤独立测试
- 集成测试：完整流程测试
- 用户测试：真实场景验证
### 4.3 描述撰写技巧
**好的描述 vs 差的描述**：
```markdown
# ✅ 好的描述
## 描述
Use when user asks about weather, temperature, or forecasts
for any location.
NOT for:
- historical weather data
- severe weather alerts
- detailed meteorological analysis
## 触发关键词
天气、温度、预报、下雨、晴、多云、气温
## 示例
用户: "北京明天天气怎么样？"
用户: "需要带伞吗？"
用户: "下周上海气温如何？"
# ❌ 差的描述
## 描述
This skill gets weather information.
描述撰写要点：
| 要点 | 说明 | 示例 |
|---|---|---|
| 触发条件 | 明确什么时候用 | "用户询问天气、温度或预报" |
| 排除条件 | 明确什么时候不用 | "不用于历史天气数据或气象分析" |
| 关键词 | 列出高频触发词 | "天气、温度、预报、下雨" |
| 具体示例 | 提供真实对话示例 | 用户说"北京明天天气怎么样？" |
| 输出格式 | 说明返回内容的格式 | "返回 Markdown 表格，包含温度、天气、风力" |
参数设计遵循最小必要原则：
parameters:
- name: location
type: string
required: true
description: "城市名称或坐标，如 '北京' 或 '39.9,116.4'"
examples: ["北京", "上海", "纽约"]
- name: days
type: integer
required: false
default: 3
description: "预报天数，1-15"
validation: "min=1, max=15"
- name: unit
type: enum
required: false
default: "celsius"
options: ["celsius", "fahrenheit"]
description: "温度单位"
参数类型支持：
| 类型 | 说明 | 验证规则 |
|---|---|---|
string |
字符串 | min/max length, regex |
integer |
整数 | min/max value |
number |
浮点数 | min/max value, precision |
boolean |
布尔值 | true/false |
enum |
枚举值 | 预定义选项列表 |
array |
数组 | item type, min/max length |
object |
对象 | schema validation |
file |
文件路径 | existence check |
场景：用户需要将本地 Markdown 文章发布到 Wiki.js
SKILL.md 核心内容：
---
name: wiki-publisher
version: 2.1.0
description: |
Publish markdown content to Wiki.js with proper formatting
and metadata handling. Supports creating new pages and
updating existing ones.
skills:
- git-commit # 发布后可选择提交到 git
tools:
- curl # 调用 Wiki.js GraphQL API
- grep # 提取 YAML frontmatter
---
# Wiki Publisher
## 描述
将 Markdown 内容发布到 Wiki.js，支持格式清理、元数据提取和页面管理。
## 触发条件
- User wants to publish content to their Wiki.js instance
- Converting articles, notes, or analysis to wiki format
- Creating new wiki pages with proper structure
- Updating existing wiki pages
## 排除条件
- NOT for: publishing to other platforms (Notion, Confluence)
- NOT for: raw file upload without formatting
## 执行步骤
1. Extract content - Get markdown from user or read from file
2. Clean formatting - Remove YAML frontmatter, convert links
3. Extract metadata - Parse title, description, tags from frontmatter
4. Validate - Check content length and required fields
5. Suggest metadata - Propose path, tags, description if missing
6. Confirm with user - Show proposed wiki location and preview
7. Create or Update - Execute pages.create or pages.update mutation
8. Verify - Fetch page to confirm successful publication
9. Return link - Provide wiki page URL
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| content | string | 是 | Markdown 内容或文件路径 |
| path | string | 否 | Wiki 页面路径（如 tech/guide） |
| title | string | 否 | 页面标题 |
| tags | array | 否 | 标签列表 |
| description | string | 否 | 页面描述 |
## 示例
### 示例 1：发布新文章
用户: 把这篇文章发到 Wiki
[粘贴 Markdown 内容]
Agent: 检测到内容，建议发布到路径：articles/my-article
标题：我的文章
确认发布？(y/n)
### 示例 2：更新现有页面
用户: 更新 Wiki 上的 Docker 指南
[粘贴更新内容]
Agent: 找到现有页面 docker-guide (ID: 42)
执行更新...
更新完成：https://wiki.example.com/docker-guide
## 依赖
- WIKI_KEY 环境变量已设置
- Wiki.js GraphQL API 可访问
- Markdown 内容长度 > 100 字符
## 注意事项
- 创建时必须设置 isPublished: true
- 更新时保留原有 tags 和 description
- 图片链接需要转换为 Wiki.js 格式
设计亮点：
场景：为项目设置完整的 Docker 部署基础设施
SKILL.md 核心内容：
---
name: docker-deploy
version: 3.0.0
description: |
Set up complete Docker-based virtualized deployment
infrastructure with docker-compose, multi-environment
support, and registry management.
skills:
- git-commit
tools:
- docker
- docker-compose
- bash
---
# Docker Deploy
## 描述
为项目搭建完整的 Docker 容器化部署方案，支持本地开发、测试和生产多环境配置。
## 触发条件
- Users ask for Docker deployment setup
- Containerization of existing applications
- docker-compose configuration
- Multi-environment deployments (dev/staging/prod)
- Registry management and image versioning
## 排除条件
- NOT for: Kubernetes deployment (use k8s-deploy Skill)
- NOT for: serverless deployment (use lambda-deploy Skill)
## 执行步骤
1. Analyze project structure
- Detect language/framework (Node.js, Python, Java, Go)
- Identify dependencies and services
- Check existing Dockerfile/docker-compose.yml
2. Create Dockerfile
- Multi-stage build for optimization
- Security best practices (non-root user, minimal base image)
- Health check and proper signal handling
3. Create docker-compose.yml
- Service definitions with dependencies
- Volume mounts for persistent data
- Environment variable configuration
4. Set up multi-environment config
- docker-compose.dev.yml (hot reload, debug tools)
- docker-compose.prod.yml (optimized, scaled)
- .env.example with documentation
5. Create build/push scripts
- build.sh with version tagging
- push.sh for registry upload
- Registry prefix switching logic
6. Document usage
- README with quick start commands
- Troubleshooting guide
## 参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_type | enum | 是 | 项目类型：node/python/java/go |
| registry | string | 否 | 镜像仓库地址 |
| prefix | string | 否 | 镜像名前缀 |
| services | array | 否 | 依赖服务（db/redis等） |
## 示例
### 示例 1：Node.js 项目
用户: 给这个 Node.js 项目配 Docker
Agent: 检测到 Express.js 项目
创建 Dockerfile（基于 node:18-alpine）
创建 docker-compose.yml（app + postgres + redis）
创建多环境配置...
完成！运行 docker-compose up 启动
## 依赖
- Docker >= 20.10
- docker-compose >= 2.0
- 项目根目录有 package.json/requirements.txt 等
## 注意事项
- 生产环境必须使用非 root 用户运行容器
- 敏感信息通过环境变量注入，不硬编码
- 多阶段构建减小最终镜像体积
设计亮点：
场景：用户要求"帮我搭建一个完整的监控报警系统"
这个需求需要多个 Skill 组合：
┌──────────────────────────────────────────────────────────────┐
│ 监控报警系统部署 Pipeline │
├──────────────────────────────────────────────────────────────┤
│ │
│ 用户: "帮我搭建一个完整的监控报警系统" │
│ │
│ ┌─────────────┐ │
│ │ 意图识别 │ → 匹配到 "monitoring-setup" Skill │
│ └──────┬──────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ monitoring-setup Skill │ │
│ │ （协调者 Skill，负责编排子 Skill） │ │
│ └────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────┼────┬────────┬────────┐ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌──┐ ┌──┐ ┌──┐ ┌──┐ ┌──┐ │
│ │S1│ │S2│ │S3│ │S4│ │S5│ │
│ │docker│ │prometheus│ │grafana│ │alertmanager│ │notification│ │
│ │-deploy│ │-setup│ │-setup│ │-setup│ │-setup│ │
│ └──┘ └──┘ └──┘ └──┘ └──┘ │
│ │ │ │ │ │ │
│ └────┴────┴────────┴────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ 整合输出 │ │
│ │ - Docker Compose 配置 │ │
│ │ - 监控面板 JSON │ │
│ │ - 报警规则 YAML │ │
│ │ - 部署文档 │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────┘
协调者 Skill 的设计：
---
name: monitoring-setup
version: 1.0.0
description: |
Set up a complete monitoring and alerting stack
including Prometheus, Grafana, and AlertManager.
skills:
- docker-deploy # 部署容器化基础设施
- prometheus-setup # 配置 Prometheus 采集
- grafana-setup # 配置 Grafana 面板
- alertmanager-setup # 配置报警路由
- notification-setup # 配置通知渠道
---
# Monitoring Setup
## 描述
搭建完整的监控报警系统，包括数据采集、可视化、报警和通知。
## 触发条件
- "搭建监控系统"
- "配置 Prometheus"
- "设置 Grafana 面板"
- "部署监控报警"
## 执行步骤
1. 调用 docker-deploy 创建基础容器编排
2. 调用 prometheus-setup 配置采集目标
3. 调用 grafana-setup 导入面板模板
4. 调用 alertmanager-setup 配置报警规则
5. 调用 notification-setup 配置通知渠道（钉钉/邮件/Slack）
6. 整合所有配置，生成部署文档
## 输出
- docker-compose.monitoring.yml
- prometheus.yml
- grafana-dashboards/
- alertmanager.yml
- README.md
OpenClaw 的官方 Skill 市场：clawhub.ai
功能特性：
| 功能 | 说明 |
|---|---|
| 浏览搜索 | 按分类、标签、热度浏览 Skill |
| 一键安装 | openclaw skill install <name> 快速安装 |
| 版本管理 | 支持安装特定版本和自动更新 |
| 评价反馈 | 用户评分和评论，帮助选择 |
| 依赖解析 | 自动安装 Skill 依赖的其他 Skill |
Skill 分类：
ClawHub/
├── development/ # 开发工具
│ ├── git-commit/
│ ├── code-review/
│ └── docker-deploy/
├── devops/ # 运维工具
│ ├── monitoring-setup/
│ ├── ci-cd/
│ └── log-analysis/
├── productivity/ # 效率工具
│ ├── wiki-publisher/
│ ├── note-organizer/
│ └── meeting-minutes/
├── data/ # 数据处理
│ ├── data-cleaning/
│ ├── visualization/
│ └── etl-pipeline/
└── custom/ # 用户自定义
└── ...
Skill 的本地存储结构：
~/.openclaw/
├── config.yml # 全局配置
├── skills/ # 已安装 Skill 目录
│ ├── weather/
│ │ ├── SKILL.md
│ │ ├── README.md
│ │ └── scripts/
│ ├── wiki-publisher/
│ │ ├── SKILL.md
│ │ ├── README.md
│ │ └── scripts/
│ └── custom-skill/ # 自定义 Skill
│ ├── SKILL.md
│ └── ...
├── cache/ # Skill 执行缓存
│ └── weather/
│ └── last_result.json
└── logs/ # 执行日志
└── 2024-01-15/
└── wiki-publisher.log
常用命令：
# 列出已安装 Skill
openclaw skill list
# 安装 Skill
openclaw skill install wiki-publisher
# 安装特定版本
openclaw skill install wiki-publisher@2.1.0
# 更新 Skill
openclaw skill update wiki-publisher
# 卸载 Skill
openclaw skill uninstall wiki-publisher
# 查看 Skill 详情
openclaw skill info wiki-publisher
# 测试 Skill
openclaw skill test wiki-publisher
采用语义化版本管理（SemVer）：
版本格式：主版本号.次版本号.修订号（如 2.1.0）
- 主版本号（Major）：不兼容的 API 修改
- 次版本号（Minor）：向下兼容的功能新增
- 修订号（Patch）：向下兼容的问题修复
版本兼容性规则：
| 场景 | 行为 |
|---|---|
| 依赖 Skill 版本冲突 | 提示用户选择或自动选择最新兼容版本 |
| Major 版本升级 | 需要用户确认，可能包含破坏性变更 |
| Minor/Patch 升级 | 自动更新，保持向后兼容 |
向 ClawHub 贡献 Skill 的流程：
1. Fork ClawHub 仓库
2. 创建 Skill 目录（遵循命名规范）
3. 编写 SKILL.md 和 README.md
4. 本地测试通过
5. 提交 Pull Request
6. 社区审核（自动化测试 + 人工 review）
7. 合并发布
贡献规范：
git-commit）Skill 是更高层的抽象：
| 维度 | MCP Tool | Skill |
|---|---|---|
| 抽象层级 | 底层功能（如"读文件"） | 业务能力（如"发布文章到 Wiki"） |
| 包含内容 | 单一工具调用 | 业务逻辑 + 判断条件 + 执行流程 |
| 组合方式 | 被 Skill 调用 | 调用 Tool 或其他 Skill |
| 描述方式 | JSON Schema | 自然语言 + 结构化定义 |
类比：
可以。在 SKILL.md 的 skills 字段声明依赖：
skills:
- git-commit
- wiki-publisher
- message-send
依赖解析规则：
通过以下多层上下文获取机制：
| 来源 | 方式 | 示例 |
|---|---|---|
| 环境变量 | os.environ |
WIKI_KEY, OPENAI_API_KEY |
| 文件系统 | 读取配置文件 | ~/.openclaw/config.yml |
| 历史记录 | 查询对话数据库 | 用户偏好、过往操作 |
| 系统信息 | 执行系统命令 | pwd, git status |
| 用户输入 | 解析自然语言 | "用中文回复"、"详细一点" |
错误处理策略：
重试机制
retry:
max_attempts: 3
backoff: exponential # 指数退避
回退策略
fallback:
- "使用备用 API"
- "返回缓存数据"
- "提示用户手动处理"
错误报告
error_handling:
log: true # 记录日志
notify: true # 通知用户
detail: "full" # 完整错误信息
# ❌ 不好的设计：一个 Skill 做太多事
name: devops-toolkit
description: "处理所有 DevOps 任务"
# ✅ 好的设计：拆分为独立 Skill
name: docker-deploy
description: "部署 Docker 容器"
name: k8s-deploy
description: "部署 Kubernetes 资源"
name: monitoring-setup
description: "搭建监控系统"
# ❌ 模糊的示例
示例：用户可以使用这个 Skill 来提交代码
# ✅ 具体的示例
示例 1：
用户: "提交当前变更"
Agent: 检测到 3 个文件变更：
- src/auth.js (修改)
- tests/auth.test.js (新增)
- README.md (修改)
生成提交信息：
feat(auth): add OAuth2 login support
确认提交？(y/n)
示例 2：
用户: "提交，范围是 api"
Agent: 生成提交信息：
fix(api): resolve race condition in payment callback
确认提交？(y/n)
# ❌ 遗漏依赖
dependencies: []
# ✅ 完整声明
dependencies:
software:
- name: git
version: ">= 2.30"
reason: "需要 git status 和 git diff 命令"
- name: node
version: ">= 18"
reason: "脚本使用 ES6 语法"
environment:
- name: WIKI_KEY
required: true
description: "Wiki.js API 密钥"
- name: WIKI_URL
required: false
default: "https://wiki.example.com"
description: "Wiki.js 实例地址"
skills:
- git-commit
- message-send
## 边界情况处理
### 情况 1：内容为空
如果提取的 Markdown 内容长度 < 100 字符：
- 提示用户内容过短
- 询问是否继续发布
### 情况 2：路径已存在
如果目标路径已存在页面：
- 获取现有页面内容
- 询问用户：更新 / 取消 / 创建到新路径
### 情况 3：API 失败
如果 Wiki.js API 返回 403/500：
- 重试 3 次（指数退避）
- 如果仍失败，保存到本地文件
- 提示用户手动同步
---
name: wiki-publisher
version: 2.1.0
compatible_with:
openclaw: ">= 1.5.0"
wiki_js: ">= 2.5.0"
---
## 变更日志
### v2.1.0 (2024-01-15)
- 新增：支持批量发布多篇文章
- 修复：处理图片链接转换问题
- 改进：优化大文件上传性能
### v2.0.0 (2023-12-01)
- 破坏性变更：移除 `force` 参数，改为交互式确认
- 新增：支持更新现有页面
- 改进：错误处理机制
### v1.5.0 (2023-11-15)
- 新增：支持 YAML frontmatter 解析
- 修复：特殊字符转义问题
| 概念 | 关系 | 链接 |
|---|---|---|
| MCP 模型上下文协议 | Skill 与工具的连接协议 | [[MCP 模型上下文协议]] |
| OpenClaw Agent 框架 | Skill 的运行环境 | [[OpenClaw Agent 框架]] |
| LLM 大语言模型 | Skill 的语义理解基础 | [[LLM 大语言模型]] |
| AI 知识体系 | 更广泛的 AI 概念 | [[AI 知识体系]] |
---
name: my-skill
description: "一句话描述这个 Skill 的作用"
---
# My Skill
## 描述
详细描述 Skill 的功能和适用场景。
## 触发条件
- 什么时候使用这个 Skill
## 执行步骤
1. 第一步
2. 第二步
3. 第三步
## 示例
用户: "示例请求"
Agent: "示例响应"
---
name: production-skill
version: 1.0.0
author: "your-name"
description: |
多行详细描述，包含触发条件和排除条件。
skills:
- dependency-skill
tools:
- tool-name
parameters:
- name: param1
type: string
required: true
description: "参数说明"
dependencies:
software:
- name: node
version: ">= 18"
environment:
- name: API_KEY
required: true
---
# Production Skill
## 描述
...
## 触发条件
...
## 排除条件
...
## 执行步骤
...
## 参数
...
## 示例
...
## 依赖
...
## 注意事项
...
## 变更日志
...
参考资料：OpenClaw 官方文档、ClawHub 规范、MCP 协议规范
最后更新：2026-05-02