🎯 什么是 Agent Skills？
Agent Skills 是 OpenClaw 生态系统中的核心概念，它是扩展 AI Agent 能力的模块化单元。就像给 Agent 安装"技能包"，让它学会新能力。
Skills 架构概览
+-- Agent Core
|
+-- Skill Loader
|
+-- Skill 1: Browser Automation
+-- Skill 2: File Operations
+-- Skill 3: API Integration
+-- Skill 4: Data Processing
|
+-- Skill Registry (ClawHub)
🛠️ 开发环境搭建
1. 安装 OpenClaw
# 安装 OpenClaw CLI
npm install -g openclaw
# 验证安装
openclaw --version
# 初始化配置
openclaw init
npm install -g openclaw
# 验证安装
openclaw --version
# 初始化配置
openclaw init
2. 创建技能项目
# 创建新技能
openclaw skill create my-awesome-skill
# 进入项目目录
cd my-awesome-skill
# 查看项目结构
tree -L 2
openclaw skill create my-awesome-skill
# 进入项目目录
cd my-awesome-skill
# 查看项目结构
tree -L 2
📁 标准项目结构
my-awesome-skill/
├── skill.json # 技能元数据
├── README.md # 使用文档
├── package.json # 依赖配置
├── src/
│ ├── index.js # 主入口
│ └── utils.js # 工具函数
├── test/
│ └── index.test.js # 测试用例
└── examples/
└── basic.js # 使用示例
✍️ 编写你的第一个 Skill
1. 定义技能元数据 (skill.json)
{
"name": "my-awesome-skill",
"version": "1.0.0",
"description": "一个很棒的技能示例",
"author": "你的名字",
"main": "src/index.js",
"keywords": ["automation", "productivity"],
"openclaw": {
"minVersion": "2026.6.0",
"permissions": ["file:read", "file:write"]
}
}
"name": "my-awesome-skill",
"version": "1.0.0",
"description": "一个很棒的技能示例",
"author": "你的名字",
"main": "src/index.js",
"keywords": ["automation", "productivity"],
"openclaw": {
"minVersion": "2026.6.0",
"permissions": ["file:read", "file:write"]
}
}
2. 实现技能逻辑 (src/index.js)
const { Skill } = require('@openclaw/core');
class MyAwesomeSkill extends Skill {
// 技能初始化
async init() {
this.logger.info('技能初始化完成');
}
// 核心功能实现
async execute(options) {
const { input } = options;
// 参数验证
if (!input) {
throw new Error('input 参数不能为空');
}
// 业务逻辑
const result = await this.process(input);
return {
success: true,
data: result
};
}
async process(input) {
// 实现你的业务逻辑
return input.toUpperCase();
}
}
module.exports = MyAwesomeSkill;
class MyAwesomeSkill extends Skill {
// 技能初始化
async init() {
this.logger.info('技能初始化完成');
}
// 核心功能实现
async execute(options) {
const { input } = options;
// 参数验证
if (!input) {
throw new Error('input 参数不能为空');
}
// 业务逻辑
const result = await this.process(input);
return {
success: true,
data: result
};
}
async process(input) {
// 实现你的业务逻辑
return input.toUpperCase();
}
}
module.exports = MyAwesomeSkill;
3. 添加配置支持
const { Skill } = require('@openclaw/core');
class ConfigurableSkill extends Skill {
async init() {
// 加载配置
this.config = await this.loadConfig();
}
async loadConfig() {
const defaultConfig = {
apiKey: '',
timeout: 30000,
retries: 3
};
const userConfig = this.getConfig();
return { ...defaultConfig, ...userConfig };
}
}
class ConfigurableSkill extends Skill {
async init() {
// 加载配置
this.config = await this.loadConfig();
}
async loadConfig() {
const defaultConfig = {
apiKey: '',
timeout: 30000,
retries: 3
};
const userConfig = this.getConfig();
return { ...defaultConfig, ...userConfig };
}
}
🧪 测试与调试
1. 编写单元测试
const { MyAwesomeSkill } = require('../src/index.js');
describe('MyAwesomeSkill', () => {
let skill;
beforeEach(() => {
skill = new MyAwesomeSkill();
});
test('应该正确执行', async () => {
const result = await skill.execute({ input: 'hello' });
expect(result.success).toBe(true);
expect(result.data).toBe('HELLO');
});
test('应该处理错误输入', async () => {
await expect(skill.execute({})).rejects.toThrow();
});
});
describe('MyAwesomeSkill', () => {
let skill;
beforeEach(() => {
skill = new MyAwesomeSkill();
});
test('应该正确执行', async () => {
const result = await skill.execute({ input: 'hello' });
expect(result.success).toBe(true);
expect(result.data).toBe('HELLO');
});
test('应该处理错误输入', async () => {
await expect(skill.execute({})).rejects.toThrow();
});
});
2. 本地测试
# 运行测试
npm test
# 本地安装测试
openclaw skill install .
# 运行技能
openclaw run my-awesome-skill --input "test"
npm test
# 本地安装测试
openclaw skill install .
# 运行技能
openclaw run my-awesome-skill --input "test"
⚠️ 调试技巧
- 使用
this.logger.debug()输出调试信息 - 在
skill.json中设置"debug": true - 使用 VS Code 调试器附加到进程
- 查看 OpenClaw 日志:
~/.openclaw/logs/
📦 打包与发布
步骤 1: 准备工作
- ✅ 确保代码已通过所有测试
- ✅ 更新 README.md 文档
- ✅ 检查 version 号（遵循语义化版本）
- ✅ 添加使用示例（examples/ 目录）
步骤 2: 打包技能
# 验证技能包
openclaw skill validate
# 打包技能
openclaw skill package
# 检查生成的包
ls -lh dist/
openclaw skill validate
# 打包技能
openclaw skill package
# 检查生成的包
ls -lh dist/
步骤 3: 发布到 ClawHub
# 登录 ClawHub
openclaw hub login
# 发布技能
openclaw skill publish
# 查看发布状态
openclaw skill info my-awesome-skill
openclaw hub login
# 发布技能
openclaw skill publish
# 查看发布状态
openclaw skill info my-awesome-skill
🎨 高级技巧
1. 技能组合（Skill Composition）
一个技能可以调用其他技能，实现复杂功能：
class AdvancedSkill extends Skill {
async execute(options) {
// 调用其他技能
const browserSkill = this.getSkill('browser-automation');
const page = await browserSkill.open('https://example.com');
const fileSkill = this.getSkill('file-ops');
await fileSkill.write('output.html', page.content());
}
}
async execute(options) {
// 调用其他技能
const browserSkill = this.getSkill('browser-automation');
const page = await browserSkill.open('https://example.com');
const fileSkill = this.getSkill('file-ops');
await fileSkill.write('output.html', page.content());
}
}
2. 事件驱动（Event-Driven）
class EventAwareSkill extends Skill {
async init() {
// 监听事件
this.on('file:created', this.onFileCreated);
}
async onFileCreated(event) {
this.logger.info(`文件已创建: ${event.path}`);
}
}
async init() {
// 监听事件
this.on('file:created', this.onFileCreated);
}
async onFileCreated(event) {
this.logger.info(`文件已创建: ${event.path}`);
}
}
3. 性能优化
⚡ 性能优化清单
- 使用缓存减少重复计算
- 实现懒加载（Lazy Loading）
- 异步处理耗时操作
- 合理设置超时时间
- 监控内存使用情况
📊 发布后维护
版本管理
# 查看当前版本
openclaw skill version
# 升级版本号（自动按语义化版本递增）
npm version patch # 1.0.0 -> 1.0.1
npm version minor # 1.0.0 -> 1.1.0
npm version major # 1.0.0 -> 2.0.0
# 发布新版本
openclaw skill publish
openclaw skill version
# 升级版本号（自动按语义化版本递增）
npm version patch # 1.0.0 -> 1.0.1
npm version minor # 1.0.0 -> 1.1.0
npm version major # 1.0.0 -> 2.0.0
# 发布新版本
openclaw skill publish
处理用户反馈
- 及时回复 Issue 和评论
- 修复 bug 并发布补丁版本
- 根据用户需求添加新功能
- 保持文档更新