Skill authoring patterns
The sequences and habits that make skills reliable and reusable: pick, place, lids, contact, known start poses, failing early, and credentials.
Authoring a skill covers the files and the signature. This page covers how to write the body so the skill works on every run and keeps working when the cell changes. The starter project's move_plate and shaker_lid skills follow every pattern here.
Geometry comes from anchors
A skill reads where to go from anchors on objects, never from coordinates in code:
grasp = anchor(plate_id, "grasp_short") # where the tool goes, with its grasp width
seat = anchor(dest_id, "top_center") # where the plate's bottom_center landsWhen an object moves in the world, or someone re-teaches an anchor, the skill follows with no code change. If an arm cannot reach an anchor, move the object in the world or teach a better anchor; do not add offsets in the skill. Grasp widths and standoffs come from the anchor too (grasp.width, grasp.preapproach()).
Fail before the arm moves
Resolve every object and every anchor at the top of the skill. A wrong name then raises before anything moves, not halfway through with a plate in the gripper:
plate_id, source_id, dest_id = resolve(plate), resolve(source), resolve(destination)
grasp = anchor(plate_id, "grasp_short")
dest = anchor(dest_id, destination_anchor) # a wrong anchor name fails hereValidate other inputs the same way and raise with a message that says what is wrong. Never return {"success": False} to signal failure: only an exception fails the step.
Pick
Approach through free space, make only the last centimetres a slow straight line, and declare the contact:
set_gripper(ARM, OPEN_M) # open before the approach
move_arm(ARM, grasp.preapproach(HOVER_M)) # free move to above the grasp
with contact(ARM, plate_id, source_id): # opened in free space
move_arm(ARM, grasp, straight_line=True, tcp_speed=SLOW) # straight in, slowly
set_gripper(ARM, grasp.width) # close to the anchor's width
attach(ARM, plate_id, snap_anchor="grasp_short") # record it held at that anchor
move_relative(ARM, (0.0, 0.0, HOVER_M), tcp_speed=LIFT) # straight upattach with snap_anchor records the object exactly at its grasp anchor on the tool, so the grip is the same on every pick.
Place
While the arm holds the plate, the tool-to-plate transform is fixed. Compute the tool pose that puts the plate's bottom_center on the seat, carry level, and set it down:
grip = get_tcp_pose(ARM).inverse() @ get_anchor_pose(plate_id, "bottom_center")
seat = dest.pose @ grip.inverse()
above = seat.translated((0.0, 0.0, HOVER_M), frame="world")
move_arm(ARM, above, keep_upright=True) # free carry, plate level
with contact(ARM, dest_id, plate_id):
move_arm(ARM, seat, straight_line=True, tcp_speed=SLOW)
release(ARM, width=OPEN_M, onto=(dest_id, destination_anchor),
settle=dest.pose, settle_anchor="bottom_center")
move_arm(ARM, above, straight_line=True, tcp_speed=LIFT, allow=contact(ARM, plate_id))
move_arm_js(ARM, HOME)release with onto records the plate seated on the destination, so the next skill and the planner find it there.
Retreat after letting go
After release the open fingers still touch the object. The retreat move must allow that contact, with allow=contact(arm, obj) or by staying inside the contact block. Without it, the move is refused before it starts.
Lids, doors and drawers
Use an anchor on the moving part and follow its arc with move_path and sweep_anchor_steps; the world model's joint follows the path. See the shaker_lid example on Paths, lids, and two arms. Read the start angle from get_articulation(obj) and return early when the part is already where it should be.
Start and end at known joint poses
Joint configurations such as a home or ready pose are properties of the cell, not of an object. Keep them as named constants with literal values (radians, joint 1 to joint 6) and move there with move_arm_js. End each skill at one, so the next skill starts clear and from a predictable place.
HOME = [-0.218, -0.663, -0.989, -0.031, 1.682, 4.491] # joint1..joint6, rad: the starter's right-arm homeWrite each constant out in full rather than aliasing one to another, so that editing one never silently changes another. Share them across skills in skills/utils.py (from utils import HOME).
World-frame and tool-frame offsets
move_relative(arm, (dx, dy, dz)) moves along the world axes: (0, 0, 0.05) is always 5 cm up. For a slide along an object's own axis, use frame="tool", or derive the direction from anchors:
import numpy
out = grasp.preapproach().xyz - grasp.pose.xyz # the grasp's approach axis, backwards
out = out / numpy.linalg.norm(out)
move_relative(ARM, tuple(0.03 * out), tcp_speed=SLOW)Speeds
Use speed (a fraction of the joint-speed limit) for free moves and tcp_speed (m/s) for straight lines. Name them as constants (SLOW, LIFT) so they are tuned in one place.
One arm, one job
Name the arm a skill uses as a constant (ARM = "right"). When two arms must work at the same time, use run_parallel with one function per arm; outside it, a move of one arm holds the other still.
Simulator and real rig
Guard only the steps with no simulated counterpart (an instrument read, a Slack message you do not want from a test run) with is_sim_mode(). Motion, the gripper and the world model behave the same in both.
Credentials
- Never write a token in a skill or pass one as a workflow input. Store it in Secrets and use
api_request(..., auth_secret="NAME")orget_secret("NAME"). - Never log, return or send a secret value, and never put one in a URL.
api_requestdoes not raise. Checkresult["success"]and raise when the step should fail.
Checklist
- Folder,
skill_idand function name are identical, lowercase with underscores. - Every input has a type and, where sensible, a default; each is described in
Args:. - Objects and anchors are resolved before the first move.
- Positions, widths and standoffs come from anchors.
- Every intended contact is declared, including the retreat after
release. -
attachfollows every grasp andreleaseevery let-go. - The skill ends at a known joint pose.
- Failures raise.
- No tokens in code, inputs or URLs.
- The skill runs in the simulator (
zeon run <skill>) before it runs on a rig.
Updated 9 days ago