AGENT SKILL

sdf

SDFormat/SDF 模型和世界创作、验证和模拟器切换。用于“.sdf”文件、SDFormat XML、模型、世界、链接、关节、姿势、框架、惯性、视觉/碰撞几何、网格 URI、传感器、灯光、物理、插件、包括、Gazebo、静态 SDF 审查或模拟器特定的元数据。请勿用于有符号距离场几何。

License 许可
MIT
最近更新
2026-09-29
Stars
★ 0
Forks
0

01 前言 Front Matter

name
sdf
description
SDFormat/SDF 模型和世界创作、验证和模拟器切换。用于“.sdf”文件、SDFormat XML、模型、世界、链接、关节、姿势、框架、惯性、视觉/碰撞几何、网格 URI、传感器、灯光、物理、插件、包括、Gazebo、静态 SDF 审查或模拟器特定的元数据。请勿用于有符号距离场几何。

02 资源文件 102

03 SKILL.md 正文

SDF

Provenance: maintained in earthtojake/text-to-cad. Use the installed local skill files as the runtime source of truth; the repository link is only for provenance and release review.

Use 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.

This skill is for SDFormat, not signed-distance-field geometry.

The .sdf file is the source of truth: author and edit the XML directly. There is no gen_sdf() contract.

Core rules

  1. Author .sdf XML directly and validate every created or modified file with scripts/validate before reporting completion.
  2. Identify the target consumer before editing: Gazebo/libsdformat version, another simulator, visualization-only tooling, model package, or world handoff.
  3. Decide document kind: model-level SDF, world-level SDF, or model-in-world. Prefer model-level SDF for reusable robot/object exports.
  4. Use SI units unless the target explicitly requires otherwise: meters, kilograms, seconds, radians.
  5. Prefer version="1.12" for new outputs unless the target consumer constrains the version.
  6. 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.
  7. 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.
  8. 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).
  9. When the robot already has a URDF, derive the SDF from it instead of re-authoring geometry; see references/interoperability.md.
  10. Regenerate upstream geometry, mesh, robot-description, render, topology, or package assets with their owning workflows before editing SDF that references them.
  11. After authoring, run available checks: bundled validation, optional gz sdf --check, simulator load, joint motion, and plugin/sensor startup.
  12. Report assumptions, skipped checks, unresolved resource paths, and target-specific compatibility risks.

Scope

Use 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.

CAD Viewer Handoff

After completing SDF work that creates or modifies a .sdf, you must ALWAYS hand the explicit file path to $cad-viewer when that skill is installed. $cad-viewer must start CAD Viewer if it is not already running and return link(s) to the relevant created or updated file(s); if $cad-viewer is unavailable or startup fails, report that instead of silently omitting the handoff.

Workflow

  1. Locate the target .sdf and its consumers.
  2. Read or create the design ledger comment block.
  3. Read references/frame-semantics.md before editing any <pose>, <frame>, joint axis, relative_to, expressed_in, nested scope, sensor frame, or plugin frame.
  4. Author the XML directly, following the worked examples in references/examples.md.
  5. Validate the explicit target with scripts/validate; treat bundled validation as a guardrail, not simulator proof.
  6. Run target-consumer smoke tests when available (references/smoke-tests.md).
  7. Hand the file to $cad-viewer. Static rendering does not execute SDF plugins or read file-authored motion metadata.
  8. Report checks run, checks skipped, and assumptions.

Commands

Run with the project or workspace Python environment. Treat python in examples as an interpreter placeholder; if bare python is unavailable, substitute python3, a project virtualenv interpreter, or the configured interpreter path. The validator uses only the Python standard library.

python scripts/validate path/to/model.sdf
python scripts/validate path/to/a.sdf path/to/b.sdf
python scripts/validate path/to/model.sdf --strict

The validator checks document shape, name scopes, pose/frame graphs, joints, geometry, mesh URIs, inertials, sensors, and plugins, and prints per-file findings plus a summary. --strict treats warnings as failures. It exits nonzero if any target fails.

Optional external checking:

python scripts/validate path/to/model.sdf --gz-check auto
python scripts/validate path/to/model.sdf --gz-check required
python scripts/validate path/to/model.sdf --gz-check never

gz sdf --check is optional target-consumer validation. It should be reported as skipped when unavailable unless explicitly required.

Required report shape

When finishing an SDF task, include a compact report:

Validated: path/to/model.sdf
Checks run:
- bundled SDF validation: passed
- gz sdf --check: skipped, gz not installed
- simulator load: skipped, target simulator unavailable
- viewer handoff: `$cad-viewer` link returned
Assumptions:
- Assumed mesh units are meters.
- Assumed lidar frame is coincident with lidar_link.
Risks:
- Camera plugin filename was not verified in the target simulator environment.

