Agent workflows
The agents/ folder of the repository holds the procedures we use to work on Steel scenes: tune a scene, debug an instability, validate a solver change, add an example, port a project from PhysX. Each is plain Markdown with exact commands, pass and fail criteria and the evidence to keep. Any coding agent can follow them, and so can a person; nothing in them depends on one agent product.
What are you trying to do?
Section titled “What are you trying to do?”| You want to | Workflow | Done when |
|---|---|---|
| make one Steel scene stable or faster, or pick its preset | Tune a scene | the settings you ship pass shelf check, cover the whole task with zero dropped rows, and their frames look right. |
| find out why a Steel scene explodes, jitters, sinks, slips or overflows | Debug instability | the cause is named with evidence, the fix passes the scene's gates over the whole task, or the report says why no setting can fix it. |
| know whether a Newton or Steel change breaks or slows any example | Validate a solver change | both revisions were rendered and checked on the same examples, every grade change is explained, and speed changes on the flagged scenes are measured. |
| add a scene to the collection, or give an example a Steel preset | Add an example | shelf check EXAMPLE --every reports works for every filled table, the example renders and looks right, and PRESETS.md is regenerated. |
| move a PhysX project to Steel | Port from PhysX | the upgraded-PhysX gate and the Steel parity check pass or every difference is explained, randomized and performance comparisons are matched and free of capacity loss, and a fresh checkout runs both backends. |
How they are built
Section titled “How they are built”Workflows 5
agents/workflows/A goal: when to use it, inputs, steps in order, decision points, exit criteria, deliverables.
Steps 11
agents/steps/One procedure: inputs, exact commands, pass and fail criteria, outputs. Calls tools, never a workflow.
Tools code
examples/shelf list, play, bench, tune, check, trial, autotune, advise; the render audit. All the logic lives here.
A workflow puts steps in order and says what to do at each decision point; a step is one procedure you can run on its own; the tools hold all the logic, so a workflow never asks anyone to re-derive a rule in prose. Every README opens with three summary lines (Goal, Use when, Done when for a workflow; Does, Use in, Passes when for a step), and commands run from the repository root unless a step says cd examples. Every step is on the steps page.
How agents find them
Section titled “How agents find them”AGENTS.md. The repository root’sAGENTS.mdpoints atagents/README.md, the catalog with the table above. Coding agents that readAGENTS.mdstart there;examples/AGENTS.mdhas the rules for changing an example or a preset.- By name. Point an agent, or yourself, at a workflow’s README: “follow
agents/workflows/tune-a-scene/README.mdforcrane_wrecking_ball”. - Adapters (optional). Some tools discover procedures in skill folders.
python agents/make_adapters.pywrites one pointer per workflow,.claude/skills/steel-<workflow>/SKILL.md, holding the workflow’s summary as front matter and one link to its README. The README stays the only copy of the procedure;--checkfails when a pointer is stale, so never edit one by hand.
What they rest on
Section titled “What they rest on”-
The tools. From
examples/:uv run python -m shelf trialruns one example’s whole episode with Steel and lists what is wrong in fix order,shelf autotunerepeats trials until no fix is left and then keeps cheaper settings that stay healthy,shelf advisere-reads a recorded trial, andscripts/render_audit/renders and grades examples with their Steel presets.Terminal window cd examplesuv run python -m shelf trial crane_wrecking_ball --out outputs/crane_t0uv run python -m shelf autotune crane_wrecking_ball --start defaults --out outputs/crane_tune -
The guides. The Steel tuning guide in the repository, with the measurements behind each rule and a validation of
shelf autotuneagainst hand-tuned presets, and on this site Tuning, Troubleshooting and Porting from PhysX. -
The examples’ own checks.
shelf checkis the acceptance for a preset; the advisor’s health and the render grades are screens in front of it.
To write a new workflow or step, see Add a workflow.
Steel docs and tutorials are licensed under Apache-2.0. Third-party notices. "Skild", "Skild AI" and the Skild logo are trademarks of Skild AI and are not licensed under Apache-2.0.