Authoring a skill
Create a skill, declare its inputs in the function signature, fail by raising, share code between skills, and run one skill on its own.
This page covers the anatomy of a skill and how the platform loads and calls it. The functions a skill calls are in the Skill API; the habits that make skills reusable are in Skill authoring patterns.
Create a skill
Inside a project's working tree:
zeon new skill plate_transfercreated skill plate_transfer
- skills/plate_transfer/metadata.yaml
- skills/plate_transfer/modules.py
- skills/plate_transfer/robotic_code.py
Edit skills/plate_transfer/robotic_code.py to get started.
The command looks for the project root by walking up from the current directory to the folder that holds .zeon/. It checks every file it is about to write first and stops with file already exists: ... if any is present, so it never leaves a half-created skill.
Name skills with lowercase letters, digits and underscores only.
zeon new skillalso accepts a hyphen, but the skill id inmetadata.yamlmust match^[a-z0-9_]+$, so a hyphenated skill fails to load.
The three files
modules.py imports the skill API:
"""Skill API v2 re-export for this skill (``execution.skill_api``; its ``__all__`` is the API)."""
from execution.skill_api import * # noqa: F401,F403robotic_code.py holds the function. The generated one:
from .modules import print_log
def plate_transfer():
"""plate_transfer: one line on what this skill does.
The skill's inputs are this function's parameters: give each a type and a default, or put it after ``*``
without a default to make it required. A world object is a ``SkillObject`` parameter
(``from protocol_schema import SkillObject``) with a default like ``{"object_ref": "<object id>"}``.
Document each input in an ``Args:`` section.
"""
print_log(runlog=True, runlog_type="step_start")
# The steps go here: move_arm, set_gripper, attach, release, seat, ... (execution.skill_api, re-exported by
# modules.py); import each name you use from .modules.
print_log("plate_transfer complete")
return {"success": True}metadata.yaml describes it. See The skill metadata file.
Three names must agree: the folder skills/<skill_id>/, the skill_id in metadata.yaml, and the function def <skill_id>(...) at the top level of robotic_code.py. The platform loads skills/<skill_id>/robotic_code.py and calls the function of that name; a file without it fails to load.
Import each API name you use from .modules. Import the standard library and other packages yourself (import math). Use only the skill API as documented in these pages; other exported names are not part of the supported surface.
Inputs come from the function signature
Each parameter of the function is an input of the skill. The platform reads the signature from the file on disk without importing it:
- Type comes from the annotation. With no annotation, it comes from the default value; with neither, the input is a string.
- Default comes from the default value. Only literal defaults (numbers, strings, lists, dicts,
True/False/None) are shown as defaults. - Required: a parameter without a default is required. Put required parameters after
*so the order of the others does not matter. - Description comes from the docstring's
Args:section, or fromparameter_descriptionsinmetadata.yaml, which wins.
| Annotation | Input type |
|---|---|
SkillObject | object (a world object) |
str | string |
bool | boolean |
int | int |
float | float |
list, List, tuple, Tuple, Sequence | array |
dict, Dict, Mapping | object |
Optional[X] and X | None count as X. Parameter names must be lowercase letters, digits and underscores.
from protocol_schema import SkillObject
from .modules import anchor, print_log, resolve
def plate_transfer(
plate: SkillObject = {"object_ref": "wellplate"},
destination: SkillObject = {"object_ref": "wellplate_stand_1"},
destination_anchor: str = "top_center",
*,
lift_m: float,
):
"""Move a plate onto a seat.
Args:
plate: The plate to move.
destination: What to set it on.
destination_anchor: The seat anchor on the destination.
lift_m: How far to lift the plate before the carry, in metres.
"""
plate_id = resolve(plate)
seat = anchor(destination, destination_anchor)
...World objects
A parameter annotated SkillObject takes a world object. A workflow node passes {"object_ref": "<instance id>"}; the skill then receives a SkillObject whose .id is the instance id. When the parameter is left to its default, the skill receives the default value itself, here the dict {"object_ref": "wellplate"}.
Pass object parameters through resolve() before using them. It accepts a SkillObject, an {"object_ref": ...} dict, an instance id or a display name, and returns the instance id. The motion and world functions that take an object accept all of these; get_world_state, set_world_state and localize_object_tags need the instance id.
A node that names an object the loaded world does not have fails before the skill runs, with the ids it could have meant.
Inputs a node supplies
- A required parameter the node does not supply fails the step before the skill runs.
- A node parameter that matches no parameter of the function fails the step, with the closest parameter name as a suggestion. A renamed parameter therefore fails visibly instead of silently falling back to its default.
Failing and returning
A skill fails only by raising. Every skill API function raises when it cannot do its job (a move that cannot be planned, an anchor that does not exist), so most skills need no error handling: let the exception propagate. Raise yourself when a check fails:
if lid not in ("open", "closed"):
raise ValueError(f"lid must be 'open' or 'closed', got {lid!r}")The return value is stored as the step's result. It does not decide success, and {"success": False} does not stop a workflow. The starter skills return {"success": True} by convention.
When a step fails, the error message is what the run shows. What happens next (the workflow's failure path, or the run failing) is covered in Running a workflow on real hardware and Authoring a workflow.
Checks before a skill loads
Before a skill is imported, its calls to skill API functions are checked against the real signatures. A keyword the function does not have, or too many positional arguments, refuses the load before anything moves:
Skill 'plate_transfer' calls the engine API incorrectly -- line 31: move_arm() has no parameter 'tcp_sped'. Did you mean 'tcp_speed'?
Edits are picked up on the next run: each run re-reads the skills folder from disk, including helper modules and new files, with no restart.
Sharing code between skills
The skills/ folder is on the import path while skills run, so:
- Another skill's function is importable by its folder name:
from move_plate.robotic_code import move_plate. - A shared module at the top of the folder, such as
skills/utils.py, is importable asfrom utils import HOME_LEFT.
Keep skill ids specific (pick_tip, not pick): each skill folder is a top-level module name.
Simulation and real hardware
The same skill runs in the simulator and on a real rig. is_sim_mode() returns True when the skill acts on the simulated set. Use it only around steps that have no simulated counterpart, such as reading a physical instrument:
if is_sim_mode():
reading = 0.0
else:
reading = api_request(f"{base_url}/reading")["data"]Motion, the gripper, objects and anchors behave the same in both. Slack notifications have no simulator branch: on a machine with Slack configured they post from a simulated run too. See Pausing and operator prompts.
Running one skill
From the CLI, against your cloud instance's simulator:
zeon run move_plate -i plate=wellplate -i source=wellplate_stand_1 -i destination=wellplate_stand_2 -i destination_anchor=top_center-i key=value sets one input (the value is parsed as JSON when it parses); the keys are the skill's parameter names. An object input also takes a display name, or a type with one instance in the world. zeon run refuses an unknown key (with the closest parameter name), a missing parameter that has no default and a value of the wrong type before the run starts. --world <id> reloads a world first. In the app, the Skills Editor runs one skill with its inputs filled in a form.
Inputs are read from the file on disk: save before you expect a changed signature to show up.
Older skills
Projects created before the current skill API import execution.execution_functions in modules.py. That surface still loads, but its pose-based motion functions (move_arm, move_relative and the recorded-motion functions) raise NotImplementedError. Port such a skill to execution.skill_api: change the import in modules.py, then rewrite its moves with the functions on Arm motion and the gripper.
Read next
Updated 1 day ago