The skill metadata file

skills//metadata.yaml: the skill's id, version, description and tags, how its parameters are derived, and what makes it fail to load.

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
  - place

Fields

FieldTypeRequiredDescription
skill_idstringyesThe skill's id. Must match ^[a-z0-9_]+$, and should equal the folder name and the function name.
versionstringyesX.Y.Z (digits). Quote it so YAML reads it as a string.
descriptionstringyesOne-line summary. May be empty.
tagslist of stringsnoFree-form labels.
parameter_descriptionsmap or listnoDescription text for parameters, overriding the docstring. See below.
parameterslistnoUsed only when the signature cannot be read. See below.
preconditionsmapnoNot checked when the skill runs. See below.
postconditionsmapnoWritten into the run's internal state when the skill succeeds. See below.
safety_ruleslist of stringsnoFree text stored with the skill. Nothing at run time reads it.
high_riskbooleannoDefault 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:

  1. parameter_descriptions in this file,
  2. the function docstring's Args: entry,
  3. 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.

  • preconditions are not checked when the skill runs. Check what the skill needs in Python and raise.
  • postconditions are written into the workflow run's internal state when the skill succeeds.
  • A skill's preconditions may not contain its own skill_id as 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.


Did this page help you?