用 AI Agent 控制机械臂：Skill 驱动的智能机器人开发教程

想象一下这样的场景：

你："抓起桌上那个绿色的瓶盖"
它：打开摄像头 -> 识别瓶盖 -> 计算位置 -> 精准抓取 -> 完成

你："把它放到左边"
它：提起物体 -> 平滑移动 -> 放下 -> 归位

你："跳个舞"
它：......它真的跳了

这不是科幻。这是一份 SKILL.md 文件 + Claude Code 做到的事。

本文将教你：如何用 Skill 系统让 AI Agent 直接控制物理世界的机械臂。不写控制代码，用自然语言指挥机器人。

项目开源地址：github.com/Linmoqian/claw_arm

docs目录下提供了更详细的教程

核心思想：Skill 是 AI 控制物理世界的桥梁

传统机器人开发的流程是：人写控制代码 -> 机器人执行。

这个项目做了一件不一样的事：让 AI 读一份 Skill 文档，自主决策如何控制机械臂。

传统方式：人 --写代码--> 机器人
本项目：  人 --写Skill--> AI Agent --自主决策--> 机器人

Skill 是一份 Markdown 文件，描述了：

• AI 应该遵守什么规则（安全第一）
• 机械臂有哪些关节、怎么控制
• 视觉系统怎么用、坐标系怎么转换
• 遇到异常怎么处理

AI 读完 Skill 后，就能理解物理世界的约束，安全、准确地控制机械臂。

你将构建的系统

最终效果

在终端中输入自然语言，机械臂立即执行：

cd claw_arm
claude

> 帮我控制机械臂抓起那个绿色物体
  [AI 读取 Skill] → [打开摄像头检测] → [计算位姿] → [控制关节移动] → [闭合夹爪]

> 把它放到左边
  [AI 规划路径] → [平滑移动] → [释放] → [归位]

系统架构

整个系统以 Skill 为中心，连接 AI 和物理世界：

                    +------------------+
                    |    SKILL.md      |
                    |  (控制规则文档)   |
                    +--------+---------+
                             |
              +--------------+--------------+
              |                             |
     +--------v--------+          +---------v---------+
     |   AI Agent      |          |   物理世界         |
     | (Claude Code)   |          |                   |
     |  理解意图       |          |  SO-100 机械臂    |
     |  规划动作       |          |  USB 摄像头       |
     |  生成指令       |          |  STS3215 舵机     |
     +--------+--------+          +---------+---------+
              |                             ^
              |    串口指令 / Python 脚本    |
              +-----------------------------+

Skill 的引用文件构成 AI 对物理世界的认知：

