Skip to content

Add an example

Workflow

Goal
a new example in examples/shelf/ with a checked Steel preset and a preview, following the collection's conventions.
Use when
adding a scene to the collection, or giving an existing example a Steel preset it does not have yet.
Done when
shelf check EXAMPLE --every reports works for every filled table, the example renders and looks right, and PRESETS.md is regenerated.

Any coding agent, or a person, can follow this workflow from agents/workflows/add-an-example/README.md. Tools that discover skill folders also find it assteel-add-an-example.

Inputs. The scene (a Newton example script, or a new one). Read examples/AGENTS.md for the presets.toml format, the conversion steps and the rules (never write status = "works" by hand; never loosen an example’s test).

Steps

  1. Put the example under examples/shelf/<NN_section>/<example>/ as example.py plus presets.toml, converted as examples/AGENTS.md describes (settings out of code into presets, self.preset = presets.load(__file__)). Fill the tables of solvers the code already supports with the values it used; leave others untested.
  2. For Steel: run-trial at the new [steel] table, then autotune-settings from defaults if the table is new. Copy the result into [steel] with a comment per setting saying why.
  3. check-example with --every.
  4. render-and-grade for this example and visual-review.
  5. Add the [gallery] table and render the preview: uv run python -m shelf thumbs EXAMPLE --force.

Deliverables

The example folder, its checked presets.toml, the regenerated PRESETS.md, and the gallery for it.

Steps it uses

  • Run a trial runs one example's whole episode with Steel at given settings and lists what is wrong, in fix order.
  • Autotune settings repeats trials until no fix is left, then keeps only cheaper settings that stay healthy.
  • Check an example runs an example's own test headless with a preset and records the result in presets.toml.
  • Render and grade renders examples with their Steel presets on one or more GPUs, records stability metrics, and grades each scene ok, suspect, unstable or failed.
  • Visual review looks at frames across each episode and records a grade and a note per scene the metrics may have misjudged.

Source: agents/workflows/add-an-example/README.md, the copy agents read.