Agent Skills

Isaac Lab agent skills are repository-owned instructions that help coding agents follow Isaac Lab workflows. They are markdown guidance assets, not runtime Python packages. The library covers installing, building environments, training, debugging, migrating, and contributing. Codex and Claude discover the skills automatically from a repository checkout (see Discovery_). The full catalog is in skills/README.md.

Skill categories

Skills typically fall into two groups: ones you invoke and ones the agent applies automatically. The groups are not exclusive. The audience directory (user/ or developer/) says who a skill is for.

Typically user-invoked skills Ask for these by task or by name, for example /isaaclab-installing-isaac-lab in Claude Code. They cover work you start yourself: installing Isaac Lab, creating and converting environments, training and debugging RL, choosing backends and presets, preparing assets for Newton, migrating from Isaac Gym or Isaac Lab 2.x, and troubleshooting setup. They live under skills/user/. Some maintainer tasks under skills/developer/ are also run on request: isaaclab-auditing-an-issue and isaaclab-triaging-issue-backlog.

Typically agent-automated skills The agent usually loads these on its own when a task matches the skill description, following AGENTS.md. They cover contribution conventions: coding style, test audits, changelog fragments, environment docs synchronization, and PR preparation. They live under skills/developer/.

User skills also trigger automatically when a request matches their description, so naming a skill is optional. Name it when you want to be sure it is used.

Layout

Skills live under the repository-level skills/ directory:

skills/
├── developer/
│   └── <skill-name>/
│       ├── SKILL.md
│       └── examples.md
└── user/
    └── <skill-name>/
        ├── SKILL.md
        ├── evaluations.md
        ├── reference.md       # optional, recommended for longer guidance
        └── examples.md        # optional, recommended for concrete workflows

Skill files

Discovery

Codex and Claude discover the repository skills automatically through project-native aliases:

.agents/skills/<frontmatter-name>  -> skills/<audience>/<slug>
.claude/skills                     -> .agents/skills

Codex scans .agents/skills and Claude scans .claude/skills. The aliases use the frontmatter name so both agents expose the same stable identifier. They resolve to the canonical directories under skills/, keeping one maintained copy of each skill and preserving repository-relative references. Do not flatten-copy the skills into a global agent skill directory.

Agents without native skill discovery should use skills/README.md as the catalog. Select a skill by matching the user’s request against the description field in each SKILL.md frontmatter, then read only that skill and its directly linked files. Directory slugs are canonical file locations for humans and reviewers; the frontmatter name is the stable identifier to use when one skill routes to another.

Skill contract

Every skill must include a SKILL.md file with frontmatter:

name: isaaclab-example-skill
description: Performs a specific Isaac Lab workflow. Use when the user mentions the workflow or related trigger terms.
audience: user
status: stable
owners:
  - isaaclab-maintainers

The required frontmatter fields are:

Frontmatter intentionally uses a small YAML subset: single-line scalar fields and the owners list. Do not use block scalars such as | or > in SKILL.md frontmatter; keep long details in the markdown body or a linked reference file.

name Unique lowercase identifier using letters, numbers, and hyphens. Prefer an isaaclab- prefix and avoid generic names such as helper, utils, or tools. The identifier must match the native alias under .agents/skills/.

description Third-person discovery text. Include what the skill does and when an agent should use it.

Good example:

description: Applies Isaac Lab coding style, API design, docstring, type-hint, lazy export, and contribution conventions. Use when writing or reviewing Isaac Lab Python code, public APIs, config classes, module exports, or documentation strings.

Bad example:

description: Helps with tasks.

audience Either developer or user. This must match the directory under skills/.

status One of experimental, stable, or deprecated.

Use experimental for new or incomplete guidance that still needs real usage. Promote a skill to stable only after it has maintained references, validation guidance, and review from the owning area. Use deprecated when a workflow is replaced or no longer recommended; deprecated skills must point to the replacement workflow or migration path.

