Skill System

What Is a Skill

A Skill is a self-contained extension package stored in the filesystem. Each Skill occupies a directory and must contain a SKILL.md metadata file; a scripts/main.lua execution script is optional. Skills come in two types:

Script-type Skill: contains scripts/main.lua. The Agent invokes it at reasoning time via the lua_run Capability, which executes the script and returns its output to the LLM for further reasoning. Examples: usb_file, camera_capture.
Knowledge-type Skill: only SKILL.md, no execution script. Activating it injects the Skill’s documentation as context for the LLM and unlocks the corresponding Capability group (cap_groups). Examples: board_hardware_info, builtin_lua_modules, skill_authoring.

Built-in Skills reside in the read-only firmware partition at rolfs:/skills/<name>/ and are updated atomically with OTA. User-created Skills reside in the writable partition at vfs:/skills/<name>/ and persist across reboots.

Built-in Skills

Ameba-Claw ships with five built-in Skills covering the most common use cases.

Skill Name	Type	How to Activate	Purpose	Typical Use Case
`board_hardware_info`	Knowledge	Say “query board info” in chat	Unlocks the `board` Capability group; gives the LLM the board’s pin and peripheral list	Must activate before writing any hardware script to avoid incorrect pin numbers
`builtin_lua_modules`	Knowledge	Say “query Lua module API” in chat	Provides a Lua module API index; LLM reads individual module docs on demand	Activate when asking the Agent to write Lua scripts
`usb_file`	Script	Ask to work with USB-drive files	Read, write, list, and delete files on a FAT32 USB drive	When a USB drive is inserted and you need file access
`camera_capture`	Script	Say “take a photo” or “capture an image”	Captures a photo via USB UVC camera; unlocks the `audio_stream` Capability group	When a USB UVC camera is attached; activate `board_hardware_info` first to confirm UVC support
`skill_authoring`	Knowledge	Activated automatically by the Agent	Gives the LLM a workflow guide for creating new Skills via the `skill_save` Capability	Auto-triggered when the Agent creates a new Skill — no manual activation needed

Note

Knowledge-type Skills (board_hardware_info, builtin_lua_modules, skill_authoring) have no execution script. Activating them injects documentation context or unlocks Capability groups — they do not run any code. AT+CLAW=skill,<name> is only meaningful for script-type Skills.

Always activate board_hardware_info before writing any script that touches hardware pins. Available pins differ between boards.

Script-type Skills can be run directly with an AT command:

AT+CLAW=skill,usb_file
AT+CLAW=skill,camera_capture

Ask the Agent to Write a Skill

You do not need Lua experience. Describe what you want in natural language; the Agent handles the rest.

Step 1 — Describe your requirement

Send a message in chat:

Add a breathing-LED effect to GPIO PA_22

Step 2 — Agent queries hardware information

The Agent activates the board_hardware_info Skill (knowledge-type) to confirm PA_22 is available on the current board and to get the correct pin-name format.

Step 3 — Agent writes the Lua script

The Agent activates builtin_lua_modules to look up the gpio module API, then generates a Lua script implementing the breathing-LED effect.

Step 4 — Agent saves the script as a new Skill

The Agent activates skill_authoring (knowledge-type, provides the save workflow guide) and then calls the skill_save Capability to write the script to vfs:/skills/breathing_led/scripts/main.lua and register it.

Step 5 — Agent confirms completion

Skill "breathing_led" has been created. PA_22 will pulse with a 1-second
breathing cycle. You can say "start breathing LED" at any time to run it.

After that, trigger it through conversation or directly:

AT+CLAW=skill,breathing_led

Tip

Just describe the effect you want. For example: “Read the temperature sensor every 30 seconds and send me the value” or “Play a chime when a GPIO signal arrives.” The Agent queries hardware info, looks up APIs, writes the script, and saves it.

Managing Installed Skills

View and Edit via the Web Console

Log in to the web management interface, open File Manager, and browse vfs:/skills/. Each Skill is a subdirectory; the main script is at scripts/main.lua. Edit main.lua directly — changes take effect immediately without restarting.

List All Skills

AT+CLAW=cap,skill_list

Uninstall a Skill

Delete the Skill’s directory in the file manager, or use:

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

Run a Skill Directly

AT+CLAW=skill,<skill_name>
AT+CLAW=skill,<skill_name>,{"key":"value"}

Browse the Filesystem

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

SKILL.md Format

Every Skill directory must contain a SKILL.md with a YAML frontmatter block:

---
name: my_skill
description: "What this skill does — shown to the LLM"
compatibility: RTL8721F
metadata:
  cap_groups: board lua     # space-separated; groups unlocked on activation
  manage_mode: editable     # editable (user) or readonly (built-in)
---
# Skill documentation body
Full documentation for the LLM goes here...

The name field must match the directory name and use only [a-z0-9_-]. Built-in Skills use manage_mode: readonly. User-created Skills default to manage_mode: editable.