Agent Skills

Agent Skills#

Agent skills help coding agents follow Isaac Lab workflows for installation, training, debugging, migration, and contributions. They are Markdown instructions in the repository. Codex and Claude discover them automatically (see Discovery); skills/README.md lists the available skills.

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#

File

Developer skills

User skills

Purpose

SKILL.md

Required

Required

Main agent-facing workflow and references.

evaluations.md

Optional

Required

Representative prompts, expected behavior, and pass/fail criteria.

reference.md

Optional

Recommended

Longer background that should not live in SKILL.md.

examples.md

Recommended

Recommended

Concrete examples of the workflow.

scripts/

Optional

Optional

Deterministic helpers with explicit run-or-read instructions.

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. In each authoritative documentation page, add an RST source comment naming the associated skills and their paths. Keep this maintenance guidance out of the rendered page. When the documented behavior changes, update the skills in the same change.

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, catalog completeness, 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.

Structural validation does not establish whether a skill improves agent behavior. When changing a workflow, exercise representative requests and inspect the resulting actions and artifacts. Include cases that should not activate the skill. Compare correctness, completion, unnecessary scope changes, tool calls, uncached input and output tokens, and validation time. Keep cached input separate from uncached input, and compare similar tasks before claiming an efficiency improvement.

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.