Skills

A skill is one robot action, written as a Python function. Pick up a tube. Read a sensor. Move to a pose. Each skill lives in its own folder at skills/<id>/, and the folder name is the skill id. Workflows call skills by that id, so the id is the name the rest of the platform knows your action by.

Two files matter. metadata.yaml describes the skill: its skill_id, a semantic version in X.Y.Z form, a description, plus optional preconditions, postconditions, safety_rules, and tags. robotic_code.py is the implementation, and it holds a function whose name must equal the skill id. Most skills also carry a modules.py alongside these two. That file is optional and holds helper code for the skill: the loader picks it up when it is there, and nothing breaks when it is not.

Parameters come from the function signature

This is the one fact worth reading twice. A skill's parameters are derived from its Python function signature, not from the parameters list in metadata.yaml.

The catalog parses robotic_code.py statically, finds the def <skill_id>(...) function, and builds the parameter schema from the arguments it sees. Each argument becomes a parameter. Its type comes from the type annotation (str, int, float, bool, list, dict, and SkillObject for a world object). An argument with a default becomes optional and carries that default. An argument without one is required.

The practical consequence: change the signature and you change the skill's inputs. Add an argument and workflows can pass it. Rename one and any workflow binding the old name is now wired to nothing. metadata.yaml cannot add a parameter the function does not accept.

What a skill returns

The function returns a dictionary containing success. That key is how the executor knows whether the step worked, which is what edges marked on_success or on_failure read when deciding where the workflow goes next. Return any other keys you want alongside it.

Making one

Run zeon new skill my_skill inside a project. That writes skills/my_skill/metadata.yaml and skills/my_skill/robotic_code.py, with the function stub already named to match the id and returning {"success": True}. Open robotic_code.py and start there. Add modules.py yourself if the skill grows helper code.

Skill ids are validated: lowercase letters, digits, and underscores only. The same rule applies to parameter names.

Read next