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 lands

When 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 here

Validate 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 up

attach 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 home

Write 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") or get_secret("NAME").
  • Never log, return or send a secret value, and never put one in a URL.
  • api_request does not raise. Check result["success"] and raise when the step should fail.

Checklist

  • Folder, skill_id and 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.
  • attach follows every grasp and release every 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.

Did this page help you?