Skill Marketplace

The Ameba-Claw Skill Marketplace is the official open repository hosted on GitHub, providing downloadable Skill packages that extend device functionality on demand. marketplace_search and marketplace_downloader are built-in Skills that ship with the Ameba-Claw firmware and are independent of the Skills available in the marketplace repository itself — the former handles searching the marketplace index, and the latter handles downloading and installing Skills from it. Together, these two Skills allow the Agent to complete the full workflow — searching, compatibility checking, downloading, and activating — entirely through conversation, without any manual filesystem operations.

Marketplace repository: https://github.com/Ameba-AIoT/ameba-claw-skills-marketplace

Note

Both Skills access github.com via the http_request Capability. Before use, ensure that github.com has been added to the HTTP request allowlist in the device configuration; otherwise operations will fail with an allowlist error.

Searching the Marketplace

marketplace_search is a knowledge-type Skill. Once activated, the Agent fetches the marketplace index, filters it in context by keyword, tag, or category, and returns matching results — including the exact id, description, and tags — to the user. The id returned in search results can be used directly for installation.

Describe what you are looking for in conversation to trigger a search:

Find Skills related to temperature and humidity in the marketplace
Search for LCD game Skills in the marketplace
What sensor Skills are available in the marketplace?

Note

marketplace_search only searches Skills in the marketplace; it does not include Skills already built into the device. After displaying the results, the Agent will prompt the user to install using the exact id.

Downloading and Installing a Skill

marketplace_downloader is a script-type Skill that downloads a specified Skill from the marketplace and installs it into the vfs:/skills/ directory, then automatically activates it in the current session.

Name the Skill you want to install in conversation:

Install dht11_temp_humidity
Get a Snake game from the marketplace
Install the ws2812_led_strip Skill

After installation, the Skill appears under vfs:/skills/ alongside user-created Skills. It can be viewed and edited through the file management interface, or invoked directly through conversation.

Peripheral Compatibility Check

Before installing, marketplace_downloader reads the target Skill’s metadata to verify that its peripheral requirements match the current board:

1. The Agent fetches the target Skill’s metadata and retrieves its peripheral dependency list.

2. If any peripheral dependencies exist, the Agent automatically activates board_hardware_info and queries each required peripheral or device for availability.

3. If all checks pass, installation proceeds. If any peripheral is missing, installation stops and the Agent reports which hardware is absent and which boards support it.

For example, when installing a game Skill that requires a touchscreen and IMU, if the current board has no touchscreen, the Agent will report:

Installation failed: the current board is missing touch_i2c_gt911_st7701p and imu_i2c_bmi270.
Boards that support these peripherals: PKE8721FLM-VA4-N33-HMI-ST7701P.

Note

To force-install on a board that does not meet the peripheral requirements, explicitly tell the Agent to skip the compatibility check. Whether the Skill functions correctly after a forced install depends on the actual hardware connected.

Available Skill Categories

Marketplace Skills are organized into the following categories. The repository is continuously updated; refer to GitHub for the latest list.

Category	Description
sensor	Sensor reading Skills that interface with common sensor modules (e.g. temperature/humidity, ambient light) via GPIO or a bus, and return readings to the Agent for reasoning
control	Actuator control Skills, including servo angle driving and addressable RGB LED strip control for scenarios requiring precise timing output
app	Application Skills for boards with a display, such as NTP-synchronized clocks and alarm clock apps
game	Game Skills for boards with a touchscreen or buttons, covering both classic and original titles
network	Network information Skills that retrieve live data — weather, cryptocurrency prices, public IP geolocation — via HTTP with no additional hardware required

Note

Installation requires the exact id from the marketplace (letters, digits, underscores, and hyphens only). Do not guess the name from a description. If unsure, use marketplace_search to confirm the id before installing.

Submitting a Skill to the Marketplace

The Ameba-Claw Skill Marketplace is an open repository — contributions from developers are welcome. The submission process follows the standard GitHub Pull Request workflow.

Submission Workflow

1. Fork the ameba-claw-skills-marketplace repository and create a branch named skill/<skill_name>.

2. Create a directory with the Skill name at the repository root and place all required files according to the directory structure below.

3. Verify that all files meet the requirements and complete every item in the Pre-submission Checklist.

4. Open a Pull Request against the main repository with the title [skill] add <skill_name>.

Directory Structure

Each Skill must contain the following files:

<skill_name>/
├─ SKILL.md          # Documentation and metadata
├─ _metadata.json    # Machine-readable index
└─ scripts/          # Lua scripts (if applicable)
   └─ main.lua

Metadata Fields

The SKILL.md file must declare metadata as JSON enclosed in --- markers at the top of the file. Required fields are listed below:

Field	Type	Description
name	string	Skill name; must match the directory name exactly
description	string	Single English sentence, no more than 120 characters, no trailing period
author	string	Your name or GitHub username
metadata.category	array	One or more of: network, game, control, sensor, utility
metadata.tags	array	3–6 lowercase keywords
metadata.peripherals	array	Device IDs of required peripherals (as defined in the repository’s board.json); use an empty array [] if no peripherals are needed

Naming Conventions

• Directory names must be lowercase with underscores, for example dht11_temp_humidity.

• description must be written in English as a single declarative sentence.

• category values must be chosen from the enumerated list; new categories may not be introduced.

• Peripheral IDs in peripherals must match the definitions in the main repository’s board.json exactly.

Pre-submission Checklist

Verify the following before opening a Pull Request:

• Metadata JSON is syntactically valid; use your editor’s JSON validation or an online tool to check.

• description meets the length limit (≤ 120 characters) and is correctly formatted.

• peripherals list accurately reflects the Skill’s actual hardware requirements.

• Lua scripts have been tested on real hardware.

• A corresponding entry has been added to SKILLS_zh.md in the repository.