Snapshot Tool

scripts/snapshot renders the robot to a PNG still or an orbit GIF, using the same shared CLI and headless browser runtime every rendering skill uses — so a snapshot matches what the CAD Viewer shows.

python scripts/snapshot --input path/to/robot.sdf --output review.png
python scripts/snapshot --input path/to/robot.sdf --output turntable.gif --mode orbit

It accepts .sdf only. Pose the robot with the job field "jointValues" (joint name to degrees, defaulting to the rest pose) rather than --params, which is STEP-only; robots are authored in metres and are framed on the robot scene scale automatically.

Theme settings live under one --theme, mirroring the viewer's Theme tab. The default theme is snapshot — Workbench Light with the ground grid, origin axis and shadows removed, because in a still image those read as geometry. There is no --display: display settings (mode, clip, exploded, edges) are CAD topology settings, and a robot carries none.

Link meshes are resolved relative to the description, so they must be present: an unhydrated Git LFS pointer fails as "No link mesh loaded for robot". Run git lfs checkout <mesh dir> first.

Use python scripts/snapshot --help for the complete current command interface.

References

  • SDF workflow: references/sdf-workflow.md
  • Worked examples (golden skeletons): references/examples.md
  • LLM guardrails: references/llm-guardrails.md
  • Design ledger: references/design-ledger.md
  • Frame semantics: references/frame-semantics.md
  • Validation scope: references/validation.md
  • Smoke tests: references/smoke-tests.md
  • Interoperability notes (URDF-derived SDF, meshes, Gazebo): references/interoperability.md

04 同仓库更多 Skills

zzz2929
zzz2929/skills-zh-CN

vercel-react-view-transitions

使用 React 的视图转换 API(`<ViewTransition>` 组件、`addTransitionType` 和 CSS 视图转换伪元素)实现流畅、原生感觉的动画的指南。每当用户想要添加页面转换、为路线更改设置动画、创建共享元素动画、为组件的进入/退出设置动画、为列表重新排序设置动画、实现定向(向前/向后)导航动画或在 Next.js 中集成视图转换时,请使用此技能。当用户提及视图转换、startViewTransition、ViewTransition、转换类型或询问有关在 React 中的 UI 状态之间设置动画而无需第三方动画库时也可使用。

★ 0
zzz2929
zzz2929/skills-zh-CN

vercel-react-native-skills

React Native和Expo构建高性能移动应用程序的最佳实践。在构建React Native组件、优化列表性能、实现动画或使用本机模块时使用。涉及React Native、Expo、移动性能或本机平台API的任务的触发器。

★ 0
zzz2929
zzz2929/skills-zh-CN

vercel-react-best-practices

Vercel Engineering的React和Next.js性能优化指南。在编写、审查或重构React/Next.js代码时,应使用此技能,以确保最佳性能模式。涉及React组件、Next.js页面、数据获取、捆绑优化或性能改进的任务的触发器。

★ 0
zzz2929
zzz2929/skills-zh-CN

vercel-composition-patterns

可扩展的React组合模式。在重构具有布尔属性增殖的组件、构建灵活的组件库或设计可重用的API时使用。涉及复合组件、渲染道具、上下文提供者或组件架构的任务的触发器。包括React 19 API变更。

★ 0
zzz2929
zzz2929/skills-zh-CN

ui-styling

使用 shadcn/ui 组件(基于 Radix UI + Tailwind 构建)、Tailwind CSS 实用优先样式和基于画布的视觉设计创建美观、可访问的用户界面。在构建用户界面、实现设计系统、创建响应式布局、添加可访问组件(对话框、下拉菜单、表单、表格)、自定义主题和颜色、实现深色模式、生成视觉设计和海报或跨应用程序建立一致的样式模式时使用。

★ 0
zzz2929
zzz2929/skills-zh-CN

design

“综合设计技能:品牌标识、设计标记、UI 样式、徽标生成(55 种样式、Gemini 或 Atlas Cloud AI)、企业形象程序(50 个可交付成果、CIP 模型)、HTML 演示文稿(Chart.js)、横幅设计(22 种样式、社交/广告/网页/打印)、图标设计(15 种样式、SVG、Gemini 3.1 Pro)、社交照片(HTML→屏幕截图、多平台)。操作:设计徽标、创建 CIP、生成模型、构建幻灯片、设计横幅、生成图标、创建社交照片、社交媒体图像、品牌标识、设计系统:Facebook、Twitter、LinkedIn、YouTube、Instagram、Pinterest、TikTok、Threads、Google Ads。”

★ 0