owners One or more maintainer groups or owners responsible for the skill.

Required SKILL.md sections are:

• When To Use
• Workflow
• Validation
• Maintenance
• References

User-facing skills must also include an evaluations.md file with at least three representative scenarios. Each scenario should include a sample prompt or task, expected behavior, and known failure modes or pass/fail criteria.

Authoring guidelines

These guidelines are adapted from Anthropic’s Skill authoring best practices and tailored to Isaac Lab’s documentation and contribution workflow.

Keep SKILL.md concise. Treat context as shared budget and assume agents already understand general programming concepts. Put only the task-critical workflow in SKILL.md.

Use progressive disclosure. Link directly from SKILL.md to one-level files such as reference.md, examples.md, or evaluations.md. Avoid chains where SKILL.md links to a file that links to the actual guidance.

Use a contents section for longer references. Reference files over 100 lines should start with # Contents or ## Contents so agents can navigate them when reading partially.

Do not include credentials, private content copied from another system, generated logs, hardware-specific benchmark dumps, or large vendored documentation. If that information is useful, summarize the workflow and link to the maintained source instead.

Set the right degree of freedom:

• Use high-freedom guidance for reviews and design work.
• Use medium-freedom templates when Isaac Lab has a preferred pattern.
• Use low-freedom exact commands or scripts for fragile workflows such as validation.

Prefer one clear default before listing alternatives. If an escape hatch is needed, state when to use it.

Avoid time-sensitive wording. For migrations, use Current Workflow and Old Patterns sections instead of date-based instructions.

Use consistent Isaac Lab terminology throughout a skill, such as manager-based environments, event terms, articulation config, and changelog fragment.

Keeping skills synchronized

Skills should not become parallel documentation. The source of truth is the Isaac Lab documentation under docs/source/ and the maintained source/examples under source/ and scripts/.

Each skill must include a Maintenance section that names the authoritative files to review when code changes. When a skill needs documentation-level content, update the official docs first and link to them from the skill.

Keep the link bidirectional. When a documentation page under docs/source/ is the source of truth for a skill, add a .. seealso:: admonition near the top of that page that names the skill and links back to it. This reminds documentation authors to update the associated skill in the same change, so the two never drift apart. Treat a missing back-link as a review issue whenever a skill’s Maintenance section names a documentation page.

Use these rules during review:

• Reject large copied API tables or standalone install guides when official docs already cover the topic.
• Prefer links to docs, source files, and maintained examples over duplicated snippets.
• Keep only agent-specific value in the skill: routing, task sequencing, validation loops, search terms, and known decision points.
• If a skill uncovers a missing migration note or troubleshooting entry, add that note to docs/source/ rather than expanding the skill.
• For simulation, asset, sensor, or randomization workflows, state whether the guidance is backend-neutral or specific to PhysX, Newton, or a renderer/visualizer backend. Link to the multi-backend docs and source implementations instead of copying backend tables into the skill.
• Run the skill validator after every skill change.

Validation workflow

Validate skills locally with:

uv run --no-project python tools/skills/cli.py check

The validator checks frontmatter, required sections, unique names, audience/path consistency, link validity, reference depth, portable paths, native Codex and Claude aliases, required user evaluations, minimum evaluation scenario counts, and per-scenario evaluation details such as sample queries, expected behavior, and known failure modes or pass/fail criteria.

Run the validator tests with:

uv run --no-project --with pytest python -m pytest tools/skills/

The skills CI gate runs only when a pull request changes files under skills/, tools/skills/, or the skills workflow. This keeps unrelated Isaac Lab PRs from being blocked by skill validation while still checking validator changes.

Review policy

Developer skills require maintainer approval from the owning area because they affect contributor workflows.

User skills require maintained references, a validation path, documentation alignment, and at least three evaluation scenarios.

Reviewers should reject skills that duplicate general knowledge instead of encoding Isaac Lab-specific workflow. Deprecated skills must include migration guidance and a replacement skill when one exists.