AI Agent Skills 设计与编写实战指南

关键点在于每个字段必须有 description，必填项要写清楚，类型要严格（string / number / boolean）。

4. 执行逻辑（handler / function）

也就是你真正的代码实现：

export async function get_weather({ city }: { city: string }) {
  return `当前 ${city} 天气晴，30°C`;
}

设计原则

写 Skill 不是随便写函数，而是设计'AI 能力模块'。

单一职责

一个 Skill 只做一件事。不要写成 get_weather_and_news，而是拆分为 get_weather 和 get_news。

可复用

避免写死逻辑。不要写 get_kuala_lumpur_weather()，而是 get_weather(city)。

对 AI 友好

你写的是给 AI 用的，不是给人看的。描述要像提示词一样自然，参数边界要明确。

实战示例：执行服务器命令

结合 OpenClaw，我们写一个实用 Skill 来执行服务器命令：

{
  "name": "run_shell_command",
  "description": "在服务器上执行安全的 shell 命令，用于查询系统状态、文件信息等。禁止执行删除、格式化等危险操作。",
  "parameters": {
    "type": "object",
    "properties": {
      "command": {"type": "string", "description": "需要执行的 shell 命令"}
    },
    "required": ["command"]
  }
}

为什么这样设计？ 关键在于明确'允许范围'以确保安全，同时限制 AI 行为防止乱删文件。

安全设计

如果你涉及云服务器控制、文件操作或自动部署，安全限制是必须的。

常见风险

• rm -rf /
• 删除数据库
• 泄露敏感信息

解决方案

1. 命令白名单

只允许特定的安全命令：

const allowList = ["ls", "cat", "pwd", "df", "top"];

2. 路径限制

确保操作在安全目录内：

if (!path.startsWith("/safe-dir")) {
  throw new Error("非法路径");
}

3. 参数校验

严格检查输入类型：

if (typeof command !== "string") {
  throw new Error("参数错误");
}

优化调用体验

为了让 AI 更容易调用你的 Skill，可以尝试以下技巧：

1. 在 description 中加入触发语义：例如'当用户询问天气、气温、下雨情况时使用该技能'。
2. 避免技能重叠：不要同时提供 get_weather, query_weather, fetch_weather，这会让 AI 困惑。
3. 返回结构化数据：相比字符串，返回 {"temperature": 30, "weather": "sunny"} 更利于后续处理。

调试方法

在开发过程中，可以通过命令行工具查看日志来排查问题：

openclaw doctor openclaw logs

调试思路主要关注三点：AI 是否调用了 Skill、参数是否正确、返回值是否合理。

进阶：组合 Skills

真正强大的 Agent 不是靠单个 Skill，而是多个技能的组合。例如生成周报的流程可以是：

1. get_git_commits（获取提交记录）
2. analyze_changes（分析变更）
3. generate_report（生成报告）

通过这种组合，可以实现自动化周报生成的实战场景落地。

总结

一句话总结：Skill = Prompt + API + 安全控制的结合体。写好 Skills，你的 Agent 才真正具备干活的能力。在设计时，请始终遵循命名清晰、描述详细、参数严格、安全可控的原则。