The skill metadata file
skills/
skills/<skill_id>/metadata.yaml says what a skill is. What it does is in robotic_code.py, and its inputs come from the function signature there, not from this file.
Example
The file zeon new skill plate_transfer writes:
# skill API v2 (execution.skill_api)
skill_id: plate_transfer
version: "1.0.0"
description: ""
# parameters are derived from the plate_transfer() signature in robotic_code.py
tags: []The starter's move_plate:
# skill API v2 (execution.skill_api)
skill_id: move_plate
version: "1.0.0"
description: "Right arm: pick a plate up by its grasp_short anchor and set its bottom_center on a destination anchor (a stand's top_center, a shaker slot)."
# parameters are derived from the move_plate() signature in robotic_code.py
tags:
- plate
- pick
- placeFields
| Field | Type | Required | Description |
|---|---|---|---|
skill_id | string | yes | The skill's id. Must match ^[a-z0-9_]+$, and should equal the folder name and the function name. |
version | string | yes | X.Y.Z (digits). Quote it so YAML reads it as a string. |
description | string | yes | One-line summary. May be empty. |
tags | list of strings | no | Free-form labels. |
parameter_descriptions | map or list | no | Description text for parameters, overriding the docstring. See below. |
parameters | list | no | Used only when the signature cannot be read. See below. |
preconditions | map | no | Not checked when the skill runs. See below. |
postconditions | map | no | Written into the run's internal state when the skill succeeds. See below. |
safety_rules | list of strings | no | Free text stored with the skill. Nothing at run time reads it. |
high_risk | boolean | no | Default false. Stored with the skill. Nothing at run time reads it. |
Other keys are ignored when the skill loads. world_state_prime, an older field that the Skills Editor still reads, is not covered here; leave it out of new skills.
Parameters
A skill's parameters are read from the signature of def <skill_id>(...) in robotic_code.py: names, types, required or optional, and defaults. See Authoring a skill. The parameters list in this file is used only when that function cannot be read (the file does not parse, or has no top-level function named after the skill). Change the signature, not this file, to change a skill's inputs.
Description text
Each parameter's description comes from, in order:
parameter_descriptionsin this file,- the function docstring's
Args:entry, - the parameter name.
parameter_descriptions:
destination_anchor: "The seat anchor on the destination: top_center on a stand, slot_1 on the shaker."The list form [{name: destination_anchor, description: "..."}] also works. A malformed block is ignored, never a load failure.
The fallback list
If you write the fallback list, each entry has name (^[a-z0-9_]+$), type (string, float, int, boolean, object or array), description, required (default true) and default. A required parameter may not have a default, and a default must match the type; either mistake fails the load.
Preconditions and postconditions
Both are flat maps of key to value.
preconditionsare not checked when the skill runs. Check what the skill needs in Python and raise.postconditionsare written into the workflow run's internal state when the skill succeeds.- A skill's
preconditionsmay not contain its ownskill_idas a key; that fails the load.
Most skills leave both out.
When a skill does not load
A skill whose metadata.yaml does not parse, or does not validate, is left out of the project's skill catalog: it cannot be run, in a workflow or on its own. Validation checks the skill_id pattern, the version format, the fallback parameter list and the precondition rule above.
Two skills cannot share a skill_id: the second one found is skipped.
If skill_id differs from the folder name, the value in the file is used, but the skill's code is looked up under skills/<skill_id>/, so the skill does not run. Keep the folder name, the skill_id and the function name identical.
If a skill's inputs are not what you expect, check that the function name matches skill_id, that robotic_code.py parses, and that the function is at the top level of the file, not inside a class or another function.
Updated 9 days ago