Skill 系统

Skill 是 Ameba-Claw 的扩展机制。每个 Skill 是存储在文件系统中的一个目录包，包含元数据文件 SKILL.md 和可选的 Lua 执行脚本。激活 Skill 后，Agent 可以获得新能力——向 LLM 注入上下文、解锁 Capability 组，或在芯片上直接运行 Lua 代码。

什么是 Skill

Skill 分为两种类型：

含脚本型 Skill ：包含 scripts/main.lua，激活后可通过 lua_run Capability 执行该脚本，将运行结果返回给 LLM 继续推理。示例：usb_file、camera_capture。
纯知识型 Skill ：只包含 SKILL.md，无执行脚本。激活后将文档内容注入 LLM 上下文，并解锁对应的 Capability 组 cap_groups。示例：board_hardware_info、builtin_lua_modules、skill_authoring。

存储位置：

内置 Skill ：存储在只读固件分区 rolfs:/skills/<名称>/，随 OTA 升级自动更新。
用户创建的 Skill ：存储在可写 Flash vfs:/skills/<名称>/，断电后保留，可通过文件管理界面编辑。

内置 Skill

Ameba-Claw 预装了五个内置 Skill，覆盖最常见的使用场景。

Skill 名称	类型	激活方式	用途	典型使用场景
`board_hardware_info`	纯知识型	对话中说"查询开发板信息"	激活后解锁 `board` Capability 组；为 LLM 提供可用引脚和外设列表	编写任何硬件控制脚本前先激活，避免引用错误的引脚号
`builtin_lua_modules`	纯知识型	对话中说"查询 Lua 模块 API"	提供内置 Lua 模块的 API 索引，LLM 可按需读取各模块文档	让 Agent 编写 Lua 脚本时激活，确保 API 调用正确
`usb_file`	含脚本型	对话中要求操作 U 盘文件，如"读取 U 盘里的文件"	对 FAT32 格式的 USB 存储器进行文件读写、列目录、删除操作	插入 USB 存储器后需要读取或写入文件时
`camera_capture`	含脚本型	对话中说"拍照"或"用摄像头拍一张照片"	通过 USB UVC 摄像头拍照；激活后解锁 `audio_stream` Capability 组	接入 USB UVC 摄像头后需要拍照时；建议先激活 `board_hardware_info` 确认 UVC 接口可用
`skill_authoring`	纯知识型	由 Agent 自动激活	为 LLM 提供创建新 Skill 的工作流指引，通过 `skill_save` Capability 写入脚本	Agent 需要创建新 Skill 时自动触发，无需手动激活

备注

纯知识型 Skill 无执行脚本 ：board_hardware_info、builtin_lua_modules、skill_authoring 均没有 scripts/main.lua，激活的作用是向 LLM 注入文档上下文或解锁特定 Capability 组，而非运行代码。AT+CLAW=skill,<名称> 命令只对含脚本型 Skill 有效，对纯知识型 Skill 不适用。

激活 Skill

大多数情况下，通过对话描述需求即可激活 Skill——Agent 会根据任务类型自动判断并激活所需的 Skill，无需手动指定。

示例：

说"帮我读取 U 盘里的配置文件" → Agent 自动激活 usb_file
说"查一下现在开发板有哪些引脚可用" → Agent 自动激活 board_hardware_info
说"帮我拍一张照" → Agent 自动激活 camera_capture

含脚本型 Skill 也可以通过 AT 命令直接运行，无需经过 Agent 对话：

AT+CLAW=skill,usb_file
AT+CLAW=skill,camera_capture
AT+CLAW=skill,<skill 名称>,<JSON 参数>

例如，指定引脚和闪烁次数：

AT+CLAW=skill,blink_led,{"pin":"PA_22","times":10}

让 Agent 编写新 Skill

你不需要会写 Lua 代码。只需用自然语言描述需求，Agent 会完成查询硬件信息、查阅 API、编写脚本并保存的全部工作。

以下示例展示完整的创建流程：

第一步：向 Agent 描述你的需求

在对话中发送：

帮我给 GPIO PA_22 添加呼吸灯效果

第二步：Agent 查询硬件信息

Agent 判断该任务涉及硬件引脚，自动激活 board_hardware_info Skill，确认当前开发板上 PA_22 引脚可用，并获取正确的引脚名称格式。

第三步：Agent 编写 Lua 脚本

Agent 调用 builtin_lua_modules Skill 查阅 gpio 模块 API，随后生成控制呼吸灯效果的 Lua 脚本。

第四步：Agent 保存为新 Skill

Agent 自动激活 skill_authoring （纯知识型 Skill，提供保存流程指引），再通过 skill_save Capability 将脚本写入 vfs:/skills/breathing_led/scripts/main.lua 并完成注册。

第五步：Agent 确认完成

Agent 回复类似：

已创建 Skill "breathing_led"。PA_22 引脚将以 1 秒为周期做呼吸灯效果。
你可以随时说"启动呼吸灯"来运行它。

此后，你可以直接通过对话触发该 Skill，也可以通过 AT 命令运行：

AT+CLAW=skill,breathing_led

管理已安装的 Skill

通过 Web 控制台查看和编辑

登录 Web 管理界面后，进入 文件管理 页面，浏览 vfs:/skills/ 目录可查看所有已安装的 Skill。每个 Skill 对应一个子目录，主脚本位于该子目录的 scripts/main.lua。直接在文件管理界面中编辑 main.lua 即可修改 Skill 逻辑，保存后立即生效，无需重启。

列出已安装的 Skill

调用 skill_list Capability 查看所有已安装的 Skill：

AT+CLAW=cap,skill_list

列出 Skill 文件目录

使用文件系统命令列出 Skill 目录内容：

AT+CLAW=fs,list,vfs:/skills/

删除 Skill

通过 AT 命令删除指定 Skill：

AT+CLAW=fs,delete,vfs:/skills/blink_led

也可以在文件管理界面中删除对应的 Skill 目录。删除后 Agent 将无法再调用该 Skill。

SKILL.md 格式简述

每个 Skill 目录下都必须包含 SKILL.md 文件，用于描述 Skill 的元数据和功能说明。文件格式为 YAML 前言加 Markdown 正文：

---
name: blink_led
description: 控制 GPIO 引脚做 LED 闪烁
manage_mode: editable
cap_groups: []
---

## 用途

本 Skill 控制指定 GPIO 引脚以指定次数闪烁。

## 参数

- pin: 引脚名称，如 "PA_22"
- times: 闪烁次数，默认 6

主要字段说明：

name ：Skill 唯一标识符，与目录名一致
description ：功能简述，显示在 Skill 列表中
manage_mode ：readonly 表示内置 Skill，editable 表示用户可编辑
cap_groups ：激活该 Skill 时自动解锁的 Capability 组列表；纯知识型 Skill 通过此字段向 LLM 开放额外工具