skills/nature_arm/
├── SKILL.md                      # 核心规则文档（为了这叠醋包的饺子
[video(video-cUQoJAYk-1775476418167)(type-csdn)(url-https://live.csdn.net/v/embed/520489)(image-https://i-blog.csdnimg.cn/img_convert/a97cf7ecca8fc2b697b2dec8b7bf8f5f.jpeg)(title-抓取)]
[video(video-iNbE4ENi-1775476425262)(type-csdn)(url-https://live.csdn.net/v/embed/520489)(image-https://i-blog.csdnimg.cn/img_convert/a97cf7ecca8fc2b697b2dec8b7bf8f5f.jpeg)(title-抓取)]

）
├── references/
│   └── so100_calibration.md      # 关节校准数据（AI 需要的参数）
└── scripts/
    ├── SDK/                      # 串口通信协议（AI 调用的底层）
    ├── simple_joint.py           # 关节控制（AI 的执行手段）
    └── simple_pnp.py             # 视觉定位（AI 的感知手段）

第一步：环境搭建

这个项目需要两套运行时：Python（控制硬件）和 Node.js（运行 Claude Code）。

1.1 安装 Node.js

Windows：从 Node.js 官网 下载 LTS 版本，双击安装。

macOS / Linux：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

验证：

node --version   # v20.x+
npm --version    # 10.x+

1.2 安装 Claude Code

Claude Code 是 Anthropic 官方的 AI 编程助手，也是运行 Skill 的平台。

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# macOS / Linux
curl -fsSL https://claude.ai/install.sh | bash

备选方式：

方式	命令
npm	npm install -g @anthropic-ai/claude-code
macOS Homebrew	brew install --cask claude-code
Windows WinGet	winget install Anthropic.ClaudeCode

OpenClaw 也可以作为替代方案：npm install -g openclaw。它支持多种 AI 模型，但注意 2026 年 4 月起通过 OpenClaw 使用 Claude 需要 API Key 计费。

1.3 安装 Python 环境

git clone https://github.com/Linmoqian/claw_arm.git
cd claw_arm

conda env create -f environment.yml
conda activate claw_arm

依赖只有三个：opencv-python、numpy、pyserial。

1.4 验证全部就绪

python -c "import cv2, numpy, serial; print('Python OK')"
claude --version

第二步：硬件准备

物料清单

组件	推荐型号	参考价格
机械臂	SO-100 (6自由度)	1500-2000 元
摄像头	USB 1080p	100-200 元
电源	12V 5A	30 元
标定板	棋盘格 9x6	20 元（可选）

总预算约 1700 元起。

SO-100 机械臂关节布局

ID	关节	作用
1	底座旋转 (base)	左右旋转
2	肩关节 (shoulder)	前后俯仰
3	肘关节 (elbow)	小臂弯曲
4	腕俯仰 (wrist_pitch)	手腕上下
5	腕旋转 (wrist_roll)	手腕旋转
6	夹爪 (gripper)	抓取/释放

连接与测试

# 确认串口号（Windows 设备管理器 / Linux: ls /dev/ttyUSB*）
# 修改脚本中的串口号后测试

python script/1.3test_motors.py   # 电机逐个转动
python CV/1_camera_test.py        # 摄像头画面弹出

两个都通过，硬件就准备好了。

第三步：理解 Skill——AI 控制机械臂的核心

这是本文最重要的部分。Skill 是一份 Markdown 文件，它是 AI Agent 和物理世界之间的"说明书"。

3.1 完整的 SKILL.md

项目中的 skills/nature_arm/SKILL.md：

---
name: nature_arm
description: 自然的机械臂。
metadata: {env: python, mode: control}
---

# 规则

- 第一守则：绝对确保用户安全
- 第二守则：绝对保障自身安全
- 第三守则：最快反馈现实实体
- 运动要求：低速平滑消除抖动
- 代码生成：非必要不新写代码
- 代码改动：代码最小化的更改
- 服务保证：环境完备端口正确
- 思考要求：尽快进行安全响应
- 专注领域：专注于机械臂任务

# 触发条件

任何涉及"机械臂"的相关词。

# 关节描述

ID:1~6的描述参考 @\references\so100_calibration.md
关节 1-5 为运动轴，通道 6 控制末端夹爪开合

# 关节控制

基于描述，参考 @\scripts\simple_joint.py 进行控制

# 空间理解

基于pnp进行位姿理解，参考 @\scripts\simple_pnp.py 进行理解，
输出的位姿是相机坐标系，输出单位：毫米

# SDK接入

SDK的位置位于 @\scripts\SDK ，若出现错误，必须先检索 SDK 文档确认参数定义

# 异常处理
- 通信丢失：立即停止发送指令，保持当前力矩。
- 用户急停：收到"停止"、"急停"指令，跳过所有逻辑，直接发送 Stop 信号。
- 报错处理：捕获异常日志，分析原因后建议用户重试或回退，不盲目重试。

# 交互风格
- 响应简洁，直接反馈执行状态（成功/失败/原因）。

# 格外建议
- 在抓取任务时：抵达目标位置后应该先停顿1s，再进行夹爪抓取

3.2 逐块解析

Frontmatter——告诉 AI 这是什么技能

name: nature_arm              # 技能名，也是斜杠命令名
description: 自然的机械臂。    # AI 根据这个判断何时激活

当用户说"帮我控制机械臂"或输入 /nature_arm，AI 就会加载这个 Skill。

规则——AI 的行为约束

这不是普通代码规则，而是给 AI 的"安全锁"。机器人三原则的变体：

• 用户安全 > 自身安全 > 执行效率
• 低速平滑，禁止猛烈动作
• 代码最小改动，不瞎写新代码

触发条件——什么时候激活

任何涉及"机械臂"的相关词。

AI 会根据对话内容自动判断是否需要激活这个 Skill。

引用——AI 的知识来源

@\references\so100_calibration.md   # 机械臂的关节参数
@\scripts\simple_joint.py           # 怎么控制关节
@\scripts\simple_pnp.py             # 怎么通过视觉定位
@\scripts\SDK                       # 底层通信协议

@\path 语法让 AI 在执行时读取这些文件，获得精确的参数和接口定义。不需要把所有代码塞进 SKILL.md，引用外部文件即可。

异常处理——紧急情况的行为

AI 遇到问题时不盲目重试，而是停下来分析。收到"急停"指令时跳过所有逻辑直接停止。

3.3 Skill 引用的知识文件

AI 通过引用文件获得对物理世界的理解：

关节参数 (references/so100_calibration.md)：

# 零点位置（按顺序1-6）
zero_shoulder_pan = 2078
zero_shoulder_lift = 930
zero_elbow_flex = 3008
...

# 运动范围
range_shoulder_pan = 721, 3489
range_shoulder_lift = 919, 3301
...

AI 读到这些数据后，就知道每个关节的安全范围，不会发出超出极限的指令。

关节控制接口 (scripts/simple_joint.py)：

class Joint:
    def enable(self): ...     # 启用扭矩
    def disable(self): ...    # 释放扭矩
    def move(self, position): # 移动到目标位置 (0-4095)
    def position(self) -> int:# 读取当前位置

AI 读取接口定义后，就知道该调用哪些方法来控制关节。

视觉定位 (scripts/simple_pnp.py)：

AI 读取后理解整个感知-决策-执行链：

• GreenDetector 检测目标物体
• PoseEstimator 通过 PnP 算法计算 3D 位姿
• ArmKinematics 做逆运动学求解
• Arm.camera_to_base() 将相机坐标转到基座坐标
• MotorController 发送最终的关节指令

3.4 SKILL.md 字段参考

字段	说明
name	技能名称，决定斜杠命令 /name
description	用途描述，AI 据此自动匹配触发时机
disable-model-invocation	设为 true 禁止自动触发，仅手动
allowed-tools	免确认使用的工具列表
context	设为 fork 在隔离子代理中运行

第四步：Skill 背后——硬件控制层

Skill 告诉 AI “做什么”，底层模块告诉机械臂 “怎么做”。了解这些有助于你编写更好的 Skill。

4.1 舵机通信协议

机械臂通过串口通信，波特率 1000000。SDK 封装了三个核心寄存器操作：

寄存器	地址	功能	用法
TORQUE_ENABLE	40	扭矩开关	写 1 启用，写 0 释放
GOAL_POSITION	42	目标位置	写入 0-4095 的目标角度
PRESENT_POSITION	56	当前位置	读取当前角度（只读）

from SDK import PortHandler, PacketHandler

port = PortHandler("COM7")
port.setBaudRate(1000000)
port.openPort()

pkt = PacketHandler(0.0)
pkt.write1ByteTxRx(port, motor_id, 40, 1)   # 启用扭矩
pkt.write2ByteTxRx(port, motor_id, 42, 2048) # 移动到中间位置
pos, _, _ = pkt.read2ByteTxRx(port, motor_id, 56)  # 读取位置

位置范围 0-4095，对应舵机旋转 0-360 度。

4.2 关节控制封装

Joint 类提供更安全的接口：

from Joints.simple_joint import Joint

joint = Joint(port, pkt, joint_id=2)  # 肩关节

joint.enable()
joint.move(2047)              # 移动到中间位置
print(joint.position())       # 读取当前角度
joint.disable()               # 安全释放

move() 内置了范围限制 max(0, min(4095, position))，防止超出机械极限。

4.3 视觉感知层

Skill 引用的 simple_pnp.py 实现了完整的感知-定位链：

class GreenDetector:
    """HSV 颜色检测：找到绿色物体"""
    def detect(self, frame): ...

class PoseEstimator:
    """PnP 位姿估计：从像素坐标算出 3D 位置"""
    def estimate(self, center): ...

class ArmKinematics:
    """SO100 运动学：逆运动学求解关节角度"""
    def inverse_simple(self, target_position): ...

class Arm:
    """串联一切：视觉 -> 坐标转换 -> 运动"""
    def move_to(self, t_cam): ...    # 相机坐标 -> 基座坐标 -> 关节角度
    def grasp(self, close=True): ... # 抓取/释放

数据流：

摄像头帧 → HSV 颜色过滤 → 轮廓提取 → 中心点坐标
→ PnP 位姿估计 → 相机坐标 (mm)
→ 手眼标定转换 → 基座坐标 (mm)
→ 逆运动学 → 6个关节角度
→ 串口发送 → 机械臂执行

4.4 坐标转换

AI 需要理解的核心概念——坐标系统：

坐标系	参考物	示例
像素坐标	图像平面	(320, 240) 像素
相机坐标	摄像头	(15, -20, 300) mm
基座坐标	机械臂底座	(43, -59, 342) mm

手眼标定矩阵（simple_pnp.py 中已包含）：

R_cam2base = np.array([
    [0.994, -0.069, -0.084],
    [0.107,  0.502,  0.858],
    [-0.017, -0.862,  0.506]
])
t_cam2base = np.array([28.4, -39.2, 42.1])  # mm

# 相机坐标 → 基座坐标
t_base = R_cam2base @ t_cam + t_cam2base

这个标定矩阵是你的安装位置决定的。换一个摄像头角度就需要重新标定。

4.5 平滑运动

预设位置 + S 曲线插值保证动作平滑：

POSES = {
    "home":        [2123, 1966, 2077, 2082, 2041, 2006],
    "right_above": [2500, 1800, 1200, 1500, 1900, 2500],
    "right_pick":  [2500, 1900, 1000, 1200, 1900, 2500],
    "center":      [2123, 1700, 1400, 1600, 2041, 2500],
    "left_above":  [1700, 1800, 1200, 1500, 2200, 2500],
    "left_place":  [1700, 1900, 1000, 1200, 2200, 2500],
}

# S 曲线插值：起止速度为零，中间平滑过渡
smooth_t = t * t * (3 - 2 * t)

第五步：安装 Skill 到 Claude Code

Skill 文件准备好了，现在让 Claude Code 能找到它。

5.1 放置 Skill

三种方式，按推荐程度排序：

方式一：项目级（推荐）

cd claw_arm
mkdir -p .claude/skills
cp -r skills/nature_arm .claude/skills/

只在 claw_arm 项目中生效，跟随项目版本控制。

方式二：–add-dir 加载

claude --add-dir ./skills

不修改项目结构，灵活但需要每次手动指定。

方式三：个人级

cp -r skills/nature_arm ~/.claude/skills/

你的所有项目都能用，但可能与其它项目冲突。

5.2 启动并使用

cd claw_arm
claude

两种触发方式：

斜杠命令（手动触发，明确指定）：

> /nature_arm 抓取桌面上的绿色物体
> /nature_arm 把东西放到左边
> /nature_arm 跳个舞

自然语言（AI 自动匹配）：

> 帮我控制机械臂抓起那个方块
> 让机械臂回到初始位置

AI 根据 description: 自然的机械臂。 自动判断是否激活 Skill。

5.3 AI 执行流程

当你发出"抓取绿色物体"的指令后，AI 的完整执行链：

1. 加载 SKILL.md，读取规则和引用文件
2. 调用 simple_pnp.py 中的 GreenDetector 检测绿色物体
3. 调用 PoseEstimator 计算 3D 位姿（相机坐标系）
4. 调用 Arm.camera_to_base() 转换到基座坐标系
5. 调用 ArmKinematics.inverse_simple() 做逆运动学求解
6. 调用 MotorController.move_angles() 发送关节指令
7. 等待 1 秒（Skill 中的"格外建议"）
8. 调用 Arm.grasp(True) 闭合夹爪
9. 反馈执行结果

AI 自主完成了从感知到执行的完整链路。你只需要一句话。

第六步：编写自己的 Skill

理解了 nature_arm 后，你可以编写新的 Skill 扩展机械臂的能力。

6.1 创建新 Skill

mkdir -p skills/pick_cup/references

编写 skills/pick_cup/SKILL.md：

---
name: pick_cup
description: 专门抓取杯子并放到指定位置。识别杯子形状和位置。
---

# 规则
- 安全第一，运动前检查路径上是否有障碍物
- 杯子易碎，下降速度必须比平时慢 50%
- 抓取前先停顿 2 秒确认位置

# 触发条件
用户要求抓取杯子、水杯、马克杯相关操作。

# 检测策略
杯口为圆形，使用 Hough 圆检测而非颜色检测。
参考 OpenCV 的 HoughCircles 函数。

# 流程
1. 使用 HoughCircles 检测杯口位置
2. 移动到杯口正上方 5cm 处
3. 停顿 2 秒确认
4. 缓慢下降（steps=50，比默认慢）
5. 闭合夹爪
6. 提升到安全高度
7. 移动到用户指定的目标位置
8. 释放杯子

# 参考
关节参数：@\references\so100_calibration.md
关节控制：@\scripts\simple_joint.py

6.2 编写 Skill 的要点

1. 规则要具体。不要只写"注意安全"，要写"下降速度必须比平时慢 50%"。AI 会严格遵守你写的规则。

2. 善用引用。@\path 让 Skill 文件保持简洁，细节放到引用文件中。AI 执行时会读取全部引用。

3. 定义异常处理。告诉 AI 遇到问题时该怎么做，而不是盲目重试。

4. 描述触发条件。好的 description 让 AI 准确判断何时激活 Skill，避免误触发。

6.3 Skill 目录的完整结构

一个完善的 Skill 可以这样组织：

skills/my_skill/
├── SKILL.md              # 核心规则文件（必需）
├── references/           # 参数和数据（AI 的知识库）
│   ├── calibration.md    # 标定数据
│   └── color_config.md   # 颜色阈值
└── scripts/              # 可执行脚本（AI 的工具）
    ├── detect.py         # 检测逻辑
    └── control.py        # 控制逻辑

第七步：飞书远程控制（可选）

配置飞书机器人后，可以在飞书聊天中用自然语言控制机械臂。
打开网址，创建应用：
https://open.feishu.cn/app
配置长连接接收事件

7.1 导入权限配置

项目根目录的 feishu.json 定义了飞书机器人所需的权限，将其导入：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "aily:knowledge:read",
      "aily:knowledge:write",
      "aily:message:read",
      "aily:message:write",
      "aily:run:read",
      "aily:run:write",
      "aily:session:read",
      "aily:session:write",
      "aily:skill:read",
      "aily:skill:write",
      "app_engine:application.environment_variable:read",
      "auth:user_access_token:read",
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.reactions:write_only",
      "im:message:send_as_bot",
      "im:message:update"
    ],
    "user": [
      "aily:skill:write"
    ]
  }
}

7.2 配置步骤

1. 登录飞书开放平台
2. 创建企业自建应用
3. 进入「权限管理」→「导入权限配置」→ 上传 feishu.json
4. 确认权限生效后发布应用

配置完成后，在飞书对话中就能用自然语言控制机械臂。
以下为效果图。

openclaw配置

1.下载飞书插件
2.绑定对应密钥

第八步：进阶方向

替换视觉模块

当前使用 HSV 颜色检测，只能识别预设颜色。在 Skill 中引用 YOLO 模型，可以识别任意物体：

# 检测策略
使用 YOLOv8 进行目标检测，模型路径：@\models\yolo_v8n.pt
支持识别：瓶子、杯子、苹果、书本等 COCO 类别物体。

多 Skill 协作

为不同任务编写不同 Skill：

skills/
├── nature_arm/     # 通用机械臂控制
├── pick_cup/       # 杯子搬运专家
├── sort_color/     # 颜色分拣专家
└── dance/          # 舞蹈动作库

AI 会根据对话内容自动选择合适的 Skill。

LeRobot 具身智能

集成 HuggingFace LeRobot 框架，让机械臂通过模仿学习自主完成复杂任务。Skill 可以从"按规则执行"进化为"从示范中学习"。

故障排除

Claude Code 找不到 Skill

确认目录结构：.claude/skills/nature_arm/SKILL.md 或使用 --add-dir。

AI 控制动作不准

1. 重新标定相机（python script/2.2calibration.py）
2. 更新 references/so100_calibration.md 中的校准数据
3. 检查 simple_pnp.py 中的手眼标定矩阵

电机连接不上

检查项	操作
串口号	确认设备管理器中的端口号
驱动	安装 CH340 或 CP2102
波特率	必须是 1000000
占用	关闭其它串口工具

AI 触发了错误动作

在 SKILL.md 的规则中添加更具体的约束。比如"移动前必须先读取当前位置确认安全"。

技术栈总结

层级	技术	在系统中的角色
AI Agent	Claude Code / OpenClaw	大脑：理解意图、规划动作
Skill	SKILL.md + 引用文件	规则：约束 AI 行为、提供知识
语言	Python 3.10	执行：实际控制硬件
视觉	OpenCV + PnP	眼睛：检测物体、计算位姿
运动	NumPy + 逆运动学	小脑：关节角度求解
通信	pySerial + SDK	神经：串口指令传输
硬件	STS3215 舵机	肌肉：执行物理动作
远程	飞书机器人	延伸：聊天界面控制

写在最后

OpenClaw 技能编写规范

OpenClaw 的 Skill 遵循 AgentSkills 规范，本质上是一个包含元数据和说明文件的文件夹。

SKILL.md 的格式：

文件名：skills//SKILL.md
顶部 YAML frontmatter（最重要的是 name / description / metadata.openclaw）
正文用 Markdown 写“什么时候用、怎么用、示例命令/示例 JSON、注意事项”等内容。

skill 的 metadata.openclaw.requires 可以声明需要的 bins / env / config 等
用户侧配置在 ~/.openclaw/openclaw.json 的 skills 下（启用/禁用、注入 env、apiKey 便捷字段等）

这个项目的核心洞察是：AI Agent 不需要写控制代码，它只需要一份好的 Skill 文档。

Skill 是连接 AI 世界和物理世界的桥梁。你写的不只是代码，而是 AI 理解物理世界的"说明书"。关节参数、安全范围、控制接口、视觉定位——这些知识通过 Skill 传递给 AI，让它能够安全、准确地操控机械臂。

这种 Skill 驱动的模式可以扩展到更多场景：3D 打印机、CNC 机床、无人机。核心思路不变——把物理世界的知识写成 Skill，让 AI 自主决策执行。

“最好的 AI 控制不是让 AI 写代码，而是让 AI 读说明书。”

“如果这个项目对你有帮助，欢迎到 GitHub 给个 Star。”

参考开发文档

飞书API文档：https://open.feishu.cn/document/home/index?lang=zh-CN
Lerobot开发文档：https://hugging-face.cn/docs/lerobot/index
通义千问API文档：https://help.aliyun.com/zh/model-studio/qwen-api-reference/
so-arm100开发文档:https://huggingface.co/docs/lerobot/so100
openclaw的skills开发文档：https://docs.openclaw.ai/zh-CN/tools/skills
SDK来自：https://gitee.com/ftservo/FTServo_Python/tree/main/scservo_sdk

硬件选型

相机：随便（门锁都行）
通信方式：UART串口通信
电源：5.5 mm×2.1 mm DC 5 V 4 A
舵机选型：飞特（FeeTech）舵机、Feetech_STS3215、ST-3215- C001 (7.4V) 1:345 齿轮比电机

机械臂校准

方式1：使用Lerobot提供的标定工具进行机械臂校准：

lerobot-calibrate --robot.type=so100_follower --robot.port=COM7 --robot.id=my_so100_arm

程序会引导您：

• 第一步：将机械臂移动到中间位置，按 Enter
• 第二步：移动所有关节通过完整运动范围，按 Enter

完成后会生成标定文件 calibration_my_so100_arm.json，包含每个关节的零点位置和运动范围。

方式2：使用本项目提供的scrit/so100_control.py进行校准

想法

如果 LLM + skills = 具身智能 ？