{"id":26876,"plugin_id":"plugins_6ac09476ef008191a35887b22b0d048a","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-06T00:02:41.602Z","digest":"7f50e53eac75aec976d88cfa8d09ed2fdb3fd78cfc2bfd9b660a53a792602583","against":null,"payload":{"description":"SDFormat/SDF model and world authoring, validation, and simulator handoff. Use for `.sdf` files, SDFormat XML, models, worlds, links, joints, poses, frames, inertials, visual/collision geometry, mesh URIs, sensors, lights, physics, plugins, includes, Gazebo, static SDF review, or simulator-specific metadata. Do not use for signed-distance-field geometry. Open and visually review existing SDF files in CAD Viewer.","included_files":[{"relative_path":"LICENSE","size_in_bytes":1074},{"relative_path":"agents/openai.yaml","size_in_bytes":296},{"relative_path":"references/design-ledger.md","size_in_bytes":4189},{"relative_path":"references/examples.md","size_in_bytes":4405},{"relative_path":"references/frame-semantics.md","size_in_bytes":3637},{"relative_path":"references/interoperability.md","size_in_bytes":3611},{"relative_path":"references/llm-guardrails.md","size_in_bytes":4534},{"relative_path":"references/sdf-workflow.md","size_in_bytes":4302},{"relative_path":"references/smoke-tests.md","size_in_bytes":3371},{"relative_path":"references/validation.md","size_in_bytes":7841},{"relative_path":"requirements.txt","size_in_bytes":25}],"name":"sdf","skill_md_contents":"---\nname: sdf\ndescription: SDFormat/SDF model and world authoring, validation, and simulator handoff. Use for `.sdf` files, SDFormat XML, models, worlds, links, joints, poses, frames, inertials, visual/collision geometry, mesh URIs, sensors, lights, physics, plugins, includes, Gazebo, static SDF review, or simulator-specific metadata. Do not use for signed-distance-field geometry. Open and visually review existing SDF files in CAD Viewer.\nlicense: MIT\n---\n\n# SDF\n\nProvenance: maintained in [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad).\nUse the installed local skill files as the runtime source of truth; the\nrepository link is only for provenance and release review.\n\nUse this skill when the deliverable is an SDFormat document. SDFormat describes simulator and world behavior: models, worlds, frames, poses, links, joints, inertials, visuals, collisions, sensors, lights, physics, plugins, includes, and simulator metadata.\n\nThis skill is for **SDFormat**, not signed-distance-field geometry.\n\nThe `.sdf` file is the source of truth: author and edit the XML directly. There is no `gen_sdf()` contract.\n\n## Setup\n\nThis skill's commands are thin entrypoints over the `cadgen` distribution, which\ncarries the Python build runtime and the JavaScript it executes. Install it once:\n\n```bash\npython -m pip install -r requirements.txt\n```\n\nSnapshots additionally need a browser, which pip cannot supply:\n\n```bash\npython -m playwright install chromium\n```\n\n## Core rules\n\n1. Author `.sdf` XML directly and validate every created or modified file with `cadgen sdf validate` before reporting completion.\n2. Identify the target consumer before editing: Gazebo/libsdformat version, another simulator, visualization-only tooling, model package, or world handoff.\n3. Decide document kind: model-level SDF, world-level SDF, or model-in-world. Prefer model-level SDF for reusable robot/object exports.\n4. Use SI units unless the target explicitly requires otherwise: meters, kilograms, seconds, radians.\n5. Prefer `version=\"1.12\"` for new outputs unless the target consumer constrains the version.\n6. Establish the design ledger before writing poses, frames, joint axes, mesh scales, inertials, sensors, or plugins, and keep it as a comment block at the top of the `.sdf`. Use `references/design-ledger.md` and `references/llm-guardrails.md`.\n7. Write `relative_to` / `expressed_in` explicitly on every nontrivial pose and axis. Implicit frame defaults are the top SDF failure mode. See `references/frame-semantics.md`.\n8. Do not infer spatial transforms from visual impression alone. Derive poses, axes, scale, mass, inertia, and frame names from upstream source data, drawings, simulator documentation, measured values, or explicit assumptions. Never freehand computed numbers — use formulas or a throwaway helper script (inertia tensors, unit conversions).\n9. When the robot already has a URDF, derive the SDF from it instead of re-authoring geometry; see `references/interoperability.md`.\n10. Regenerate upstream geometry, mesh, robot-description, render, topology, or package assets with their owning workflows before editing SDF that references them.\n11. After authoring, run available checks: bundled validation (which runs `gz sdf --check` itself whenever `gz` is on PATH), simulator load, joint motion, and plugin/sensor startup.\n12. Report assumptions, skipped checks, unresolved resource paths, and target-specific compatibility risks.\n\n## Scope\n\nUse this skill for SDFormat outputs. Do not use it for signed-distance-field modeling, raw geometry generation, planning semantics, or to paper over incorrect upstream robot/source data unless the task is explicitly simulator-only.\n\n## Show the model\n\nShow the user each file you create or change, and any they ask to see. Snapshots and\nvalidation don't replace this.\n\n- If your tools include `cad_show` (your host may prefix it), use it, and follow its\n  description for when to call it again. `cad_view` reads what the user selected;\n  `cad_screenshot` shows you what they see. Neither is a review of your own work.\n- Otherwise run the CAD Viewer from the models directory (usually `models/`, not an\n  artifact's output folder):\n\n  ```bash\n  cd /absolute/path/to/model-workspace && cadgen viewer --host 127.0.0.1 --json --detach\n  ```\n\n  `--detach` returns once the viewer answers requests and leaves it running in the\n  background: always pass it, since a foreground viewer never exits (and piping its\n  output through `tail` can hide the URL for good). It starts or reuses the viewer.\n  Read `url` from its one JSON line (never guess the port); for each file under that\n  directory return `url?file=<URL-encoded relative path>`, or `url` alone to review the\n  directory. If it fails to launch, say so.\n\nReview placement, resources and joints. The viewer does not execute simulator\nplugins or validate dynamics; keep simulator checks separate.\n\n## Workflow\n\n1. Locate the target `.sdf` and its consumers.\n2. Read or create the design ledger comment block.\n3. Read `references/frame-semantics.md` before editing any `<pose>`, `<frame>`, joint axis, `relative_to`, `expressed_in`, nested scope, sensor frame, or plugin frame.\n4. Author the XML directly, following the worked examples in `references/examples.md`.\n5. Validate the explicit target with `cadgen sdf validate`; treat bundled validation as a guardrail, not simulator proof.\n6. Run target-consumer smoke tests when available (`references/smoke-tests.md`).\n7. Show the result ([Show the model](#show-the-model)). Static rendering does not execute SDF plugins or read file-authored motion metadata.\n8. Report checks run, checks skipped, and assumptions.\n\n## Commands\n\nRun `cadgen` from the Python environment this skill's `requirements.txt` was installed into (`python -m cadgen.cli <verb>` with that interpreter is the PATH-independent equivalent). `cadgen doctor <skill-dir>` verifies the installed cadgen matches this skill's pin — docs drift silently on a mismatched install. Validation itself needs nothing beyond the Python standard library; only snapshots need the browser. Use `cadgen <verb> --help` for the complete current interface.\n\n```bash\ncadgen sdf validate path/to/model.sdf\ncadgen sdf validate path/to/model.sdf --strict\ncadgen sdf validate path/to/model.sdf --json\ncadgen sdf snapshot path/to/model.sdf review.png\n```\n\nThe validator checks document shape, name scopes, pose/frame graphs, joints, geometry, mesh URIs, inertials, sensors, and plugins, and prints its findings plus a summary. One run validates ONE file: `--strict` treats warnings as failures and `--json` prints one line of `{\"ok\", \"path\", \"issues\": [{\"severity\", \"code\", \"message\", \"element\", \"hint\"}], \"summary\"}`, where `element` is the XML path. It exits nonzero if the target fails.\n\nExternal checking is on by default:\n\n```bash\ncadgen sdf validate path/to/model.sdf --gz-check required\ncadgen sdf validate path/to/model.sdf --gz-check never\n```\n\n`gz sdf --check` is target-consumer validation. `--gz-check auto` is the default: it runs when `gz` is on PATH, reporting `gz_check_passed` or the tool's own output as the error `gz_check_failed`, and otherwise notes `info: gz_check_unavailable` and carries on. An absent optional tool says nothing about the file, so it never fails a clean document and `--strict` does not change that. `--gz-check required` makes the tool mandatory — a missing `gz` is then an error — and `--gz-check never` skips it outright.\n\n## Required report shape\n\nWhen finishing an SDF task, include a compact report:\n\n```text\nValidated: path/to/model.sdf\nChecks run:\n- bundled SDF validation: passed\n- gz sdf --check: skipped, gz not installed\n- simulator load: skipped, target simulator unavailable\n- viewer review: live link returned, or explicit launch failure\nAssumptions:\n- Assumed mesh units are meters.\n- Assumed lidar frame is coincident with lidar_link.\nRisks:\n- Camera plugin filename was not verified in the target simulator environment.\n```\n\n## Snapshot Tool\n\n`cadgen sdf snapshot` renders the robot to a PNG still, using the same shared\nCLI and headless browser runtime every rendering skill uses — so a snapshot matches what\nthe CAD Viewer shows.\n\n```bash\ncadgen sdf snapshot path/to/robot.sdf review.png\n```\n\nIt accepts `.sdf` only (a format door, same `TARGET [OUT]` grammar as the rest). Pose the robot with `--joint-values` — `{joint: degrees}` JSON,\njoints you do not name staying at their defaults, where the CAD Viewer opens the robot (the\n`\"jointValues\"` job field is the same thing in a packet). The snapshot draws the robot with the\nviewer's own scene, so it shows what the viewer shows, and a link mesh that cannot be loaded\nfails it rather than leaving the link out. Robots are authored in metres and are framed on the\nrobot scene scale automatically.\n\nA normal snapshot uses the Solid preset and Light appearance; omitted groups inherit preset defaults.\nPass `--display render` for the shared photographic scene. Inline display JSON and\nJSON files use grouped settings such as `lighting`, `background`, and `floor`;\n`appearance` is `light` (default) or `dark`. Projection and focal length belong\nin `display.camera`. Top-level `--camera` and `--joint-values` remain active in every display\nmode. The display modes are `solid` and `render`: `edges`, `clip`, `exploded`, the\n`xray`, `hidden-line` and `wireframe` modes and the `hidden`/`off` surface styles\ndescribe a STEP model's CAD edges, parts and solids, and are refused by name here.\n\nLink meshes are resolved relative to the description, so they must be present: an\nunhydrated Git LFS pointer fails as \"No link mesh loaded for robot\". Run\n`git lfs checkout <mesh dir>` first.\n\nThe grammar is `cadgen sdf snapshot TARGET [OUT] [flags]`, the same one every\nformat door uses. Use `cadgen sdf snapshot --help` for the complete current\ninterface — the flags a robot cannot act on are absent from it, not refused by it.\n\n## References\n\n- SDF workflow: `references/sdf-workflow.md`\n- Worked examples (golden skeletons): `references/examples.md`\n- LLM guardrails: `references/llm-guardrails.md`\n- Design ledger: `references/design-ledger.md`\n- Frame semantics: `references/frame-semantics.md`\n- Validation scope: `references/validation.md`\n- Smoke tests: `references/smoke-tests.md`\n- Interoperability notes (URDF-derived SDF, meshes, Gazebo): `references/interoperability.md`\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}