Skill 应用市场

Ameba-Claw Skill 应用市场是托管于 GitHub 的官方开放仓库，为设备提供可按需安装的 Skill 扩展包。 marketplace_search 和 marketplace_downloader 是随 Ameba-Claw 固件预置的内置 Skill，与市场仓库中的 Skill 相互独立；前者负责搜索市场索引，后者负责从市场下载并安装 Skill。借助这两个 Skill，Agent 可以在对话中直接完成搜索、兼容性检查、下载与激活的完整流程，无需手动操作文件系统。

市场仓库地址：https://github.com/Ameba-AIoT/ameba-claw-skills-marketplace 。

备注

两个 Skill 均需通过 http_request Capability 访问 github.com。使用前请确认设备配置中已将 github.com 加入 HTTP 请求白名单，否则操作会失败并提示 allowlist 错误。

搜索市场 Skill

marketplace_search 是一个纯知识型 Skill，激活后 Agent 会从市场拉取 Skill 索引，在上下文中按关键字、标签或类别进行过滤，并将匹配结果（包含精确 id、描述、标签等信息）返回给用户。搜索结果中的 id 可直接用于后续安装。

在对话中描述需求即可触发搜索：

帮我找一下市场里有没有温湿度相关的 Skill
帮我搜一下 LCD 游戏类的 Skill
市场里有哪些传感器 Skill？

备注

marketplace_search 仅搜索市场中的 Skill，不包含设备上已内置的 Skill。搜索结果展示后，Agent 会提示用户使用精确 id 进行安装。

下载并安装 Skill

marketplace_downloader 是一个含脚本型 Skill，负责将市场中的 Skill 下载并安装到设备的 vfs:/skills/ 目录，安装完成后自动在当前会话中激活。

在对话中说明要安装的 Skill 即可：

帮我安装 dht11_temp_humidity
从市场装一个贪吃蛇游戏
安装 ws2812_led_strip 这个 Skill

安装后，该 Skill 会出现在 vfs:/skills/ 目录下，与用户自建的 Skill 统一管理，可通过文件管理界面查看和编辑，也可通过对话直接调用。

外设兼容性检查

安装前，marketplace_downloader 会先读取目标 Skill 的元数据，确认其外设依赖是否与当前开发板匹配：

1. Agent 拉取目标 Skill 的元数据，获取其外设依赖列表。

2. 若存在外设依赖，Agent 自动激活 board_hardware_info，逐一查询依赖的外设或设备是否可用。

3. 全部通过后执行安装；若有任一外设缺失，安装停止，Agent 会告知用户缺少哪些硬件以及哪些开发板支持这些外设。

例如，安装一个依赖触摸屏和 IMU 的游戏 Skill 时，若当前开发板不带触摸屏，Agent 会提示：

安装失败：当前开发板缺少 touch_i2c_gt911_st7701p 和 imu_i2c_bmi270。
支持这些外设的开发板：PKE8721FLM-VA4-N33-HMI-ST7701P。

备注

如需在不满足外设要求的开发板上强制安装，可明确告知 Agent 跳过兼容性检查。强制安装后，Skill 能否正常运行取决于硬件实际连接情况。

可用 Skill 概览

市场中的 Skill 按功能分为以下类别，内容持续扩充，以 GitHub 仓库为准：

类别	说明
sensor	传感器读取类，通过 GPIO 或总线接入常见传感器模块（如温湿度、环境光等），读取数据后返回给 Agent 推理
control	执行器控制类，包括舵机角度驱动、可寻址 RGB LED 灯带控制等需要精确时序输出的场景
app	应用类，面向带显示屏的开发板，提供含 NTP 时间同步的时钟、闹钟等实用应用
game	游戏类，面向带触摸屏或按键的开发板，涵盖多款经典及原创游戏
network	网络信息查询类，通过 HTTP 接口获取实时天气、加密货币价格、公网 IP 地理位置等数据，无需额外硬件

备注

安装时必须使用市场中的精确 id （仅允许字母、数字、下划线和连字符），不可凭描述猜测名称。如不确定，请先通过 marketplace_search 确认 id 再执行安装。

提交 Skill 到市场

Ameba-Claw Skill 应用市场是开放仓库，欢迎开发者贡献 Skill。提交流程基于标准的 GitHub Pull Request 工作流。

提交流程

1. Fork 仓库 ameba-claw-skills-marketplace，在自己的 Fork 上新建分支，分支命名格式为 skill/<skill_name>。

2. 在仓库根目录下创建以 Skill 名称命名的目录，按照下方目录结构放置文件。

3. 确认所有文件符合规范，完成 提交前检查清单 中的各项检查。

4. 向主仓库发起 Pull Request，标题格式为 [skill] add <skill_name>。

目录结构

每个 Skill 须包含以下文件：

<skill_name>/
├─ SKILL.md          # 文档与元数据
├─ _metadata.json    # 机器可读索引
└─ scripts/          # Lua 脚本（如有）
   └─ main.lua

元数据字段

SKILL.md 文件头部须以 --- 包裹的 JSON 格式声明元数据，必填字段如下：

字段	类型	说明
name	string	Skill 名称，须与目录名完全一致
description	string	英文单句描述，不超过 120 个字符，末尾不加句号
author	string	作者姓名或 GitHub 用户名
metadata.category	array	功能类别，从 network、game、control、sensor、utility 中选取一项或多项
metadata.tags	array	3–6 个全小写关键字
metadata.peripherals	array	所依赖外设的设备 ID（取自仓库中的 board.json），无外设依赖时填写空数组 []

命名规范

• 目录名使用全小写字母与下划线组合，例如 dht11_temp_humidity。

• description 须为英文，表述为单个陈述句。

• category 只能从枚举列表中选取，不得自行添加新类别。

• peripherals 中的设备 ID 须与主仓库 board.json 中的定义严格匹配。

提交前检查清单

在发起 Pull Request 前，请确认以下各项：

• 元数据 JSON 语法正确，可使用编辑器的 JSON 校验功能或在线工具验证。

• description 满足长度限制（≤120 字符）且格式正确。

• peripherals 列表与 Skill 实际硬件需求一致。

• Lua 脚本已在真实硬件上完成测试。

• 已在仓库的 SKILLS_zh.md 文件中添加对应条目。