技能开发中的常见错误和最佳实践
开发 OpenClaw 技能时，有些错误很容易犯，有些最佳实践能让你的技能更好用。本文整理了我开发技能过程中的一些经验。
常见错误
1. SKILL.md 写得太模糊
错误写法：
# 我的技能
这个技能很厉害，可以做很多事情。AI 看不懂，不知道有哪些工具、参数是什么，肯定用不对。
正确写法：
# 字数统计
统计文本和文件的字数、词数、行数。
## 可用工具
### count_words(text: string)
统计文本字数。
**参数：**
- text: string - 要统计的文本
**返回：** JSON 格式的统计结果清晰、完整，AI 一看就懂。
2. 不做错误处理
错误： 直接崩溃，不返回错误信息
正确： 捕获错误，返回 {error: "错误描述"}，AI 能告诉你哪里错了
try {
// 你的代码
return JSON.stringify(result);
} catch (e) {
return JSON.stringify({error: e.message});
}3. API Key 硬编码进代码
错误：
const API_KEY = "sk-1234567890";把 API Key 提交到 GitHub 会被盗用，而且每个人的 API Key 不一样。
正确：
const API_KEY = process.env.MY_API_KEY;让用户把 API Key 放在环境变量里。
4. SKILL.md 不写参数说明
AI 不知道每个参数是什么类型、做什么用，调用的时候经常传错。
一定要写：
**参数：**
- city: string - 要查询天气的城市名称5. 一个技能做太多事情
“我这个技能既能发邮件又能查天气还能写博客…”
最佳实践： 一个技能聚焦一件事，做好做精。技能可以组合使用，不需要把所有功能塞到一个技能里。
最佳实践
1. 让 TypeScript 可选，但 JavaScript 没问题
如果你会 TypeScript，可以用它，类型安全少出错。不会也没关系，纯 JavaScript 完全够用。
2. 返回结构化数据
尽量返回 JSON，AI 容易解析。比纯文本好。
// 好
return JSON.stringify({city: "北京", temp: "18", text: "晴"});
// 不好
return "北京今天18度，晴天";3. 添加使用示例
在 SKILL.md 最后加个使用示例，用户一看就知道怎么用。
## 使用示例
> 帮我统计一下 README.md 文件的字数4. 使用环境变量存储配置
配置信息（API Key、地址、端口…）都放在环境变量，不要写死在代码里。这样：
- ✅ 安全，不会泄露 API Key
- ✅ 用户可以自己配置
- ✅ 代码可以公开分享
5. 添加 README 给人看
SKILL.md 是给 AI 看的，可以再加一个 README.md 给人看，介绍：
- 这个技能做什么的
- 怎么安装配置
- 使用示例
6. 一次工具调用做一件事
不要设计一个工具做十件事，分成多个工具更清晰。
// 好
get_current_weather()
get_forecast()
// 不好
get_weather(type, city)7. 验证参数
在工具执行前验证参数：
if (!params.city) {
return JSON.stringify({error: "缺少必填参数: city"});
}AI 能马上知道哪里错了。
8. 处理依赖
如果需要第三方 npm 包，在技能目录加 package.json:
{
"name": "your-skill",
"version": "1.0.0",
"dependencies": {
"axios": "^1.6.0"
}
}用户 npm install 就可以了。
总结
记住这些要点，你的技能会更容易使用，更少出问题：
- ✅ SKILL.md 清晰完整，每个工具参数都说明白
- ✅ 做好错误处理，返回结构化错误信息
- ✅ API Key 放环境变量，不要硬编码
- ✅ 一个技能做一件事
- ✅ 返回 JSON 而不是纯文本
遵循这些实践，你的技能会更加专业！