From cc30c1baa0e6cd949e0db11a18f35deebeca1524 Mon Sep 17 00:00:00 2001 From: Kelly Guo Date: Sun, 24 May 2026 20:49:31 -0700 Subject: [PATCH 1/6] Adds skills for Isaac Lab --- .github/workflows/skills-check.yml | 40 +++ AGENTS.md | 9 + .../overview/developer-guide/agent_skills.rst | 182 ++++++++++ .../source/overview/developer-guide/index.rst | 1 + skills/README.md | 63 ++++ skills/developer/changelog-fragments/SKILL.md | 54 +++ .../developer/changelog-fragments/examples.md | 33 ++ skills/developer/coding-style/SKILL.md | 57 +++ skills/developer/coding-style/examples.md | 41 +++ skills/developer/pr-workflow/SKILL.md | 58 +++ skills/developer/pr-workflow/examples.md | 38 ++ .../user/domain-randomization-events/SKILL.md | 65 ++++ .../evaluations.md | 86 +++++ .../domain-randomization-events/examples.md | 73 ++++ .../domain-randomization-events/reference.md | 80 +++++ skills/user/migrate-2x-to-3x/SKILL.md | 54 +++ skills/user/migrate-2x-to-3x/evaluations.md | 53 +++ skills/user/migrate-2x-to-3x/examples.md | 41 +++ skills/user/migrate-2x-to-3x/reference.md | 36 ++ .../migrate-2x-to-3x/supplemental-checks.md | 38 ++ skills/user/migrate-from-isaac-gym/SKILL.md | 64 ++++ .../migrate-from-isaac-gym/evaluations.md | 71 ++++ .../user/migrate-from-isaac-gym/examples.md | 37 ++ .../user/migrate-from-isaac-gym/reference.md | 72 ++++ .../validation-rough-locomotion.md | 104 ++++++ skills/user/select-backends/SKILL.md | 57 +++ skills/user/select-backends/evaluations.md | 46 +++ skills/user/setup-troubleshooting/SKILL.md | 61 ++++ .../user/setup-troubleshooting/evaluations.md | 46 +++ skills/user/train-rl-agents/SKILL.md | 56 +++ skills/user/train-rl-agents/evaluations.md | 46 +++ skills/user/use-sensors-actuators/SKILL.md | 60 ++++ .../user/use-sensors-actuators/evaluations.md | 46 +++ tools/skills/cli.py | 340 ++++++++++++++++++ tools/skills/pyproject.toml | 11 + tools/skills/test/test_validate.py | 149 ++++++++ 36 files changed, 2368 insertions(+) create mode 100644 .github/workflows/skills-check.yml create mode 100644 docs/source/overview/developer-guide/agent_skills.rst create mode 100644 skills/README.md create mode 100644 skills/developer/changelog-fragments/SKILL.md create mode 100644 skills/developer/changelog-fragments/examples.md create mode 100644 skills/developer/coding-style/SKILL.md create mode 100644 skills/developer/coding-style/examples.md create mode 100644 skills/developer/pr-workflow/SKILL.md create mode 100644 skills/developer/pr-workflow/examples.md create mode 100644 skills/user/domain-randomization-events/SKILL.md create mode 100644 skills/user/domain-randomization-events/evaluations.md create mode 100644 skills/user/domain-randomization-events/examples.md create mode 100644 skills/user/domain-randomization-events/reference.md create mode 100644 skills/user/migrate-2x-to-3x/SKILL.md create mode 100644 skills/user/migrate-2x-to-3x/evaluations.md create mode 100644 skills/user/migrate-2x-to-3x/examples.md create mode 100644 skills/user/migrate-2x-to-3x/reference.md create mode 100644 skills/user/migrate-2x-to-3x/supplemental-checks.md create mode 100644 skills/user/migrate-from-isaac-gym/SKILL.md create mode 100644 skills/user/migrate-from-isaac-gym/evaluations.md create mode 100644 skills/user/migrate-from-isaac-gym/examples.md create mode 100644 skills/user/migrate-from-isaac-gym/reference.md create mode 100644 skills/user/migrate-from-isaac-gym/validation-rough-locomotion.md create mode 100644 skills/user/select-backends/SKILL.md create mode 100644 skills/user/select-backends/evaluations.md create mode 100644 skills/user/setup-troubleshooting/SKILL.md create mode 100644 skills/user/setup-troubleshooting/evaluations.md create mode 100644 skills/user/train-rl-agents/SKILL.md create mode 100644 skills/user/train-rl-agents/evaluations.md create mode 100644 skills/user/use-sensors-actuators/SKILL.md create mode 100644 skills/user/use-sensors-actuators/evaluations.md create mode 100644 tools/skills/cli.py create mode 100644 tools/skills/pyproject.toml create mode 100644 tools/skills/test/test_validate.py diff --git a/.github/workflows/skills-check.yml b/.github/workflows/skills-check.yml new file mode 100644 index 000000000000..5e08df540c1c --- /dev/null +++ b/.github/workflows/skills-check.yml @@ -0,0 +1,40 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +name: Skills Check + +on: + pull_request: + types: [opened, synchronize, reopened] + paths: + - "skills/**" + - "tools/skills/**" + - ".github/workflows/skills-check.yml" + workflow_dispatch: + +concurrency: + group: skills-check-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + check-skills: + name: Check skills + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6 + + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: "3.12" + + - name: Verify skills + run: python3 tools/skills/cli.py check + + - name: Compile skills validator + run: python3 -m py_compile tools/skills/cli.py tools/skills/test/test_validate.py diff --git a/AGENTS.md b/AGENTS.md index f331c3c10988..3bed29453c19 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,6 +87,15 @@ Proper workflow: **When reviewing code** (e.g. via a code-reviewer agent), always run `./isaaclab.sh -f` as part of the review to catch formatting or lint issues early. +## Agent skills + +- Repo-owned agent skills live under `skills/`. +- Developer workflow skills live under `skills/developer/`; user-facing skills live under `skills/user/`. +- Keep `SKILL.md` files concise and link to one-level reference files for longer details. +- Keep official docs and maintained source examples as the source of truth; skills should route agents through those references instead of duplicating them. +- Validate skills with `./isaaclab.sh -p tools/skills/cli.py check` before opening a PR that changes `skills/`. +- The CI skills gate runs only for PRs that modify `skills/`, `tools/skills/`, or the skills workflow. + ## Changelog - **Do not edit `CHANGELOG.rst` or `config/extension.toml` directly.** Each PR adds a fragment file under `source//changelog.d/`; the changelog and version are compiled by the nightly CI workflow. diff --git a/docs/source/overview/developer-guide/agent_skills.rst b/docs/source/overview/developer-guide/agent_skills.rst new file mode 100644 index 000000000000..6af30df4aaf9 --- /dev/null +++ b/docs/source/overview/developer-guide/agent_skills.rst @@ -0,0 +1,182 @@ +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. + +Skills live under the repository-level ``skills/`` directory: + +.. code-block:: text + + skills/ + ├── developer/ + │ └── / + │ ├── SKILL.md + │ └── examples.md + └── user/ + └── / + ├── SKILL.md + ├── evaluations.md + ├── reference.md # optional, recommended for longer guidance + └── examples.md # optional, recommended for concrete workflows + +Developer skills + Help contributors and maintainers follow Isaac Lab workflows such as PR preparation, changelog fragments, testing, and documentation rules. + +User skills + Ship with the repository as supported guidance for users building on top of Isaac Lab. Some user skills are intentionally router-only and may only need ``SKILL.md`` plus ``evaluations.md`` when the official docs and source examples already contain the details. + +Skill files +----------- + +.. list-table:: + :header-rows: 1 + :widths: 20 20 20 40 + + * - 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. + +Skill contract +-------------- + +Every skill must include a ``SKILL.md`` file with frontmatter: + +.. code-block:: yaml + + 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: + +``name`` + Unique lowercase identifier using letters, numbers, and hyphens. Prefer an ``isaaclab-`` prefix and avoid generic names such as ``helper``, ``utils``, or ``tools``. + +``description`` + Third-person discovery text. Include what the skill does and when an agent should use it. + + Good example: + + .. code-block:: yaml + + 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: + + .. code-block:: yaml + + 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. + +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: + +.. code-block:: bash + + ./isaaclab.sh -p tools/skills/cli.py check + +The validator checks frontmatter, required sections, unique names, audience/path consistency, link validity, reference depth, portable paths, 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: + +.. code-block:: bash + + ./isaaclab.sh -p -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. diff --git a/docs/source/overview/developer-guide/index.rst b/docs/source/overview/developer-guide/index.rst index 59f603fbfad2..d006f1f8663e 100644 --- a/docs/source/overview/developer-guide/index.rst +++ b/docs/source/overview/developer-guide/index.rst @@ -13,3 +13,4 @@ using VSCode. VS Code repo_structure development + agent_skills diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 000000000000..b02731efe342 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,63 @@ +# Isaac Lab Agent Skills + +Isaac Lab skills are repo-owned instructions that help agents follow project workflows and user-facing Isaac Lab patterns. They are guidance assets, not runtime Python packages. + +## Catalog + +Developer skills: + +- `developer/pr-workflow/`: prepare changes for review using Isaac Lab's PR, commit, changelog, and validation conventions. +- `developer/changelog-fragments/`: add and validate package changelog fragments. +- `developer/coding-style/`: apply Isaac Lab coding style, API design, docstring, type-hint, lazy export, and contribution conventions. + +User skills: + +- `user/migrate-from-isaac-gym/`: migrate Isaac Gym tasks, assets, and training workflows to Isaac Lab. +- `user/migrate-2x-to-3x/`: migrate Isaac Lab 2.x projects to Isaac Lab 3.0 using the official migration guide. +- `user/domain-randomization-events/`: implement domain randomization through Isaac Lab event terms. +- `user/build-environments/`: create direct and manager-based Isaac Lab environments from task requirements. +- `user/train-rl-agents/`: configure and run Isaac Lab reinforcement learning workflows. +- `user/use-sensors-actuators/`: add sensors, sensor observations, and actuator models to tasks. +- `user/select-backends/`: choose and validate PhysX, Newton, and backend-specific task presets. +- `user/setup-troubleshooting/`: route installation, verification, and setup issues to official docs and canonical commands. + +Planned user skills: + +- `user/import-robot-urdf-mjcf/` + +## Authoring Rules + +Every skill directory must contain a `SKILL.md` file with frontmatter: + +```yaml +name: isaaclab-example-skill +description: Does a specific Isaac Lab task. Use when the user mentions the task or related trigger terms. +audience: user +status: stable +owners: + - isaaclab-maintainers +``` + +Directory slugs are stable file paths for humans and reviewers. The frontmatter `name` is the agent discovery identifier and should be used when one skill routes to another. + +Required `SKILL.md` sections: + +- `When To Use` +- `Workflow` +- `Validation` +- `Maintenance` +- `References` + +User-facing skills must also link to `evaluations.md` with at least three representative scenarios. Each scenario must include a sample query, expected behavior, and known failure modes or pass/fail criteria. + +Keep skills concise. Use `SKILL.md` for the main workflow and link directly to one-level files such as `reference.md`, `examples.md`, or `evaluations.md` for details. Use forward-slash paths, avoid time-sensitive wording, and provide one recommended default before listing alternatives. + +Keep skills synchronized by making official docs and source code the source of truth. If a skill needs documentation-level details, update `docs/source/` or a maintained source example first, then link to it from the skill. The `Maintenance` section must name the authoritative files that should be reviewed when code changes. + +Skills should add agent-specific routing, sequencing, validation checks, and decision points. They should not vendor installation guides, API catalogs, generated logs, hardware benchmark reports, or large tutorial copies. + +Run the validator before submitting skill changes: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` diff --git a/skills/developer/changelog-fragments/SKILL.md b/skills/developer/changelog-fragments/SKILL.md new file mode 100644 index 000000000000..acd24f08b8a5 --- /dev/null +++ b/skills/developer/changelog-fragments/SKILL.md @@ -0,0 +1,54 @@ +--- +name: isaaclab-writing-changelog-fragments +description: Writes and validates Isaac Lab package changelog fragments using the repository fragment format and bump rules. Use when source package changes need release notes, migration guidance, or changelog validation. +audience: developer +status: stable +owners: + - isaaclab-maintainers +--- + +# Writing Changelog Fragments + +## When To Use + +Use this skill when a PR changes code under `source//` and needs a changelog fragment, or when reviewing fragment formatting. + +Do not use this skill for pure docs, CI, tools, or skills changes unless they also modify `source//`. + +## Workflow + +1. Identify each changed package under `source/`. +2. Add one fragment per touched package under `source//changelog.d/`. +3. Choose the suffix: + - `.rst` for patch changes. + - `.minor.rst` for minor changes. + - `.major.rst` for major changes. + - `.skip` for package changes that intentionally have no user-facing entry. +4. Place entries under `Added`, `Changed`, `Deprecated`, `Removed`, or `Fixed`. +5. Include migration guidance for `Deprecated`, `Changed`, and `Removed` entries. +6. Prefix breaking changes with `**Breaking:**`. + +## Validation + +Run the changelog gate: + +```bash +./isaaclab.sh -p tools/changelog/cli.py check develop +``` + +Then run the normal formatting gate: + +```bash +./isaaclab.sh -f +``` + +## Maintenance + +Keep this skill synchronized with `AGENTS.md`, `docs/source/refs/contributing.rst`, and `tools/changelog/cli.py`. If changelog policy changes, update those authoritative sources first and keep this skill focused on routing agents to the right workflow. + +## References + +- [Contributing guide](../../../docs/source/refs/contributing.rst) +- [Changelog tool](../../../tools/changelog/cli.py) +- [Integration examples](../../../tools/changelog/test/integration/README.md) +- [Examples](examples.md) diff --git a/skills/developer/changelog-fragments/examples.md b/skills/developer/changelog-fragments/examples.md new file mode 100644 index 000000000000..ece55bae6f83 --- /dev/null +++ b/skills/developer/changelog-fragments/examples.md @@ -0,0 +1,33 @@ +# Changelog Fragment Examples + +## Contents + +- Patch fragment +- Minor fragment +- Skip fragment + +## Patch Fragment + +Use `source/isaaclab/changelog.d/.rst` for a bug fix: + +```rst +Fixed +^^^^^ + +* Fixed contact sensor reset behavior when environments are partially reset. +``` + +## Minor Fragment + +Use `source/isaaclab/changelog.d/.minor.rst` for a new public feature: + +```rst +Added +^^^^^ + +* Added :class:`~isaaclab.sensors.ExampleSensor` for configurable example sensing. +``` + +## Skip Fragment + +Use `source/isaaclab/changelog.d/.skip` when a `source//` change is test-only and has no user-facing release note. diff --git a/skills/developer/coding-style/SKILL.md b/skills/developer/coding-style/SKILL.md new file mode 100644 index 000000000000..fc138a7b0ee1 --- /dev/null +++ b/skills/developer/coding-style/SKILL.md @@ -0,0 +1,57 @@ +--- +name: isaaclab-following-coding-style +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. +audience: developer +status: stable +owners: + - isaaclab-maintainers +--- + +# Following Coding Style + +## When To Use + +Use this skill when adding or reviewing Isaac Lab code, especially public APIs, config classes, package exports, docstrings, type hints, or files that may import simulator-dependent modules. + +Do not use this skill as a replacement for the contribution guide. Read the authoritative docs before making broad style decisions. + +## Workflow + +1. Read the `Coding Style` section of `docs/source/refs/contributing.rst`. +2. Check `AGENTS.md` for always-on Isaac Lab API, docstring, dependency, and tooling rules. +3. Keep the change aligned with local patterns in the touched package. +4. Use the documented file and class member ordering. +5. Avoid runtime circular imports with `TYPE_CHECKING`, resolvable strings, and lazy exports where the contribution guide calls for them. +6. Use modern, specific type hints and Google-style docstrings. +7. Keep public-facing docs and auto-generated API docs current when adding public symbols. +8. Run the formatting and lint feedback loop. + +## Validation + +Run formatting and lint checks: + +```bash +./isaaclab.sh -f +``` + +For focused tests, use: + +```bash +./isaaclab.sh -p -m pytest PATH_TO_TEST +``` + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `AGENTS.md`, `docs/source/refs/contributing.rst`, `docs/source/refs/snippets/code_skeleton.py`, and `.pre-commit-config.yaml`. If coding-style guidance changes, update those authoritative files first and keep this skill as a routing checklist. + +## References + +- [Contributing guide](../../../docs/source/refs/contributing.rst) +- [Code skeleton](../../../docs/source/refs/snippets/code_skeleton.py) +- [Examples](examples.md) diff --git a/skills/developer/coding-style/examples.md b/skills/developer/coding-style/examples.md new file mode 100644 index 000000000000..698d8257330a --- /dev/null +++ b/skills/developer/coding-style/examples.md @@ -0,0 +1,41 @@ +# Coding Style Examples + +## Contents + +- Public API change +- Package export change +- Config class with simulator-dependent implementation + +## Public API Change + +Input: adding a public method to an Isaac Lab class. + +Expected workflow: + +1. Check naming against `AGENTS.md`. +2. Use specific type hints and Google-style docstrings. +3. Add SI units in public docstrings for physical quantities. +4. Preserve deprecation policy for renamed or removed APIs. +5. Run `./isaaclab.sh -f` and focused tests. + +## Package Export Change + +Input: adding a public symbol to a package `__init__.py`. + +Expected workflow: + +1. Follow the lazy export pattern from the contribution guide. +2. Update the adjacent `.pyi` stub with explicit public exports. +3. Use relative imports for local submodules. +4. Confirm package import remains lightweight before simulator startup. + +## Config Class With Simulator-Dependent Implementation + +Input: a config class needs to refer to an implementation that imports simulator runtime modules. + +Expected workflow: + +1. Avoid eager runtime imports in the config module. +2. Use a resolvable string or `TYPE_CHECKING` guard as documented. +3. Keep the config constructable before `SimulationApp` launches. +4. Add tests or smoke checks for the resolved runtime path. diff --git a/skills/developer/pr-workflow/SKILL.md b/skills/developer/pr-workflow/SKILL.md new file mode 100644 index 000000000000..401465bc48d6 --- /dev/null +++ b/skills/developer/pr-workflow/SKILL.md @@ -0,0 +1,58 @@ +--- +name: isaaclab-preparing-pr-workflow +description: Prepares Isaac Lab changes for review using the repository PR checklist, validation commands, commit rules, and changelog policy. Use when opening a PR, finishing a branch, preparing a commit, or checking contribution readiness. +audience: developer +status: stable +owners: + - isaaclab-maintainers +--- + +# Preparing PR Workflow + +## When To Use + +Use this skill when preparing Isaac Lab changes for review, checking a branch before a PR, or helping a contributor understand final readiness steps. + +Do not use this skill to bypass repository checks or to push to `origin`. + +## Workflow + +1. Inspect the changed files and identify touched packages. +2. Confirm the branch is focused on one logical change. +3. Run targeted tests for the touched behavior. +4. Run formatting and lint checks with `./isaaclab.sh -f`. +5. Add package changelog fragments when `source//` code changes. +6. Check whether `CONTRIBUTORS.md` needs an update for a new contributor. +7. Draft a commit message in imperative mood with no AI attribution. +8. Use the PR checklist in `.github/PULL_REQUEST_TEMPLATE.md`. + +## Validation + +Run the feedback loop until checks pass: + +```bash +./isaaclab.sh -f +``` + +For targeted tests, use: + +```bash +./isaaclab.sh -p -m pytest PATH_TO_TEST +``` + +If skills changed, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `AGENTS.md`, `.github/PULL_REQUEST_TEMPLATE.md`, and `docs/source/refs/contributing.rst`. If a PR workflow rule changes, update the authoritative file first and keep this skill as a short routing checklist. + +## References + +- [PR template](../../../.github/PULL_REQUEST_TEMPLATE.md) +- [Contributing guide](../../../docs/source/refs/contributing.rst) +- [Changelog skill](../changelog-fragments/SKILL.md) +- [Examples](examples.md) diff --git a/skills/developer/pr-workflow/examples.md b/skills/developer/pr-workflow/examples.md new file mode 100644 index 000000000000..ede0b323b25e --- /dev/null +++ b/skills/developer/pr-workflow/examples.md @@ -0,0 +1,38 @@ +# PR Workflow Examples + +## Contents + +- Source package change +- Docs-only change +- Skill-only change + +## Source Package Change + +Input: a PR modifies `source/isaaclab/isaaclab/assets/`. + +Expected workflow: + +1. Run targeted tests for the changed asset behavior. +2. Add a fragment under `source/isaaclab/changelog.d/`. +3. Run `./isaaclab.sh -f`. +4. Fill the PR checklist with test results. + +## Docs-Only Change + +Input: a PR modifies `docs/source/overview/`. + +Expected workflow: + +1. Build or preview docs when the change affects rendering. +2. Run `./isaaclab.sh -f`. +3. Do not add a package changelog fragment unless `source//` changed. + +## Skill-Only Change + +Input: a PR modifies `skills/user/domain-randomization-events/SKILL.md`. + +Expected workflow: + +1. Run `./isaaclab.sh -p tools/skills/cli.py check`. +2. Confirm the skill has current references and evaluations. +3. Let the path-scoped skills CI gate validate the change on the PR. diff --git a/skills/user/domain-randomization-events/SKILL.md b/skills/user/domain-randomization-events/SKILL.md new file mode 100644 index 000000000000..a8cc0bd72916 --- /dev/null +++ b/skills/user/domain-randomization-events/SKILL.md @@ -0,0 +1,65 @@ +--- +name: isaaclab-randomizing-with-events +description: Implements Isaac Lab domain randomization with event terms in direct and manager-based workflows. Use when adding domain randomization, randomizing physics or observations, porting reset randomization, or configuring event-based variation. +audience: user +status: stable +owners: + - isaaclab-maintainers +--- + +# Randomizing With Events + +## When To Use + +Use this skill when a user wants to add domain randomization to an Isaac Lab task through event terms. + +Do not use this skill for unrelated curriculum, command sampling, or reward shaping unless those changes interact with randomization. + +## Workflow + +1. Identify what should vary: assets, physics properties, observations, initial state, external disturbances, or rendering. +2. Identify the task workflow: direct (`DirectRLEnv` or `DirectMARLEnv`) or manager-based. Both can use `EventManager` through an `events` config. +3. Identify the active target backend: PhysX, Newton, or both through `PresetCfg`. +4. Check whether the randomization function has backend-specific behavior or unsupported backends in `source/isaaclab/isaaclab/envs/mdp/events.py`. +5. Choose the event mode: + - Use prestartup events for USD-level properties that must be authored before simulation starts. + - Use startup events for one-time setup randomization after simulation starts. + - Use reset events for per-episode randomization. + - Use interval events for repeated disturbances during an episode. +6. Check timing limitations before editing. Some USD-stage or topology-level changes are prestartup-only and cannot be safely moved to reset or interval events. +7. Define event terms in the environment configuration. In direct workflows, assign the event config to the task config's `events` field. In manager-based workflows, assign it to the manager-based env config's `events` field. +8. Use backend-specific `PresetCfg` event configs when PhysX and Newton need different terms. +9. Scope each term to the correct scene entities. +10. Use one clear distribution and range for each randomized quantity. +11. Validate with a small number of environments and repeated resets on each backend. +12. Expand ranges only after the baseline randomized task is stable. + +## Validation + +Use the plan-validate-execute loop: + +1. List each randomized property, target entity, backend, event mode, distribution, range, and timing limitation. +2. Check the list against the environment config before editing. +3. Check CPU/GPU expectations in the implementation. Some PhysX paths use CPU tensors while Newton paths may operate on the environment device. +4. Run a small reset or rollout smoke test for every targeted backend. +5. Fix shape, device, backend, and entity-name errors before scaling. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `source/isaaclab/isaaclab/managers/event_manager.py`, `source/isaaclab/isaaclab/envs/direct_rl_env.py`, `source/isaaclab/isaaclab/envs/direct_marl_env.py`, the direct and manager-based environment tutorials, and the managers API docs. If event-term behavior or mode semantics change, update the official docs or examples first and keep this skill focused on selecting the right workflow. + +## References + +- [Reference](reference.md) +- [Examples](examples.md) +- [Evaluations](evaluations.md) +- [Event manager source](../../../source/isaaclab/isaaclab/managers/event_manager.py) +- [Direct workflow randomization tutorial](../../../docs/source/tutorials/03_envs/create_direct_rl_env.rst) +- [Manager-based event terms tutorial](../../../docs/source/tutorials/03_envs/create_manager_base_env.rst) +- [Managers API](../../../docs/source/api/lab/isaaclab.managers.rst) diff --git a/skills/user/domain-randomization-events/evaluations.md b/skills/user/domain-randomization-events/evaluations.md new file mode 100644 index 000000000000..6fe8cf2363aa --- /dev/null +++ b/skills/user/domain-randomization-events/evaluations.md @@ -0,0 +1,86 @@ +# Event Randomization Evaluations + +## Contents + +- Scenario 1: reset randomization +- Scenario 2: prestartup-only randomization +- Scenario 3: interval disturbance +- Scenario 4: PhysX and Newton material randomization +- Scenario 5: direct workflow events + +## Scenario 1: Reset Randomization + +Query: "Randomize initial joint positions every episode." + +Expected behavior: + +- Selects reset mode. +- Places randomization in event terms. +- Checks entity names, ranges, and reset behavior. + +Known failure modes: + +- Adds randomization to the reward function. +- Uses startup mode for per-episode behavior. + +## Scenario 2: Prestartup-Only Randomization + +Query: "Randomize authored USD properties for each run, but I also want them to change every reset." + +Expected behavior: + +- Identifies that some USD-stage or topology-level randomizations are prestartup-only. +- Warns not to place prestartup-only changes in reset or interval events. +- Suggests pre-generated variants, separate authored assets, or fixed-per-run randomization if per-reset changes are unsupported. + +Known failure modes: + +- Promises per-reset changes for a property that must be authored before simulation starts. +- Omits the timing limitation from the plan. + +## Scenario 3: Interval Disturbance + +Query: "Apply random pushes to the robot during training." + +Expected behavior: + +- Selects interval mode. +- Defines magnitude and interval ranges. +- Recommends small-scale rollout validation before training at scale. + +Known failure modes: + +- Implements pushes in the training loop. +- Does not check tensor device and shape compatibility. + +## Scenario 4: PhysX and Newton Material Randomization + +Query: "Randomize friction and restitution for both PhysX and Newton." + +Expected behavior: + +- Checks the current event implementation for backend-specific behavior. +- Uses PhysX bucket behavior for PhysX. +- Calls out that Newton uses one friction coefficient and ignores `dynamic_friction_range` and `num_buckets`. +- Recommends separate `PresetCfg` event configs and separate smoke tests per backend. + +Known failure modes: + +- Copies PhysX material parameters directly into Newton. +- Ignores CPU/GPU differences in the event implementation. + +## Scenario 5: Direct Workflow Events + +Query: "Add domain randomization events to my DirectRLEnv task." + +Expected behavior: + +- Recognizes that direct RL environments can use `EventManager` through the `events` config field. +- Keeps observations and rewards in direct workflow methods. +- Adds event terms only for randomization behavior. +- References the direct workflow randomization tutorial. + +Known failure modes: + +- Claims event terms are only for manager-based environments. +- Converts the task to manager-based solely to use randomization events. diff --git a/skills/user/domain-randomization-events/examples.md b/skills/user/domain-randomization-events/examples.md new file mode 100644 index 000000000000..b127fcda191e --- /dev/null +++ b/skills/user/domain-randomization-events/examples.md @@ -0,0 +1,73 @@ +# Event Randomization Examples + +## Contents + +- Reset state randomization +- Direct workflow event config +- Prestartup USD randomization +- Startup property randomization +- Backend-specific material randomization +- Interval disturbance + +## Reset State Randomization + +Input: randomize robot initial joint positions at the start of each episode. + +Expected setup: + +- Use a reset event. +- Scope the term to the robot articulation. +- Use conservative joint ranges first. +- Validate with repeated resets before training. + +## Direct Workflow Event Config + +Input: add friction and gravity randomization to a `DirectRLEnv` task. + +Expected setup: + +- Define an `EventCfg` with `EventTerm` entries in the direct task config module. +- Assign `events: EventCfg = EventCfg()` on the direct task config. +- Keep reward and observation logic in direct methods. +- Validate that `prestartup`, `startup`, `reset`, and `interval` modes fire at the expected times for direct workflows. + +## Startup Property Randomization + +Input: randomize a property once after simulation starts. + +Expected setup: + +- Use a startup event. +- Keep ranges tied to physical units. +- Confirm the randomized values are applied before rollout. + +## Prestartup USD Randomization + +Input: randomize authored USD-stage properties or asset variants before simulation buffers are created. + +Expected setup: + +- Use a prestartup event. +- Do not move the change to reset or interval events unless the backend explicitly supports changing that property after initialization. +- If per-episode variation is required but unsupported, pre-generate variants or use separate authored assets. + +## Interval Disturbance + +Input: apply random pushes during locomotion training. + +Expected setup: + +- Use an interval event. +- Choose a clear interval and magnitude range. +- Start with a small number of environments and inspect failures before scaling. + +## Backend-Specific Material Randomization + +Input: randomize rigid-body material properties in an environment that should support PhysX and Newton. + +Expected setup: + +- Read the `randomize_rigid_body_material` implementation before choosing parameters. +- Use PhysX buckets and static/dynamic friction ranges for the PhysX preset. +- Use Newton's single friction coefficient behavior for the Newton preset. +- Do not assume `dynamic_friction_range`, `num_buckets`, or CPU/GPU behavior are identical across backends. diff --git a/skills/user/domain-randomization-events/reference.md b/skills/user/domain-randomization-events/reference.md new file mode 100644 index 000000000000..4b35f0424250 --- /dev/null +++ b/skills/user/domain-randomization-events/reference.md @@ -0,0 +1,80 @@ +# Event Randomization Reference + +## Contents + +- Direct and manager-based usage +- Event mode selection +- Backend compatibility +- Timing limitations +- Current workflow +- Old patterns +- Validation checklist + +## Direct and Manager-Based Usage + +Event randomization is not limited to manager-based environments. Direct RL and direct multi-agent RL configs also expose an `events` field that is handled by `EventManager`. + +Use the same event-term structure in both workflows: + +| Workflow | Where events are configured | +| --- | --- | +| Direct RL | Add an event config class to the direct task config's `events` field. | +| Direct MARL | Add an event config class to the direct multi-agent task config's `events` field. | +| Manager-based | Add an event config class to the manager-based env config's `events` field. | + +In direct workflows, observations and rewards remain direct methods; only randomization is routed through event terms. + +## Event Mode Selection + +Use this default mapping: + +| Desired behavior | Event mode | +| --- | --- | +| Author USD-level properties before simulation starts | `prestartup` | +| Randomize once after simulation starts | `startup` | +| Randomize at episode reset | `reset` | +| Apply repeated disturbances during an episode | `interval` | + +## Backend Compatibility + +Check each event function against the current implementation before assuming the same behavior on PhysX and Newton. Some event functions are backend-neutral through asset APIs, while others dispatch to backend-specific implementations. + +Important examples from `source/isaaclab/isaaclab/envs/mdp/events.py`: + +| Event concern | PhysX behavior | Newton behavior | +| --- | --- | --- | +| Rigid body material randomization | Bucket-based static friction, dynamic friction, and restitution; uses CPU tensors and the PhysX tensor API. | Continuous per-shape friction and restitution; Newton uses one friction coefficient, so `dynamic_friction_range` and `num_buckets` are ignored. | +| Rigid body CoM randomization | Writes full CoM pose data. | Writes position-only CoM data; runtime CoM changes may have different stability implications. | +| Collider offset randomization | Uses PhysX rest/contact offsets. | Maps to Newton margin/gap concepts. | + +For multi-backend environments, use `PresetCfg` event configs. Keep PhysX-only terms in the PhysX preset and provide a Newton-compatible preset when an event is unsupported or has different parameters. + +## Timing Limitations + +Some randomizations are only valid before simulation starts. Use `prestartup` for USD-stage or topology-level authoring that must happen before physics views and simulation buffers are created. Do not move those changes to `reset` or `interval` just to get per-episode variation. + +Use `startup` for one-time setup after simulation starts. Use `reset` only for state or parameter changes that the environment and backend support after initialization. Use `interval` for runtime disturbances such as pushes. + +If the desired property cannot be changed after startup, choose between pre-generating variants, cloning separate authored assets, or documenting that the randomization is fixed per run. + +## Current Workflow + +Define randomization as event terms in the environment configuration. Each term should identify the workflow, target scene entity, backend, mode, distribution, range, and timing limitation. + +Keep randomization ranges conservative at first. Expand ranges after reset and rollout smoke tests pass. + +## Old Patterns + +Avoid hiding domain randomization in environment constructors, training scripts, or reward functions. Those patterns make the randomized behavior hard to inspect and hard to validate. + +## Validation Checklist + +- Each randomized property has a target scene entity. +- The plan states whether the task is direct or manager-based. +- Each randomized property has an explicit backend compatibility note. +- Event modes match the intended timing. +- Prestartup-only changes are not placed in reset or interval events. +- CPU/GPU expectations match the event implementation. +- Distribution ranges use the expected units. +- Repeated resets produce valid states. +- Interval disturbances do not break tensor shapes or device placement. diff --git a/skills/user/migrate-2x-to-3x/SKILL.md b/skills/user/migrate-2x-to-3x/SKILL.md new file mode 100644 index 000000000000..1d4006c6c127 --- /dev/null +++ b/skills/user/migrate-2x-to-3x/SKILL.md @@ -0,0 +1,54 @@ +--- +name: isaaclab-migrating-2x-to-3x +description: Migrates Isaac Lab 2.x projects to Isaac Lab 3.0 by routing agents through the official migration guide, current source APIs, and focused compatibility checks. Use when users mention Isaac Lab 3.0 migration, 2.x projects, quaternion order changes, ProxyArray data access, backend migration, or visualization CLI changes. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Migrating 2.x To 3.x + +## When To Use + +Use this skill when migrating a downstream Isaac Lab 2.x project to Isaac Lab 3.0 or diagnosing migration errors after an upgrade. + +Do not copy migration tables into answers from memory. Read the official migration guide first, then inspect the current source or examples for the specific API involved. + +## Workflow + +1. Read the official migration guide in `docs/source/migration/migrating_to_isaaclab_3-0.rst`. +2. Identify which migration area applies: visualization CLI, backend packages, schema cfgs, quaternion order, `ProxyArray`, asset views, RSL-RL config, or project-specific scripts. +3. Search the downstream project for old API symbols before editing. +4. Apply the smallest focused migration change. +5. Run a targeted smoke test or import test. +6. If the official docs are missing a recurring migration issue, update `docs/source/migration/migrating_to_isaaclab_3-0.rst` instead of expanding this skill with standalone documentation. + +## Validation + +Use this feedback loop: + +```bash +./isaaclab.sh -p -m pytest PATH_TO_DOWNSTREAM_TEST +``` + +For quaternion migrations, use the repository quaternion tooling documented in the official migration guide. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `docs/source/migration/migrating_to_isaaclab_3-0.rst`, `source/isaaclab_rl/isaaclab_rl/rsl_rl/utils.py`, and current training/play scripts under `scripts/reinforcement_learning/`. If code changes invalidate migration guidance, update the official migration document first and keep this skill as a router plus checklist. + +## References + +- [Reference](reference.md) +- [Supplemental checks](supplemental-checks.md) +- [Examples](examples.md) +- [Evaluations](evaluations.md) +- [Official migration guide](../../../docs/source/migration/migrating_to_isaaclab_3-0.rst) +- [RSL-RL compatibility helper](../../../source/isaaclab_rl/isaaclab_rl/rsl_rl/utils.py) diff --git a/skills/user/migrate-2x-to-3x/evaluations.md b/skills/user/migrate-2x-to-3x/evaluations.md new file mode 100644 index 000000000000..886e2a40850b --- /dev/null +++ b/skills/user/migrate-2x-to-3x/evaluations.md @@ -0,0 +1,53 @@ +# Isaac Lab 3.0 Migration Evaluations + +## Contents + +- Scenario 1: quaternion migration +- Scenario 2: ProxyArray migration +- Scenario 3: RSL-RL migration + +## Scenario 1: Quaternion Migration + +Query: "My Isaac Lab 2.x project has hardcoded quaternions and now behaves incorrectly in 3.0." + +Expected behavior: + +- Reads the official migration guide before proposing edits. +- Uses the quaternion finder workflow documented in the repo. +- Distinguishes quaternions from colors or other four-element values. +- Recommends a small task smoke test. + +Known failure modes: + +- Reorders every four-element tuple blindly. +- Ignores runtime quaternion index assignments. + +## Scenario 2: ProxyArray Migration + +Query: "After upgrading, `asset.data.joint_pos.detach()` fails." + +Expected behavior: + +- Routes to the current `ProxyArray` migration guidance. +- Verifies the current access pattern against docs/source before editing. +- Avoids stale raw `wp.to_torch()`-only guidance when the current docs recommend explicit `ProxyArray` accessors. + +Known failure modes: + +- Copies old raw Warp-array instructions from an external skill. +- Changes unrelated asset APIs without checking current source. + +## Scenario 3: RSL-RL Migration + +Query: "My old RSL-RL training script fails after migrating to Isaac Lab 3.0." + +Expected behavior: + +- Checks maintained Isaac Lab RSL-RL scripts and compatibility helpers. +- Identifies whether the downstream script can be replaced with or aligned to the maintained script. +- Runs a small config or training smoke test. + +Known failure modes: + +- Patches a copied training script without comparing to the current maintained implementation. +- Hardcodes old version-specific assumptions into the skill. diff --git a/skills/user/migrate-2x-to-3x/examples.md b/skills/user/migrate-2x-to-3x/examples.md new file mode 100644 index 000000000000..07fb9470d546 --- /dev/null +++ b/skills/user/migrate-2x-to-3x/examples.md @@ -0,0 +1,41 @@ +# Isaac Lab 3.0 Migration Examples + +## Contents + +- Quaternion migration +- ProxyArray migration +- RSL-RL compatibility migration + +## Quaternion Migration + +Input: downstream code contains hardcoded quaternions and direct quaternion index assignments. + +Expected workflow: + +1. Read the quaternion section of the official migration guide. +2. Run the documented quaternion finder tool on the downstream project. +3. Fix identity quaternions mechanically when safe. +4. Review non-identity quaternions and runtime index assignments manually. +5. Run a small task smoke test. + +## ProxyArray Migration + +Input: downstream code calls tensor-only methods on asset or sensor data. + +Expected workflow: + +1. Read the `ProxyArray` sections of the official migration guide. +2. Search for tensor-only method calls on `.data.*` properties. +3. Use the current `ProxyArray` access pattern from the docs and source. +4. Run focused tests around the migrated logic. + +## RSL-RL Compatibility Migration + +Input: downstream training scripts fail after the RSL-RL upgrade. + +Expected workflow: + +1. Inspect current Isaac Lab RSL-RL scripts and `source/isaaclab_rl/isaaclab_rl/rsl_rl/utils.py`. +2. Use the compatibility helper when it applies. +3. Avoid preserving copied training scripts if a maintained Isaac Lab script can be reused or imported. +4. Run a short training or config-construction smoke test. diff --git a/skills/user/migrate-2x-to-3x/reference.md b/skills/user/migrate-2x-to-3x/reference.md new file mode 100644 index 000000000000..656175f6dc9b --- /dev/null +++ b/skills/user/migrate-2x-to-3x/reference.md @@ -0,0 +1,36 @@ +# Isaac Lab 2.x To 3.x Migration Reference + +## Contents + +- Source of truth +- Current workflow +- Old patterns +- Maintenance rule + +## Source of Truth + +The official migration guide is the authoritative source: + +- `docs/source/migration/migrating_to_isaaclab_3-0.rst` + +Use this skill to decide where to look and how to validate. Do not treat this file as a replacement for the migration guide. + +## Current Workflow + +Start with the official migration guide, then verify behavior against current source files and examples. Prioritize these areas: + +- Visualizer CLI and headless behavior. +- Multi-backend architecture and backend-specific packages. +- Schema configuration class refactors. +- Quaternion convention changes. +- `ProxyArray` access for asset and sensor data. +- Asset and physics view API renames. +- RL workflow compatibility helpers. + +## Old Patterns + +Avoid carrying forward old project-specific migration notes as general guidance. The external prototype skill included useful discoveries, but it also contained downstream-project paths, stale raw Warp-array guidance, and one-off commands. Convert those into short search checks and official doc improvements. + +## Maintenance Rule + +If a repeated migration fix is not covered by the official guide, update `docs/source/migration/migrating_to_isaaclab_3-0.rst`. Keep this skill small so it does not become a second migration document that drifts from the codebase. diff --git a/skills/user/migrate-2x-to-3x/supplemental-checks.md b/skills/user/migrate-2x-to-3x/supplemental-checks.md new file mode 100644 index 000000000000..fec8023aa6b0 --- /dev/null +++ b/skills/user/migrate-2x-to-3x/supplemental-checks.md @@ -0,0 +1,38 @@ +# Supplemental Migration Checks + +## Contents + +- Current-source checks +- Prototype-skill checks +- Documentation gaps + +## Current-Source Checks + +Use these checks to route investigation, not as standalone migration docs: + +| Symptom or old pattern | Current source of truth | +| --- | --- | +| `--headless` launch behavior changed | `docs/source/migration/migrating_to_isaaclab_3-0.rst` and `source/isaaclab/isaaclab/app/app_launcher.py` | +| Backend-specific physics or schema cfgs | `docs/source/overview/core-concepts/multi_backend_architecture.rst` and `docs/source/overview/core-concepts/schema_cfgs.rst` | +| Quaternion order changed from WXYZ to XYZW | `docs/source/migration/migrating_to_isaaclab_3-0.rst` and `scripts/tools/find_quaternions.py` | +| Asset or sensor data no longer behaves like plain tensors | `ProxyArray` sections in `docs/source/migration/migrating_to_isaaclab_3-0.rst` | +| `root_physx_view` or object API warnings | asset view sections in `docs/source/migration/migrating_to_isaaclab_3-0.rst` | +| RSL-RL config compatibility errors | `source/isaaclab_rl/isaaclab_rl/rsl_rl/utils.py` | +| Pretrained checkpoint helper import path | `source/isaaclab_rl/isaaclab_rl/utils/pretrained_checkpoint.py` | + +## Prototype-Skill Checks + +The external prototype migration skill called out useful search terms. Before using any fix from that prototype, verify against current docs/source: + +- `AdditiveUniformNoiseCfg` +- `SimulationCfg.physics` +- `PhysxCfg` +- `asset.data.*.detach()` +- `root_physx_view` +- `get_published_pretrained_checkpoint` +- `noise_std_type` +- `--viz` + +## Documentation Gaps + +If one of these checks reveals a real migration issue that is missing from the official migration guide, add the migration note to `docs/source/migration/migrating_to_isaaclab_3-0.rst` and keep this file as a pointer. diff --git a/skills/user/migrate-from-isaac-gym/SKILL.md b/skills/user/migrate-from-isaac-gym/SKILL.md new file mode 100644 index 000000000000..a8f55d54ccea --- /dev/null +++ b/skills/user/migrate-from-isaac-gym/SKILL.md @@ -0,0 +1,64 @@ +--- +name: isaaclab-migrating-from-isaac-gym +description: Migrates Isaac Gym tasks, assets, vectorized environments, and training workflows to Isaac Lab. Use when porting Isaac Gym environments, legacy Gym tasks, or Isaac Gym reinforcement learning code to Isaac Lab. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Migrating From Isaac Gym + +## When To Use + +Use this skill when a user wants to port an Isaac Gym task, asset workflow, observation/reward implementation, or training setup into Isaac Lab. + +Do not use this skill for Isaac Lab 2.x to 3.x migration. Use the `isaaclab-migrating-2x-to-3x` skill for that workflow. + +## Workflow + +1. Identify the Isaac Gym task structure: assets, environment state tensors, observations, rewards, resets, and training runner. +2. Read the IsaacGymEnvs migration guide and direct workflow docs before proposing edits. +3. Migrate to a direct workflow first by default. This preserves the single-class structure that most Isaac Gym tasks already use. +4. Choose the initial backend target. Start with PhysX when matching Isaac Gym behavior; add Newton only after the direct PhysX migration is validated or if the user explicitly targets Newton. +5. Map Isaac Gym PhysX parameters through the schema cfg docs: first to Isaac Lab PhysX cfgs, then to backend-portable base cfgs or Newton/MuJoCo cfgs where an equivalent exists. +6. Map assets to Isaac Lab asset configs and scene entities. +7. Move action application, observation assembly, reward computation, termination checks, and reset logic into a `DirectRLEnv` or `DirectMARLEnv` implementation. +8. Port training configuration to the selected Isaac Lab reinforcement learning workflow. +9. Run a small smoke test before scaling training. +10. Only convert to a manager-based environment if the user asks for modular managers or the task benefits from reusable observation, reward, command, curriculum, or event terms. +11. Iterate through the validation loop until the environment resets, steps, and trains without shape or device errors. + +## Validation + +Use this feedback loop: + +```bash +./isaaclab.sh -p -m pytest PATH_TO_MIGRATION_TEST +``` + +For manual smoke testing, run the smallest training or random-action entry point available for the migrated task. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `docs/source/migration/migrating_from_isaacgymenvs.rst`, `docs/source/overview/core-concepts/task_workflows.rst`, `docs/source/overview/core-concepts/multi_backend_architecture.rst`, `docs/source/overview/core-concepts/schema_cfgs.rst`, the direct environment tutorial, and direct task examples under `source/isaaclab_tasks/isaaclab_tasks/direct/`. If the migration requires documentation-level details, update `docs/source/` or the maintained examples first and keep this skill as a workflow router. + +## References + +- [Reference](reference.md) +- [Examples](examples.md) +- [Rough locomotion validation](validation-rough-locomotion.md) +- [Evaluations](evaluations.md) +- [IsaacGymEnvs migration guide](../../../docs/source/migration/migrating_from_isaacgymenvs.rst) +- [Task workflows](../../../docs/source/overview/core-concepts/task_workflows.rst) +- [Multi-backend architecture](../../../docs/source/overview/core-concepts/multi_backend_architecture.rst) +- [Schema cfgs](../../../docs/source/overview/core-concepts/schema_cfgs.rst) +- [Environments overview](../../../docs/source/overview/environments.rst) +- [Create direct workflow environment tutorial](../../../docs/source/tutorials/03_envs/create_direct_rl_env.rst) +- [Create manager-based environment tutorial](../../../docs/source/tutorials/03_envs/create_manager_rl_env.rst) diff --git a/skills/user/migrate-from-isaac-gym/evaluations.md b/skills/user/migrate-from-isaac-gym/evaluations.md new file mode 100644 index 000000000000..ab68bbdb839b --- /dev/null +++ b/skills/user/migrate-from-isaac-gym/evaluations.md @@ -0,0 +1,71 @@ +# Isaac Gym Migration Evaluations + +## Contents + +- Scenario 1: rough locomotion migration +- Scenario 2: sensor and terrain migration +- Scenario 3: randomization migration +- Scenario 4: Newton backend follow-up + +## Scenario 1: Rough Locomotion Migration + +Query: "Port this IsaacGymEnvs rough-terrain quadruped task to Isaac Lab." + +Expected behavior: + +- Identifies terrain generation, robot asset, commands, observations, rewards, resets, sensors, randomization, and training configuration. +- Recommends a direct environment as the first migration target. +- Maps reward, termination, command, and reset logic into direct environment methods. +- Gives a smoke-test plan before training at scale. + +Known failure modes: + +- Starts by decomposing into manager terms before preserving behavior in direct form. +- Omits terrain or sensor behavior from the migration plan. + +## Scenario 2: Sensor and Terrain Migration + +Query: "Migrate the height measurements and contact force observations from my Isaac Gym quadruped terrain task." + +Expected behavior: + +- Maps terrain generation to `TerrainImporterCfg` and a maintained terrain generator. +- Maps height measurements to a ray-caster height scanner when appropriate. +- Maps contact-force usage to contact sensors. +- Calls out observation-block parity and shape validation. + +Known failure modes: + +- Drops the height measurement block because it is not part of the flat locomotion task. +- Assumes contact-force tensors map directly without sensor configuration. + +## Scenario 3: Randomization Migration + +Query: "Move my Isaac Gym reset randomization to Isaac Lab." + +Expected behavior: + +- Preserves reset randomization behavior in the direct migration first. +- Distinguishes startup, reset, and interval randomization when the user asks for event terms. +- Recommends validation with repeated resets and small environment counts. + +Known failure modes: + +- Places all randomization in environment constructor code. +- Does not verify reset determinism or tensor shapes. + +## Scenario 4: Newton Backend Follow-Up + +Query: "The migrated Isaac Gym task works on PhysX. Add Newton support." + +Expected behavior: + +- Keeps the validated direct workflow intact. +- Uses `PresetCfg` variants for backend-specific physics settings. +- Maps PhysX schema cfgs through the multi-backend and schema cfg docs before proposing Newton equivalents. +- Calls out parameters with no direct Newton equivalent instead of silently copying them. + +Known failure modes: + +- Assumes every PhysX parameter maps one-to-one to Newton. +- Replaces the PhysX config instead of adding a backend preset. diff --git a/skills/user/migrate-from-isaac-gym/examples.md b/skills/user/migrate-from-isaac-gym/examples.md new file mode 100644 index 000000000000..8e6d62b6ce6b --- /dev/null +++ b/skills/user/migrate-from-isaac-gym/examples.md @@ -0,0 +1,37 @@ +# Isaac Gym Migration Examples + +## Contents + +- Rough locomotion task +- PhysX to Newton follow-up +- Domain randomization handoff + +## Rough Locomotion Task + +Input: an Isaac Gym rough-terrain quadruped task uses generated terrain, velocity commands, contact forces, height measurements, reset randomization, and random pushes. + +Output: an Isaac Lab direct environment with: + +- Terrain importer config with a maintained rough terrain generator. +- Articulation config for the quadruped. +- Contact sensors for feet and undesired body contacts. +- Ray-caster height scanner for terrain perception. +- A `DirectRLEnvCfg` config. +- Direct command, action, observation, reward, termination, and reset methods. +- Randomization added after the deterministic direct task runs. + +## Domain Randomization Handoff + +When the migration task is mostly about randomization behavior, first preserve behavior in the direct migration. If the user asks for manager-based randomization or reusable event terms, switch to the `isaaclab-randomizing-with-events` skill. + +## PhysX to Newton Follow-Up + +Input: a migrated direct task runs on PhysX and the user asks to add Newton support. + +Expected workflow: + +- Read the multi-backend and schema cfg docs. +- Add `PresetCfg` variants for PhysX and Newton physics settings. +- Keep PhysX-specific parameters in the PhysX preset. +- Add Newton or MuJoCo solver parameters only where the docs/source show an equivalent. +- Validate PhysX and Newton separately with small smoke tests. diff --git a/skills/user/migrate-from-isaac-gym/reference.md b/skills/user/migrate-from-isaac-gym/reference.md new file mode 100644 index 000000000000..18985fc37d84 --- /dev/null +++ b/skills/user/migrate-from-isaac-gym/reference.md @@ -0,0 +1,72 @@ +# Isaac Gym Migration Reference + +## Contents + +- Direct workflow mapping +- Backend mapping +- Manager-based follow-up mapping +- Current workflow +- Old patterns +- Validation checklist + +## Direct Workflow Mapping + +Use this mapping as the default starting point: + +| Isaac Gym concept | Isaac Lab target | +| --- | --- | +| Task class with tensor buffers | `DirectRLEnv` or `DirectMARLEnv` subclass | +| YAML task config | `DirectRLEnvCfg` or `DirectMARLEnvCfg` config class | +| Asset loading in task setup | Asset config and scene config | +| Action application | Direct environment action methods | +| Observation buffer assembly | Direct observation method | +| Reward tensor functions | Direct reward method or helper function | +| Reset logic | Direct reset method | +| Domain randomization hooks | Direct reset/startup logic first, event terms if the user wants manager-style randomization | +| RL runner script | Isaac Lab training script for the chosen framework | + +## Backend Mapping + +Use PhysX as the first target when preserving Isaac Gym behavior, because Isaac Gym tasks were PhysX-based. Do not assume every PhysX parameter has a Newton equivalent. + +Map backend parameters through the official schema docs: + +| Isaac Gym / PhysX concern | Isaac Lab PhysX target | Newton target | +| --- | --- | --- | +| Simulation-level PhysX settings | `PhysxCfg` on `SimulationCfg.physics` | `NewtonCfg` with a solver cfg such as `MJWarpSolverCfg` | +| Rigid-body settings | `PhysxRigidBodyPropertiesCfg` or backend-portable `RigidBodyBaseCfg` | `NewtonRigidBodyPropertiesCfg` or `MujocoRigidBodyPropertiesCfg` when using the MuJoCo solver | +| Collision settings | `PhysxCollisionPropertiesCfg` or `CollisionBaseCfg` | `NewtonCollisionPropertiesCfg` or `NewtonMeshCollisionPropertiesCfg` | +| Joint-drive settings | `JointDriveBaseCfg` plus PhysX-specific classes when needed | `NewtonJointDrivePropertiesCfg` or `MujocoJointDrivePropertiesCfg` | +| Material settings | `PhysxRigidBodyMaterialCfg` or `RigidBodyMaterialBaseCfg` | `NewtonMaterialPropertiesCfg` | + +For multi-backend tasks, use `PresetCfg` variants so the PhysX and Newton configs can differ cleanly. Keep backend-specific ranges, solver values, and unsupported options in separate presets. + +## Manager-Based Follow-Up Mapping + +Only use this mapping when the user asks for manager-based organization or when the task needs reusable manager terms: + +| Direct migration concern | Manager-based target | +| --- | --- | +| Observation method | Observation manager terms | +| Reward method | Reward manager terms | +| Termination checks | Termination manager terms | +| Reset randomization | Event manager reset terms | +| Command sampling | Command manager terms | + +## Current Workflow + +Prefer a direct environment for the first migration pass. This is closer to Isaac Gym task structure and makes it easier to compare observations, rewards, resets, and actions against the original implementation. + +Move to manager-based environments only when the user asks for a modular task or after the direct migration is validated. + +## Old Patterns + +Legacy Isaac Gym tasks often combine asset loading, reward computation, reset logic, and randomization in one Python class. During the direct migration, keep the logic easy to compare with the original task, but structure methods according to the Isaac Lab direct workflow. + +## Validation Checklist + +- The migrated environment can construct with a small number of environments. +- `reset()` succeeds repeatedly. +- `step()` returns observations with expected shapes. +- Rewards and terminations match the intended task behavior. +- Training starts with the chosen RL framework. diff --git a/skills/user/migrate-from-isaac-gym/validation-rough-locomotion.md b/skills/user/migrate-from-isaac-gym/validation-rough-locomotion.md new file mode 100644 index 000000000000..b1e03af12a33 --- /dev/null +++ b/skills/user/migrate-from-isaac-gym/validation-rough-locomotion.md @@ -0,0 +1,104 @@ +# Rough Locomotion Migration Validation + +## Contents + +- Source task +- How to use this validation +- Why this is the representative validation +- Direct workflow mapping +- Terrain mapping +- Sensors and observations +- Randomization and backend checks +- Result + +## Source Task + +This validation uses IsaacGymEnvs AnymalTerrain: + +- `isaacgymenvs/tasks/anymal_terrain.py` +- `isaacgymenvs/cfg/task/AnymalTerrain.yaml` + +## How To Use This Validation + +Use this file as an evaluation checklist for the migration skill, not as a ready-made migrated task. A useful migration attempt should: + +- Read the IsaacGymEnvs source task and config. +- Start with a direct Isaac Lab environment target. +- Produce an explicit mapping for terrain, sensors, observations, rewards, resets, randomization, and backend settings. +- Identify behavior differences between the legacy task and maintained Isaac Lab examples. +- Define small import, reset, step, and training smoke tests before scaling. + +## Why This Is the Representative Validation + +AnymalTerrain is representative because it combines several migration concerns that usually fail when a skill only handles simple control tasks: + +- Rough triangle-mesh terrain generation with curriculum levels and terrain proportions. +- A quadruped URDF asset with PD control parameters and default joint poses. +- Velocity command sampling. +- Height measurements for terrain perception. +- Net contact force usage for feet, knees, and termination. +- Observation noise, action noise, friction randomization, random pushes, and setup-only mass randomization. +- PhysX simulation parameters such as contact collection, GPU contact pair count, and solver iterations. + +## Direct Workflow Mapping + +| IsaacGymEnvs AnymalTerrain | Isaac Lab direct rough Anymal-C | +| --- | --- | +| `VecTask` subclass | `AnymalCEnv`, a `DirectRLEnv` subclass | +| `AnymalTerrain.yaml` | `AnymalCRoughEnvCfg` config class | +| `numActions = 12` | `action_space = 12` | +| `numObservations = 188` | `observation_space = 235` in the maintained Isaac Lab rough task | +| `dt = 0.005`, `control.decimation = 4` | `sim.dt = 1 / 200`, `decimation = 4` | +| `urdf/anymal_c/urdf/anymal_minimal.urdf` | `isaaclab_assets.robots.anymal.ANYMAL_C_CFG` | +| `create_sim()`, `_create_trimesh()`, `_create_envs()` | `TerrainImporterCfg`, rough terrain generator, and `_setup_scene()` | +| `compute_observations()` | `_get_observations()` with robot state, commands, contact sensor data, and height scanner data | +| `compute_reward()` and reward helpers | `_get_rewards()` with explicit reward terms in the direct environment | +| `reset_idx()` | `_reset_idx()` with command and robot state reset | + +## Terrain Mapping + +IsaacGymEnvs creates a custom triangle mesh through `Terrain(...)` and `gym.add_triangle_mesh(...)`. In Isaac Lab, route this through `TerrainImporterCfg` with `terrain_type="generator"` and a maintained terrain generator such as `ROUGH_TERRAINS_CFG`. + +The IsaacGymEnvs terrain settings map conceptually as: + +| IsaacGymEnvs terrain setting | Isaac Lab target | +| --- | --- | +| `terrainType: trimesh` | `TerrainImporterCfg(terrain_type="generator")` | +| `curriculum` | terrain generator curriculum setting | +| `numLevels`, `numTerrains` | terrain generator rows / columns or difficulty grid | +| `terrainProportions` | terrain generator sub-terrain proportions | +| friction / restitution | terrain physics material | +| custom terrain origins | terrain importer environment origins | + +## Sensors and Observations + +IsaacGymEnvs AnymalTerrain uses net contact forces and sampled terrain heights. The maintained Isaac Lab direct rough Anymal-C task uses: + +- `ContactSensorCfg` for contact history, feet air time, and undesired contacts. +- `RayCasterCfg` mounted on the robot base with rays cast against `/World/ground`. +- Direct observation assembly that includes height scanner data for rough terrain. + +Do not assume observation dimensions will match exactly. A migration that needs behavior parity should compare every observation block and decide whether to preserve IsaacGymEnvs' 188-dimensional observation or adopt the maintained Isaac Lab rough locomotion observation layout. + +## Randomization and Backend Checks + +IsaacGymEnvs AnymalTerrain includes: + +- Observation and action noise. +- Friction randomization. +- Random pushes. +- Setup-only rigid-body mass randomization. +- DOF damping, stiffness, and limit randomization. + +In Isaac Lab, first migrate the direct task until it runs with the maintained baseline randomization. Then port the legacy task's additional randomization through event terms or noise models, checking each item against current source: + +- Use the `isaaclab-randomizing-with-events` skill for event timing and backend compatibility. +- Treat setup-only randomization as `prestartup` or `startup` unless the backend supports runtime changes. +- Check PhysX versus Newton behavior before adding `PresetCfg` support. +- Validate CPU/GPU assumptions for each event implementation. + +## Result + +The migration skill is actionable for a non-toy rough-terrain locomotion task. The direct-first path remains valid because Isaac Lab has a maintained direct rough Anymal-C task at `source/isaaclab_tasks/isaaclab_tasks/direct/anymal_c/`. + +This validation also shows the limits of direct copying: terrain generation, sensor models, observation layout, randomization timing, and PhysX/Newton support must be mapped deliberately through Isaac Lab docs and maintained source. diff --git a/skills/user/select-backends/SKILL.md b/skills/user/select-backends/SKILL.md new file mode 100644 index 000000000000..3bca7c3216ae --- /dev/null +++ b/skills/user/select-backends/SKILL.md @@ -0,0 +1,57 @@ +--- +name: isaaclab-selecting-backends +description: Selects and validates Isaac Lab physics and rendering backends. Use when choosing PhysX or Newton, adding backend presets, comparing backend behavior, or debugging backend-specific simulation, randomization, sensor, or renderer issues. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Selecting Backends + +## When To Use + +Use this skill when a user needs to choose, configure, compare, or debug Isaac Lab physical backends or renderer-related behavior. + +Do not use this skill to duplicate backend reference material. Link to the multi-backend docs, schema cfg docs, and source examples for current configuration details. + +## Workflow + +1. Identify the target backend: PhysX, Newton, or a task that must support both through presets. +2. Read the multi-backend architecture and schema cfg docs before editing backend configs. +3. Start with the backend that best matches the source task or current maintained example. Use PhysX first when matching Isaac Gym behavior. +4. Add backend presets only after the task runs on one backend. +5. Map simulation parameters through public cfg schemas instead of copying old simulator-specific keys. +6. Check backend support for sensors, randomization events, terrain, contacts, and actuators before enabling them. +7. Separate backend-specific differences using `PresetCfg` or existing preset helpers rather than runtime conditionals scattered through task code. +8. Validate each backend with a small reset/step rollout before training. +9. Document intentional behavior differences, especially around contacts, randomization timing, CPU/GPU data paths, and renderer requirements. + +## Validation + +Use this checklist: + +1. Run a small reset/step smoke test on the primary backend. +2. If adding another backend, run the same smoke test there before training. +3. Compare observation shape, action shape, reset behavior, and contact behavior. +4. Check randomization events for backend-specific support and device assumptions. +5. Run short training only after both backends pass smoke tests. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `docs/source/overview/core-concepts/multi_backend_architecture.rst`, `docs/source/overview/core-concepts/schema_cfgs.rst`, backend installation docs, and backend-aware task examples under `source/isaaclab_tasks/isaaclab_tasks/`. If backend docs are incomplete, improve the docs rather than expanding this skill into a backend reference. + +## References + +- [Evaluations](evaluations.md) +- [Multi-backend architecture](../../../docs/source/overview/core-concepts/multi_backend_architecture.rst) +- [Schema cfgs](../../../docs/source/overview/core-concepts/schema_cfgs.rst) +- [PhysX installation](../../../docs/source/overview/core-concepts/physical-backends/physx/installation.rst) +- [Newton installation](../../../docs/source/overview/core-concepts/physical-backends/newton/installation.rst) +- [Task examples](../../../source/isaaclab_tasks/isaaclab_tasks) diff --git a/skills/user/select-backends/evaluations.md b/skills/user/select-backends/evaluations.md new file mode 100644 index 000000000000..cbfc535428a9 --- /dev/null +++ b/skills/user/select-backends/evaluations.md @@ -0,0 +1,46 @@ +# Backend Selection Evaluations + +## Scenario 1: Isaac Gym Parity + +Query: "I am porting an Isaac Gym task. Should I start with PhysX or Newton?" + +Expected behavior: + +- Recommends PhysX first when matching Isaac Gym behavior. +- Maps simulation parameters through Isaac Lab cfg schemas. +- Defers Newton support until the direct PhysX migration is stable unless the user explicitly targets Newton. + +Known failure modes: + +- Starts with Newton without explaining behavior differences. +- Copies Isaac Gym PhysX keys directly into Isaac Lab configs. + +## Scenario 2: Add Presets + +Query: "My task works on PhysX. Add Newton support too." + +Expected behavior: + +- Adds backend-specific presets or config variants. +- Checks sensors, contacts, actuators, terrain, and randomization events for backend support. +- Runs reset/step smoke tests on both backends. + +Known failure modes: + +- Adds runtime conditionals throughout task logic instead of config presets. +- Assumes event randomization works identically on both backends. + +## Scenario 3: Renderer Or Sensor Issue + +Query: "My camera observations work in one mode but fail with another backend or renderer." + +Expected behavior: + +- Separates physics backend, renderer, sensor type, and device assumptions. +- Points to relevant backend and sensor docs. +- Recommends a small reproducible smoke test before training. + +Known failure modes: + +- Treats all visual failures as physics backend bugs. +- Ignores renderer and app-launch requirements. diff --git a/skills/user/setup-troubleshooting/SKILL.md b/skills/user/setup-troubleshooting/SKILL.md new file mode 100644 index 000000000000..a0d0dd26c8b4 --- /dev/null +++ b/skills/user/setup-troubleshooting/SKILL.md @@ -0,0 +1,61 @@ +--- +name: isaaclab-setup-troubleshooting +description: Routes Isaac Lab installation, verification, and common troubleshooting issues to official docs and canonical commands. Use when installing Isaac Lab, verifying setup, debugging launch failures, or diagnosing environment problems. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Setup Troubleshooting + +## When To Use + +Use this skill when a user asks for help installing Isaac Lab, verifying a local setup, or diagnosing common setup and launch failures. + +Do not duplicate installation or troubleshooting docs in this skill. The official docs are the source of truth. + +## Workflow + +1. Identify the install mode: pip, source, binary, cloud, kitless, or backend-specific setup. +2. Identify OS, Python environment, GPU/driver context, Isaac Sim source, and target backend. +3. Read the matching installation guide and troubleshooting reference before prescribing commands. +4. Use documented Isaac Lab wrapper commands such as `./isaaclab.sh -p` for Python and tests. +5. Ask for the smallest relevant error output when the failure mode is unclear. +6. Prefer a minimal verification command before running examples, training, or rendering workflows. +7. Route backend-specific setup to the relevant PhysX or Newton docs. +8. If the docs are incomplete or stale, update the docs rather than expanding this skill. + +## Validation + +Use this checklist: + +1. Confirm the user is following one supported install path. +2. Confirm Python and package commands use the Isaac Lab wrapper when applicable. +3. Run a minimal import or verification command before larger tests. +4. Check troubleshooting docs for the observed error class. +5. Escalate to environment-specific debugging only after the documented checks are exhausted. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with installation docs under `docs/source/setup/installation/`, quick installation docs, backend installation docs, and `docs/source/refs/troubleshooting.rst`. Setup guidance changes often, so keep this skill as a router to official docs and minimal verification steps. + +## References + +- [Evaluations](evaluations.md) +- [Quick installation](../../../docs/source/setup/quick_installation.rst) +- [Source installation](../../../docs/source/setup/installation/source_installation.rst) +- [Pip installation](../../../docs/source/setup/installation/pip_installation.rst) +- [Isaac Lab pip installation](../../../docs/source/setup/installation/isaaclab_pip_installation.rst) +- [Binary installation](../../../docs/source/setup/installation/binaries_installation.rst) +- [Cloud installation](../../../docs/source/setup/installation/cloud_installation.rst) +- [Kitless installation](../../../docs/source/setup/installation/kitless_installation.rst) +- [PhysX installation](../../../docs/source/overview/core-concepts/physical-backends/physx/installation.rst) +- [Newton installation](../../../docs/source/overview/core-concepts/physical-backends/newton/installation.rst) +- [Troubleshooting](../../../docs/source/refs/troubleshooting.rst) diff --git a/skills/user/setup-troubleshooting/evaluations.md b/skills/user/setup-troubleshooting/evaluations.md new file mode 100644 index 000000000000..61b1808cc8d9 --- /dev/null +++ b/skills/user/setup-troubleshooting/evaluations.md @@ -0,0 +1,46 @@ +# Setup Troubleshooting Evaluations + +## Scenario 1: Fresh Install + +Query: "Help me install Isaac Lab from source on my machine." + +Expected behavior: + +- Asks for OS, Python environment, Isaac Sim source, GPU/driver context, and desired backend. +- Points to the official source installation guide. +- Uses documented wrapper commands for verification. + +Known failure modes: + +- Copies an installation recipe into the skill response without checking the current docs. +- Mixes pip, source, and binary installation steps. + +## Scenario 2: Import Failure + +Query: "Isaac Lab installed, but imports fail when I run my script." + +Expected behavior: + +- Checks whether the user is running through the Isaac Lab wrapper or correct environment. +- Points to troubleshooting docs for the observed error. +- Requests the smallest relevant traceback if the failure is ambiguous. + +Known failure modes: + +- Suggests reinstalling before checking the active environment. +- Diagnoses from a partial error message without asking for the missing context. + +## Scenario 3: Backend Setup + +Query: "I want to run this task with Newton but setup fails." + +Expected behavior: + +- Routes to backend-specific installation docs. +- Separates backend installation issues from task implementation issues. +- Verifies setup with a minimal command before running training. + +Known failure modes: + +- Treats backend setup as a task bug. +- Gives backend-specific commands without checking the docs. diff --git a/skills/user/train-rl-agents/SKILL.md b/skills/user/train-rl-agents/SKILL.md new file mode 100644 index 000000000000..2ad05b06994e --- /dev/null +++ b/skills/user/train-rl-agents/SKILL.md @@ -0,0 +1,56 @@ +--- +name: isaaclab-training-rl-agents +description: Configures and runs Isaac Lab reinforcement learning workflows. Use when selecting RL frameworks, wiring agent configs, launching training, resuming runs, or troubleshooting training setup for Isaac Lab tasks. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Training RL Agents + +## When To Use + +Use this skill when a user wants to train, resume, evaluate, or configure reinforcement learning for an Isaac Lab task. + +Do not use this skill to design environment observations, rewards, or resets from scratch. Use `isaaclab-building-environments` (`skills/user/build-environments/`) for environment construction first. + +## Workflow + +1. Identify the registered task name, workflow type, action space, observation space, target backend, device, and desired RL framework. +2. Read the RL training guide and the training tutorial before writing commands or configs. +3. Start from an existing agent config under `source/isaaclab_tasks/isaaclab_tasks/` that matches the framework and task family. +4. Keep framework-specific config formats separate. Do not mix RSL-RL Python configs with RL-Games, SKRL, or SB3 YAML/config files. +5. Use `./isaaclab.sh -p` entry points and documented scripts rather than ad hoc Python invocations. +6. Run a small smoke training job before scaling environment count, horizon, network size, or logging integrations. +7. For visual observations, confirm the sensor pipeline and renderer requirements before enabling large environment counts. +8. For multi-backend tasks, validate training on one backend before introducing backend presets. +9. Record the exact task, framework, backend, seed, and config overrides needed to reproduce the result. + +## Validation + +Use this checklist: + +1. Confirm the task can reset and step without the training runner. +2. Confirm the selected agent config belongs to the intended RL framework. +3. Run a short training command with a small number of environments. +4. Resume or load a checkpoint only after the initial run writes expected artifacts. +5. Check logs for device, observation shape, action shape, and backend errors. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `docs/source/overview/reinforcement-learning/training_guide.rst`, RL training tutorials under `docs/source/tutorials/03_envs/`, and agent configs under `source/isaaclab_tasks/isaaclab_tasks/`. If framework commands or config formats change, update the official training docs or maintained examples first. + +## References + +- [Evaluations](evaluations.md) +- [RL training guide](../../../docs/source/overview/reinforcement-learning/training_guide.rst) +- [Configure RL training tutorial](../../../docs/source/tutorials/03_envs/configuring_rl_training.rst) +- [Run RL training tutorial](../../../docs/source/tutorials/03_envs/run_rl_training.rst) +- [Task examples](../../../source/isaaclab_tasks/isaaclab_tasks) diff --git a/skills/user/train-rl-agents/evaluations.md b/skills/user/train-rl-agents/evaluations.md new file mode 100644 index 000000000000..f4e26300a17f --- /dev/null +++ b/skills/user/train-rl-agents/evaluations.md @@ -0,0 +1,46 @@ +# RL Training Evaluations + +## Scenario 1: Choose A Framework + +Query: "I have a new locomotion task. Should I train it with RSL-RL, RL-Games, SKRL, or SB3?" + +Expected behavior: + +- Asks about task type, observation space, action space, desired framework, and existing nearby examples. +- Points to official training docs and maintained agent configs. +- Recommends starting from the closest existing task config. + +Known failure modes: + +- Recommends hyperparameters without checking any maintained examples. +- Mixes framework-specific config formats. + +## Scenario 2: Smoke Train A New Task + +Query: "My environment imports now. Help me run the first training test." + +Expected behavior: + +- Runs or proposes reset/step validation before training. +- Uses documented Isaac Lab training entry points. +- Keeps environment count and run length small for the first training check. + +Known failure modes: + +- Starts a full-scale training run before checking shape and reset behavior. +- Uses a raw `python` command instead of the Isaac Lab wrapper. + +## Scenario 3: Visual Observations + +Query: "Train a policy using camera observations." + +Expected behavior: + +- Checks renderer, sensor config, observation shape, memory cost, and framework support. +- Points to sensor docs and camera-enabled examples. +- Recommends a small environment count until the visual pipeline is stable. + +Known failure modes: + +- Treats camera observations like low-dimensional state without checking rendering requirements. +- Ignores GPU memory and renderer constraints. diff --git a/skills/user/use-sensors-actuators/SKILL.md b/skills/user/use-sensors-actuators/SKILL.md new file mode 100644 index 000000000000..4dde2c79634a --- /dev/null +++ b/skills/user/use-sensors-actuators/SKILL.md @@ -0,0 +1,60 @@ +--- +name: isaaclab-using-sensors-actuators +description: Adds and configures Isaac Lab sensors and actuators. Use when adding cameras, contact sensors, ray casters, IMUs, joint wrench sensors, tiled cameras, actuator models, or sensor observations to tasks. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Using Sensors And Actuators + +## When To Use + +Use this skill when a user wants to add, configure, or debug sensors or actuator models in an Isaac Lab task. + +Do not use this skill as a complete sensor or actuator catalog. Point to the API docs and maintained examples for available classes and parameters. + +## Workflow + +1. Identify the data needed by the task: contacts, ray hits, camera images, IMU data, joint wrench data, actuator dynamics, or low-dimensional robot state. +2. Read the relevant sensor or actuator docs before editing configs. +3. Check whether the sensor requires a simulation app, renderer, backend-specific support, or special update period. +4. Add sensor or actuator configs to the environment scene or asset config using existing task examples as templates. +5. Register the sensor in the scene setup for direct workflows, or in the scene config for manager-based workflows. +6. Add observation terms only after confirming the sensor data shape and device. +7. For contact-heavy tasks, verify body name patterns and history length. +8. For ray-cast terrain perception, verify mesh paths and terrain import setup. +9. For camera-based RL, start with small environment counts and confirm renderer memory behavior. +10. For actuator changes, compare default joint names, limits, stiffness, damping, effort limits, and backend differences. + +## Validation + +Use this checklist: + +1. Instantiate the environment with a small number of environments. +2. Confirm the sensor or actuator config binds to the intended prims or joints. +3. Step the simulation and inspect data shape, dtype, device, and update timing. +4. Confirm observations include the intended data and no stale values. +5. Run a short rollout or training smoke test after shape validation. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with sensor and actuator docs under `docs/source/overview/core-concepts/`, sensor tutorials under `docs/source/tutorials/04_sensors/`, API docs under `docs/source/api/`, and maintained task examples under `source/isaaclab_tasks/isaaclab_tasks/`. If sensor support changes for PhysX, Newton, or renderers, update the docs or source examples first. + +## References + +- [Evaluations](evaluations.md) +- [Add sensors on robot tutorial](../../../docs/source/tutorials/04_sensors/add_sensors_on_robot.rst) +- [Contact sensor docs](../../../docs/source/overview/core-concepts/sensors/contact_sensor.rst) +- [Joint wrench sensor docs](../../../docs/source/overview/core-concepts/sensors/joint_wrench_sensor.rst) +- [Actuators docs](../../../docs/source/overview/core-concepts/actuators.rst) +- [Sensors API](../../../docs/source/api/lab/isaaclab.sensors.rst) +- [Sensor patterns API](../../../docs/source/api/lab/isaaclab.sensors.patterns.rst) +- [Actuators API](../../../docs/source/api/lab/isaaclab.actuators.rst) diff --git a/skills/user/use-sensors-actuators/evaluations.md b/skills/user/use-sensors-actuators/evaluations.md new file mode 100644 index 000000000000..0e3c7e1207c8 --- /dev/null +++ b/skills/user/use-sensors-actuators/evaluations.md @@ -0,0 +1,46 @@ +# Sensors And Actuators Evaluations + +## Scenario 1: Contact Sensor + +Query: "Add foot contact observations and air-time rewards to my quadruped task." + +Expected behavior: + +- Points to contact sensor docs and nearby locomotion examples. +- Checks body name patterns, history length, update period, and contact thresholds. +- Validates sensor data shape before adding observations and rewards. + +Known failure modes: + +- Reads raw contact tensors directly without configuring the scene sensor. +- Uses body name patterns that do not match the robot asset. + +## Scenario 2: Ray-Cast Terrain Perception + +Query: "Add height measurements for rough terrain locomotion." + +Expected behavior: + +- Points to ray-caster usage in maintained rough locomotion examples. +- Checks terrain mesh paths and ray pattern configuration. +- Adds observation data only after validating ray hit shape and device. + +Known failure modes: + +- Adds height observations without binding the ray caster to the ground mesh. +- Assumes flat-terrain observation dimensions still apply. + +## Scenario 3: Actuator Model + +Query: "Replace ideal position control with a learned actuator model." + +Expected behavior: + +- Checks actuator docs, robot asset config, joint names, and backend constraints. +- Preserves joint limits and control semantics when changing actuator config. +- Runs a small rollout to catch stability or device issues. + +Known failure modes: + +- Changes actuator type without checking joint names and limits. +- Treats actuator behavior as independent of physics backend. diff --git a/tools/skills/cli.py b/tools/skills/cli.py new file mode 100644 index 000000000000..66a04a75e82d --- /dev/null +++ b/tools/skills/cli.py @@ -0,0 +1,340 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Validate Isaac Lab agent skills. + +Skills live under ``skills///SKILL.md`` and are markdown +guidance assets for agents. This tool keeps the accepted skill format small, +portable, and reviewable. +""" + +from __future__ import annotations + +import argparse +import re +import sys +from dataclasses import dataclass +from pathlib import Path +from urllib.parse import unquote + +REPO_ROOT = Path(__file__).parent.parent.parent +SKILLS_ROOT = REPO_ROOT / "skills" + +AUDIENCES = {"developer", "user"} +STATUSES = {"experimental", "stable", "deprecated"} +REQUIRED_SECTIONS = {"When To Use", "Workflow", "Validation", "Maintenance", "References"} + +NAME_RE = re.compile(r"^[a-z0-9-]{1,64}$") +HEADING_RE = re.compile(r"^## (?P.+?)\s*$", re.MULTILINE) +LINK_RE = re.compile(r"(?<!!)\[[^\]]+\]\((?P<target>[^)]+)\)") +BACKTICK_PATH_RE = re.compile(r"`(?P<path>(?:docs|source|scripts|skills|tools|\.github)/[^`\s]+)`") +XML_TAG_RE = re.compile(r"<[^>]+>") +WINDOWS_PATH_RE = re.compile(r"(?<!`)[A-Za-z0-9_.-]+\\[A-Za-z0-9_.-]+") +SCENARIO_RE = re.compile(r"^#{2,3} Scenario\b", re.MULTILINE) +GENERIC_NAME_PARTS = {"helper", "helpers", "utils", "tools"} + + +def _display_path(path: Path) -> str: + try: + return path.relative_to(REPO_ROOT).as_posix() + except ValueError: + return path.as_posix() + + +def _is_relative_to(path: Path, root: Path) -> bool: + try: + path.relative_to(root) + except ValueError: + return False + return True + + +def _parse_frontmatter(text: str) -> tuple[dict[str, str | list[str]], str, str | None]: + lines = text.splitlines() + if not lines or lines[0] != "---": + return {}, text, "missing YAML frontmatter" + + end = None + for index, line in enumerate(lines[1:], start=1): + if line == "---": + end = index + break + if end is None: + return {}, text, "unterminated YAML frontmatter" + + data: dict[str, str | list[str]] = {} + current_list_key: str | None = None + for line in lines[1:end]: + if not line.strip(): + continue + if line.startswith(" - "): + if current_list_key is None: + return data, "\n".join(lines[end + 1 :]), f"list item without key: {line!r}" + value = line[4:].strip() + current = data.setdefault(current_list_key, []) + if not isinstance(current, list): + return data, "\n".join(lines[end + 1 :]), f"mixed scalar/list value for {current_list_key!r}" + current.append(value) + continue + current_list_key = None + if ":" not in line: + return data, "\n".join(lines[end + 1 :]), f"invalid frontmatter line: {line!r}" + key, value = line.split(":", 1) + key = key.strip() + value = value.strip() + if not key: + return data, "\n".join(lines[end + 1 :]), "empty frontmatter key" + if value: + data[key] = value.strip("\"'") + else: + data[key] = [] + current_list_key = key + + return data, "\n".join(lines[end + 1 :]), None + + +@dataclass(frozen=True) +class Skill: + """One ``SKILL.md`` file and its validation rules.""" + + path: Path + + @property + def root(self) -> Path: + return self.path.parent + + @property + def audience_dir(self) -> str: + try: + return self.path.relative_to(SKILLS_ROOT).parts[0] + except ValueError: + return self.path.parent.parent.name + + def validate(self) -> list[str]: + errors: list[str] = [] + if self.path.name != "SKILL.md": + return [f"{_display_path(self.path)}: expected file named SKILL.md"] + if not self.path.exists(): + return [f"{_display_path(self.path)}: file does not exist"] + + text = self.path.read_text(encoding="utf-8") + metadata, body, frontmatter_error = _parse_frontmatter(text) + if frontmatter_error: + errors.append(f"{_display_path(self.path)}: {frontmatter_error}") + return errors + + errors.extend(self._validate_metadata(metadata)) + errors.extend(self._validate_body(body)) + errors.extend(self._validate_links(self.path, body, enforce_one_level=True)) + errors.extend(self._validate_backtick_paths(self.path, body)) + errors.extend(self._validate_reference_files()) + if metadata.get("audience") == "user": + errors.extend(self._validate_user_evaluations(body)) + errors.extend(self._validate_scripts(body)) + return errors + + def _validate_metadata(self, metadata: dict[str, str | list[str]]) -> list[str]: + errors: list[str] = [] + name = metadata.get("name") + description = metadata.get("description") + audience = metadata.get("audience") + status = metadata.get("status") + owners = metadata.get("owners") + + if not isinstance(name, str) or not name: + errors.append(f"{_display_path(self.path)}: missing required frontmatter field 'name'") + elif not NAME_RE.fullmatch(name): + errors.append(f"{_display_path(self.path)}: invalid skill name {name!r}") + else: + name_parts = set(name.split("-")) + if name_parts & GENERIC_NAME_PARTS: + errors.append( + f"{_display_path(self.path)}: skill name contains generic term {name_parts & GENERIC_NAME_PARTS}" + ) + if "claude" in name_parts or "anthropic" in name_parts: + errors.append(f"{_display_path(self.path)}: skill name uses reserved words") + + if not isinstance(description, str) or not description: + errors.append(f"{_display_path(self.path)}: missing required frontmatter field 'description'") + elif len(description) > 1024: + errors.append(f"{_display_path(self.path)}: description is longer than 1024 characters") + else: + lowered = description.lower() + if XML_TAG_RE.search(description): + errors.append(f"{_display_path(self.path)}: description must not contain XML tags") + if "use when" not in lowered: + errors.append(f"{_display_path(self.path)}: description must include 'Use when' trigger guidance") + if lowered.startswith(("i ", "i can", "you ", "you can")): + errors.append(f"{_display_path(self.path)}: description must be written in third person") + + if audience not in AUDIENCES: + errors.append(f"{_display_path(self.path)}: audience must be one of {sorted(AUDIENCES)}") + elif audience != self.audience_dir: + errors.append( + f"{_display_path(self.path)}: audience {audience!r} does not match directory {self.audience_dir!r}" + ) + + if status not in STATUSES: + errors.append(f"{_display_path(self.path)}: status must be one of {sorted(STATUSES)}") + + if not isinstance(owners, list) or not owners or any(not owner for owner in owners): + errors.append(f"{_display_path(self.path)}: owners must list at least one owner") + + return errors + + def _validate_body(self, body: str) -> list[str]: + errors: list[str] = [] + line_count = len(body.splitlines()) + if line_count > 500: + errors.append(f"{_display_path(self.path)}: SKILL.md body must stay under 500 lines") + if WINDOWS_PATH_RE.search(body): + errors.append(f"{_display_path(self.path)}: use forward-slash paths, not Windows-style paths") + + sections = {match.group("title") for match in HEADING_RE.finditer(body)} + missing = sorted(REQUIRED_SECTIONS - sections) + if missing: + errors.append(f"{_display_path(self.path)}: missing required sections: {', '.join(missing)}") + return errors + + def _validate_links(self, source: Path, body: str, enforce_one_level: bool = False) -> list[str]: + errors: list[str] = [] + for match in LINK_RE.finditer(body): + raw_target = match.group("target").strip() + if self._is_external_or_anchor(raw_target): + continue + target_text = unquote(raw_target.split("#", 1)[0]) + target = (source.parent / target_text).resolve() + if not target.exists(): + errors.append(f"{_display_path(source)}: broken link {raw_target!r}") + continue + if enforce_one_level and _is_relative_to(target, self.root): + rel = target.relative_to(self.root) + if len(rel.parts) > 1: + errors.append( + f"{_display_path(source)}: local skill references must be one level deep: {raw_target}" + ) + return errors + + def _validate_reference_files(self) -> list[str]: + errors: list[str] = [] + for reference in self.root.rglob("*.md"): + if reference.name == "SKILL.md": + continue + text = reference.read_text(encoding="utf-8") + lines = text.splitlines() + if len(lines) > 100 and not any(line.strip() in {"# Contents", "## Contents"} for line in lines[:20]): + errors.append(f"{_display_path(reference)}: reference files over 100 lines need a Contents section") + if WINDOWS_PATH_RE.search(text): + errors.append(f"{_display_path(reference)}: use forward-slash paths, not Windows-style paths") + errors.extend(self._validate_links(reference, text)) + errors.extend(self._validate_backtick_paths(reference, text)) + return errors + + def _validate_backtick_paths(self, source: Path, text: str) -> list[str]: + errors: list[str] = [] + for match in BACKTICK_PATH_RE.finditer(text): + raw_path = match.group("path").rstrip(".,);:") + if "<" in raw_path or ">" in raw_path: + continue + target = (REPO_ROOT / raw_path).resolve() + if not target.exists(): + errors.append(f"{_display_path(source)}: backtick path does not exist: {raw_path}") + return errors + + def _validate_user_evaluations(self, body: str) -> list[str]: + errors: list[str] = [] + evaluations = self.root / "evaluations.md" + if not evaluations.exists(): + errors.append(f"{_display_path(self.path)}: user-facing skills must include evaluations.md") + return errors + if "evaluations.md" not in body: + errors.append(f"{_display_path(self.path)}: user-facing skills must link to evaluations.md from SKILL.md") + text = evaluations.read_text(encoding="utf-8") + scenario_matches = list(SCENARIO_RE.finditer(text)) + if len(scenario_matches) < 3: + errors.append(f"{_display_path(evaluations)}: user-facing skills need at least three evaluation scenarios") + for index, match in enumerate(scenario_matches, start=1): + next_match = scenario_matches[index] if index < len(scenario_matches) else None + scenario_text = text[match.start() : next_match.start() if next_match else len(text)] + scenario_name = match.group(0).strip("# ") + if "Query:" not in scenario_text: + errors.append(f"{_display_path(evaluations)}: {scenario_name} must include a sample query") + if "Expected behavior:" not in scenario_text: + errors.append(f"{_display_path(evaluations)}: {scenario_name} must include expected behavior") + if ( + "Known failure modes:" not in scenario_text + and "Pass/fail" not in scenario_text + and "pass/fail" not in scenario_text + ): + errors.append( + f"{_display_path(evaluations)}: {scenario_name} must include known failure modes " + "or pass/fail criteria" + ) + return errors + + def _validate_scripts(self, body: str) -> list[str]: + scripts = self.root / "scripts" + if not scripts.exists(): + return [] + if "Run `scripts/" not in body and "Read `scripts/" not in body: + return [f"{_display_path(self.path)}: scripts require explicit run-or-read instructions"] + return [] + + @staticmethod + def _is_external_or_anchor(target: str) -> bool: + return target.startswith(("#", "http://", "https://", "mailto:")) + + +def iter_skills(root: Path = SKILLS_ROOT) -> list[Skill]: + if not root.exists(): + return [] + return [Skill(path) for path in sorted(root.glob("*/*/SKILL.md"))] + + +def validate_all(root: Path = SKILLS_ROOT) -> list[str]: + errors: list[str] = [] + skills = iter_skills(root) + names: dict[str, Path] = {} + for skill in skills: + metadata, _, frontmatter_error = _parse_frontmatter(skill.path.read_text(encoding="utf-8")) + if frontmatter_error is None and isinstance(metadata.get("name"), str): + name = str(metadata["name"]) + if name in names: + errors.append( + f"{_display_path(skill.path)}: duplicate skill name {name!r}; " + f"first used by {_display_path(names[name])}" + ) + else: + names[name] = skill.path + errors.extend(skill.validate()) + return errors + + +def _cmd_check(args: argparse.Namespace) -> int: + root = Path(args.root).resolve() if args.root else SKILLS_ROOT + errors = validate_all(root) + if errors: + print("Skill validation failed:") + for error in errors: + print(f"- {error}") + return 1 + print(f"Validated {len(iter_skills(root))} skills.") + return 0 + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + subparsers = parser.add_subparsers(dest="command", required=True) + + check = subparsers.add_parser("check", help="validate Isaac Lab skills") + check.add_argument("--root", type=Path, default=None, help="skills root to validate") + check.set_defaults(func=_cmd_check) + + args = parser.parse_args(argv) + return args.func(args) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tools/skills/pyproject.toml b/tools/skills/pyproject.toml new file mode 100644 index 000000000000..13d5692153e7 --- /dev/null +++ b/tools/skills/pyproject.toml @@ -0,0 +1,11 @@ +# Scopes pytest to this self-contained tool: the ``[tool.pytest.ini_options]`` +# section makes pytest treat ``tools/skills/`` as its rootdir, so: +# +# 1. ``pythonpath = ["."]`` adds ``tools/skills/`` to ``sys.path``, +# making ``import cli`` work from the test files without any shim. +# 2. ``tools/conftest.py`` sits above rootdir and is therefore not loaded. +# +# Run with: ``./isaaclab.sh -p -m pytest tools/skills/`` +[tool.pytest.ini_options] +pythonpath = ["."] +testpaths = ["test"] diff --git a/tools/skills/test/test_validate.py b/tools/skills/test/test_validate.py new file mode 100644 index 000000000000..2ae6f1e845ed --- /dev/null +++ b/tools/skills/test/test_validate.py @@ -0,0 +1,149 @@ +# Copyright (c) 2022-2026, The Isaac Lab Project Developers (https://github.com/isaac-sim/IsaacLab/blob/main/CONTRIBUTORS.md). +# All rights reserved. +# +# SPDX-License-Identifier: BSD-3-Clause + +"""Skill validation rules.""" + +from __future__ import annotations + +from pathlib import Path + +import cli + + +def _write_skill(root: Path, audience: str = "user", name: str = "isaaclab-testing-skill") -> Path: + skill_dir = root / audience / "example" + skill_dir.mkdir(parents=True) + (skill_dir / "reference.md").write_text("# Reference\n\n## Contents\n\n- Current workflow\n", encoding="utf-8") + if audience == "user": + (skill_dir / "evaluations.md").write_text( + "# Evaluations\n\n" + "## Contents\n\n- Scenario 1\n- Scenario 2\n- Scenario 3\n\n" + '## Scenario 1: first\n\nQuery: "Do the first task."\n\nExpected behavior:\n\n- Works.\n\n' + "Known failure modes:\n\n- Fails.\n\n" + '## Scenario 2: second\n\nQuery: "Do the second task."\n\nExpected behavior:\n\n- Works.\n\n' + "Known failure modes:\n\n- Fails.\n\n" + '## Scenario 3: third\n\nQuery: "Do the third task."\n\nExpected behavior:\n\n- Works.\n\n' + "Known failure modes:\n\n- Fails.\n", + encoding="utf-8", + ) + references = "- [Reference](reference.md)\n" + if audience == "user": + references += "- [Evaluations](evaluations.md)\n" + skill = skill_dir / "SKILL.md" + skill.write_text( + "---\n" + f"name: {name}\n" + "description: Tests Isaac Lab skill validation behavior. " + "Use when validating skill fixtures or testing skill rules.\n" + f"audience: {audience}\n" + "status: stable\n" + "owners:\n" + " - isaaclab-maintainers\n" + "---\n\n" + "# Example Skill\n\n" + "## When To Use\n\nUse for tests.\n\n" + "## Workflow\n\n1. Follow the test workflow.\n\n" + "## Validation\n\nRun the validator.\n\n" + "## Maintenance\n\nKeep this synchronized with test fixtures.\n\n" + "## References\n\n" + f"{references}", + encoding="utf-8", + ) + return skill + + +def test_validate_current_repo_skills(): + assert cli.validate_all() == [] + + +def test_validate_accepts_well_formed_user_skill(tmp_path): + skill = _write_skill(tmp_path) + assert cli.Skill(skill).validate() == [] + + +def test_validate_rejects_duplicate_names(tmp_path): + _write_skill(tmp_path, audience="user", name="isaaclab-duplicate-skill") + _write_skill(tmp_path, audience="developer", name="isaaclab-duplicate-skill") + errors = cli.validate_all(tmp_path) + assert any("duplicate skill name" in error for error in errors) + + +def test_validate_rejects_missing_required_section(tmp_path): + skill = _write_skill(tmp_path) + text = skill.read_text(encoding="utf-8").replace("## Validation\n\nRun the validator.\n\n", "") + skill.write_text(text, encoding="utf-8") + errors = cli.Skill(skill).validate() + assert any("missing required sections" in error for error in errors) + + +def test_validate_rejects_broken_link(tmp_path): + skill = _write_skill(tmp_path) + text = skill.read_text(encoding="utf-8").replace("[Reference](reference.md)", "[Reference](missing.md)") + skill.write_text(text, encoding="utf-8") + errors = cli.Skill(skill).validate() + assert any("broken link" in error for error in errors) + + +def test_validate_rejects_user_skill_without_three_evaluations(tmp_path): + skill = _write_skill(tmp_path) + (skill.parent / "evaluations.md").write_text( + "# Evaluations\n\n## Scenario 1: only\n\nExpected behavior:\n\n- Works.\n", + encoding="utf-8", + ) + errors = cli.Skill(skill).validate() + assert any("at least three evaluation scenarios" in error for error in errors) + + +def test_validate_rejects_user_skill_without_evaluation_details(tmp_path): + skill = _write_skill(tmp_path) + (skill.parent / "evaluations.md").write_text( + "# Evaluations\n\n" + "## Scenario 1: first\n\n- Works.\n\n" + "## Scenario 2: second\n\n- Works.\n\n" + "## Scenario 3: third\n\n- Works.\n", + encoding="utf-8", + ) + errors = cli.Skill(skill).validate() + assert any("sample query" in error for error in errors) + assert any("expected behavior" in error for error in errors) + assert any("known failure modes" in error for error in errors) + + +def test_validate_rejects_scenario_without_evaluation_details(tmp_path): + skill = _write_skill(tmp_path) + text = ( + (skill.parent / "evaluations.md") + .read_text(encoding="utf-8") + .replace( + '## Scenario 2: second\n\nQuery: "Do the second task."\n\nExpected behavior:\n\n- Works.\n\n' + "Known failure modes:\n\n- Fails.\n\n", + "## Scenario 2: second\n\n- Missing details.\n\n", + ) + ) + (skill.parent / "evaluations.md").write_text(text, encoding="utf-8") + errors = cli.Skill(skill).validate() + assert any("Scenario 2" in error and "sample query" in error for error in errors) + assert any("Scenario 2" in error and "expected behavior" in error for error in errors) + assert any("Scenario 2" in error and "known failure modes" in error for error in errors) + + +def test_validate_rejects_first_person_description(tmp_path): + skill = _write_skill(tmp_path) + text = skill.read_text(encoding="utf-8").replace( + "description: Tests Isaac Lab skill validation behavior. " + "Use when validating skill fixtures or testing skill rules.", + "description: I can help validate skills. Use when testing skill rules.", + ) + skill.write_text(text, encoding="utf-8") + errors = cli.Skill(skill).validate() + assert any("third person" in error for error in errors) + + +def test_validate_rejects_windows_paths(tmp_path): + skill = _write_skill(tmp_path) + text = skill.read_text(encoding="utf-8") + "\nUse scripts\\helper.py for this task.\n" + skill.write_text(text, encoding="utf-8") + errors = cli.Skill(skill).validate() + assert any("forward-slash paths" in error for error in errors) From 1f78c4d94d83c3cb1124b29c9ba2314bfb58ba6f Mon Sep 17 00:00:00 2001 From: Kelly Guo <kellyguo123@hotmail.com> Date: Sun, 24 May 2026 21:09:45 -0700 Subject: [PATCH 2/6] address feedback --- .github/workflows/skills-check.yml | 6 ++ .../overview/developer-guide/agent_skills.rst | 4 ++ docs/source/setup/ecosystem.rst | 1 - skills/README.md | 2 +- skills/user/create-environments/SKILL.md | 59 +++++++++++++++++++ .../user/create-environments/evaluations.md | 47 +++++++++++++++ skills/user/train-rl-agents/SKILL.md | 2 +- tools/skills/cli.py | 12 +++- tools/skills/test/test_validate.py | 25 ++++++++ 9 files changed, 152 insertions(+), 6 deletions(-) create mode 100644 skills/user/create-environments/SKILL.md create mode 100644 skills/user/create-environments/evaluations.md diff --git a/.github/workflows/skills-check.yml b/.github/workflows/skills-check.yml index 5e08df540c1c..c090561091a4 100644 --- a/.github/workflows/skills-check.yml +++ b/.github/workflows/skills-check.yml @@ -36,5 +36,11 @@ jobs: - name: Verify skills run: python3 tools/skills/cli.py check + - name: Install test dependencies + run: python3 -m pip install pytest + + - name: Test skills validator + run: python3 -m pytest tools/skills/ + - name: Compile skills validator run: python3 -m py_compile tools/skills/cli.py tools/skills/test/test_validate.py diff --git a/docs/source/overview/developer-guide/agent_skills.rst b/docs/source/overview/developer-guide/agent_skills.rst index 6af30df4aaf9..a07ff67815ab 100644 --- a/docs/source/overview/developer-guide/agent_skills.rst +++ b/docs/source/overview/developer-guide/agent_skills.rst @@ -73,6 +73,10 @@ Every skill must include a ``SKILL.md`` file with frontmatter: 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``. diff --git a/docs/source/setup/ecosystem.rst b/docs/source/setup/ecosystem.rst index 0b532af7db03..4ce71497b59b 100644 --- a/docs/source/setup/ecosystem.rst +++ b/docs/source/setup/ecosystem.rst @@ -209,7 +209,6 @@ contributing, please reach out to us. .. _AirSim: https://microsoft.github.io/AirSim/ .. _DoorGym: https://github.com/PSVL/DoorGym/ .. _ManiSkill: https://github.com/haosulab/ManiSkill -.. _ThreeDWorld: https://www.threedworld.org/ .. _RoboSuite: https://github.com/ARISE-Initiative/robosuite .. _MuJoCo: https://mujoco.org/ .. _MuJoCo Playground: https://playground.mujoco.org/ diff --git a/skills/README.md b/skills/README.md index b02731efe342..4f04070e7558 100644 --- a/skills/README.md +++ b/skills/README.md @@ -15,7 +15,7 @@ User skills: - `user/migrate-from-isaac-gym/`: migrate Isaac Gym tasks, assets, and training workflows to Isaac Lab. - `user/migrate-2x-to-3x/`: migrate Isaac Lab 2.x projects to Isaac Lab 3.0 using the official migration guide. - `user/domain-randomization-events/`: implement domain randomization through Isaac Lab event terms. -- `user/build-environments/`: create direct and manager-based Isaac Lab environments from task requirements. +- `user/create-environments/`: create direct and manager-based Isaac Lab environments from task requirements. - `user/train-rl-agents/`: configure and run Isaac Lab reinforcement learning workflows. - `user/use-sensors-actuators/`: add sensors, sensor observations, and actuator models to tasks. - `user/select-backends/`: choose and validate PhysX, Newton, and backend-specific task presets. diff --git a/skills/user/create-environments/SKILL.md b/skills/user/create-environments/SKILL.md new file mode 100644 index 000000000000..c7cd8101c169 --- /dev/null +++ b/skills/user/create-environments/SKILL.md @@ -0,0 +1,59 @@ +--- +name: isaaclab-building-environments +description: Builds Isaac Lab direct and manager-based environments from task requirements. Use when creating a new environment, choosing between direct and manager-based workflows, registering Gym environments, or adapting existing task examples. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Building Environments + +## When To Use + +Use this skill when a user wants to create a new Isaac Lab environment, choose the right task workflow, or adapt an existing task example. + +Do not use this skill for migrating Isaac Gym tasks. Use the `isaaclab-migrating-from-isaac-gym` skill when the source is an Isaac Gym or IsaacGymEnvs task. + +## Workflow + +1. Identify the task type, assets, action space, observation needs, rewards, resets, termination conditions, sensors, training framework, and target backend. +2. Read the task workflow overview and the relevant direct or manager-based tutorial before proposing code. +3. Choose direct workflow when the task needs custom control flow, close parity with a monolithic source task, or rapid prototyping. +4. Choose manager-based workflow when the task benefits from reusable observation, reward, command, event, termination, or curriculum terms. +5. Start from the closest maintained source example under `source/isaaclab_tasks/isaaclab_tasks/`. +6. Define the scene and asset configs before adding rewards or training configuration. +7. Add observations, actions, rewards, resets, and terminations incrementally. +8. Register the environment and connect the smallest compatible agent config. +9. Run a random-action or short training smoke test before scaling environment count. +10. Move reusable logic into shared MDP terms only after the behavior is stable. + +## Validation + +Check the environment in this order: + +1. Import the task module without launching a long training job. +2. Instantiate a small number of environments. +3. Reset and step with random actions. +4. Verify action, observation, reward, reset, and termination shapes. +5. Run a short training command only after the smoke test passes. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `docs/source/overview/core-concepts/task_workflows.rst`, the environment tutorials under `docs/source/tutorials/03_envs/`, and maintained task examples under `source/isaaclab_tasks/isaaclab_tasks/`. If workflow documentation is missing or stale, update the docs or examples first and keep this skill focused on choosing the right path. + +## References + +- [Evaluations](evaluations.md) +- [Task workflows](../../../docs/source/overview/core-concepts/task_workflows.rst) +- [Create direct workflow environment tutorial](../../../docs/source/tutorials/03_envs/create_direct_rl_env.rst) +- [Modify direct workflow environment tutorial](../../../docs/source/tutorials/03_envs/modify_direct_rl_env.rst) +- [Create manager-based base environment tutorial](../../../docs/source/tutorials/03_envs/create_manager_base_env.rst) +- [Create manager-based RL environment tutorial](../../../docs/source/tutorials/03_envs/create_manager_rl_env.rst) +- [Register Gym environment tutorial](../../../docs/source/tutorials/03_envs/register_rl_env_gym.rst) diff --git a/skills/user/create-environments/evaluations.md b/skills/user/create-environments/evaluations.md new file mode 100644 index 000000000000..e3b5a376163f --- /dev/null +++ b/skills/user/create-environments/evaluations.md @@ -0,0 +1,47 @@ +# Environment Building Evaluations + +## Scenario 1: Choose A Workflow + +Query: "I want to build a quadruped locomotion task with custom command sampling and custom rewards." + +Expected behavior: + +- Asks for assets, actions, observations, rewards, reset conditions, sensors, and backend targets. +- Recommends direct workflow first if custom control flow is central to the task. +- Points to maintained locomotion examples and direct environment tutorials. +- Defines a smoke-test plan before training. + +Known failure modes: + +- Starts from manager terms without preserving the requested custom task behavior. +- Copies tutorial code without checking the task's action and observation requirements. + +## Scenario 2: Build A Manager-Based Task + +Query: "Create a reusable reaching task where observations and rewards should be reusable across robot arms." + +Expected behavior: + +- Recommends manager-based workflow because observations and rewards are reusable. +- Maps task pieces to scene, observation, action, command, reward, termination, event, and curriculum configs. +- Points to manager-based tutorials and source examples. + +Known failure modes: + +- Implements all behavior in a direct environment even though reuse is the user's main requirement. +- Adds custom abstractions before checking existing MDP terms. + +## Scenario 3: Register And Train + +Query: "I created a new environment config and need to train it with Gym registration." + +Expected behavior: + +- Points to the Gym registration and RL training tutorials. +- Verifies the environment imports, resets, and steps before training. +- Checks that the agent config matches the selected training framework. + +Known failure modes: + +- Starts a large training run before checking reset and step behavior. +- Mixes agent config formats from different RL frameworks. diff --git a/skills/user/train-rl-agents/SKILL.md b/skills/user/train-rl-agents/SKILL.md index 2ad05b06994e..9d625a48d202 100644 --- a/skills/user/train-rl-agents/SKILL.md +++ b/skills/user/train-rl-agents/SKILL.md @@ -13,7 +13,7 @@ owners: Use this skill when a user wants to train, resume, evaluate, or configure reinforcement learning for an Isaac Lab task. -Do not use this skill to design environment observations, rewards, or resets from scratch. Use `isaaclab-building-environments` (`skills/user/build-environments/`) for environment construction first. +Do not use this skill to design environment observations, rewards, or resets from scratch. Use `isaaclab-building-environments` (`skills/user/create-environments/`) for environment construction first. ## Workflow diff --git a/tools/skills/cli.py b/tools/skills/cli.py index 66a04a75e82d..bbe7b5ae03a9 100644 --- a/tools/skills/cli.py +++ b/tools/skills/cli.py @@ -32,7 +32,7 @@ BACKTICK_PATH_RE = re.compile(r"`(?P<path>(?:docs|source|scripts|skills|tools|\.github)/[^`\s]+)`") XML_TAG_RE = re.compile(r"<[^>]+>") WINDOWS_PATH_RE = re.compile(r"(?<!`)[A-Za-z0-9_.-]+\\[A-Za-z0-9_.-]+") -SCENARIO_RE = re.compile(r"^#{2,3} Scenario\b", re.MULTILINE) +SCENARIO_RE = re.compile(r"^#{2,3} (?P<title>Scenario\b.*)$", re.MULTILINE) GENERIC_NAME_PARTS = {"helper", "helpers", "utils", "tools"} @@ -86,6 +86,8 @@ def _parse_frontmatter(text: str) -> tuple[dict[str, str | list[str]], str, str value = value.strip() if not key: return data, "\n".join(lines[end + 1 :]), "empty frontmatter key" + if value in {"|", ">"}: + return data, "\n".join(lines[end + 1 :]), f"unsupported block scalar for {key!r}" if value: data[key] = value.strip("\"'") else: @@ -249,7 +251,11 @@ def _validate_user_evaluations(self, body: str) -> list[str]: if not evaluations.exists(): errors.append(f"{_display_path(self.path)}: user-facing skills must include evaluations.md") return errors - if "evaluations.md" not in body: + has_evaluations_link = any( + unquote(match.group("target").strip().split("#", 1)[0]) == "evaluations.md" + for match in LINK_RE.finditer(body) + ) + if not has_evaluations_link: errors.append(f"{_display_path(self.path)}: user-facing skills must link to evaluations.md from SKILL.md") text = evaluations.read_text(encoding="utf-8") scenario_matches = list(SCENARIO_RE.finditer(text)) @@ -258,7 +264,7 @@ def _validate_user_evaluations(self, body: str) -> list[str]: for index, match in enumerate(scenario_matches, start=1): next_match = scenario_matches[index] if index < len(scenario_matches) else None scenario_text = text[match.start() : next_match.start() if next_match else len(text)] - scenario_name = match.group(0).strip("# ") + scenario_name = match.group("title").strip() if "Query:" not in scenario_text: errors.append(f"{_display_path(evaluations)}: {scenario_name} must include a sample query") if "Expected behavior:" not in scenario_text: diff --git a/tools/skills/test/test_validate.py b/tools/skills/test/test_validate.py index 2ae6f1e845ed..3e41eb25b675 100644 --- a/tools/skills/test/test_validate.py +++ b/tools/skills/test/test_validate.py @@ -96,6 +96,17 @@ def test_validate_rejects_user_skill_without_three_evaluations(tmp_path): assert any("at least three evaluation scenarios" in error for error in errors) +def test_validate_rejects_user_skill_without_evaluations_link(tmp_path): + skill = _write_skill(tmp_path) + text = skill.read_text(encoding="utf-8").replace( + "- [Evaluations](evaluations.md)\n", + "Mention evaluations.md in prose without linking it.\n", + ) + skill.write_text(text, encoding="utf-8") + errors = cli.Skill(skill).validate() + assert any("must link to evaluations.md" in error for error in errors) + + def test_validate_rejects_user_skill_without_evaluation_details(tmp_path): skill = _write_skill(tmp_path) (skill.parent / "evaluations.md").write_text( @@ -129,6 +140,20 @@ def test_validate_rejects_scenario_without_evaluation_details(tmp_path): assert any("Scenario 2" in error and "known failure modes" in error for error in errors) +def test_validate_rejects_frontmatter_block_scalars(tmp_path): + skill = _write_skill(tmp_path) + text = skill.read_text(encoding="utf-8").replace( + "description: Tests Isaac Lab skill validation behavior. " + "Use when validating skill fixtures or testing skill rules.\n", + "description: |\n" + " Tests Isaac Lab skill validation behavior. " + "Use when validating skill fixtures or testing skill rules.\n", + ) + skill.write_text(text, encoding="utf-8") + errors = cli.Skill(skill).validate() + assert any("unsupported block scalar" in error for error in errors) + + def test_validate_rejects_first_person_description(tmp_path): skill = _write_skill(tmp_path) text = skill.read_text(encoding="utf-8").replace( From 6ff9f187a85de7bdcf899196a6dafee0da9d238b Mon Sep 17 00:00:00 2001 From: Kelly Guo <kellyguo123@hotmail.com> Date: Sun, 24 May 2026 21:21:17 -0700 Subject: [PATCH 3/6] address feedback --- .../overview/developer-guide/agent_skills.rst | 10 +++ skills/README.md | 4 ++ skills/user/create-environments/SKILL.md | 1 + skills/user/create-environments/examples.md | 52 +++++++++++++++ skills/user/select-backends/SKILL.md | 1 + skills/user/select-backends/evaluations.md | 17 +++++ skills/user/select-backends/examples.md | 44 +++++++++++++ skills/user/setup-troubleshooting/SKILL.md | 1 + .../user/setup-troubleshooting/evaluations.md | 17 +++++ .../user/setup-troubleshooting/reference.md | 65 +++++++++++++++++++ skills/user/train-rl-agents/SKILL.md | 1 + skills/user/train-rl-agents/evaluations.md | 17 +++++ skills/user/train-rl-agents/examples.md | 62 ++++++++++++++++++ skills/user/use-sensors-actuators/SKILL.md | 1 + .../user/use-sensors-actuators/evaluations.md | 17 +++++ skills/user/use-sensors-actuators/examples.md | 63 ++++++++++++++++++ 16 files changed, 373 insertions(+) create mode 100644 skills/user/create-environments/examples.md create mode 100644 skills/user/select-backends/examples.md create mode 100644 skills/user/setup-troubleshooting/reference.md create mode 100644 skills/user/train-rl-agents/examples.md create mode 100644 skills/user/use-sensors-actuators/examples.md diff --git a/docs/source/overview/developer-guide/agent_skills.rst b/docs/source/overview/developer-guide/agent_skills.rst index a07ff67815ab..54e03a597444 100644 --- a/docs/source/overview/developer-guide/agent_skills.rst +++ b/docs/source/overview/developer-guide/agent_skills.rst @@ -57,6 +57,16 @@ Skill files - Optional - Deterministic helpers with explicit run-or-read instructions. +Discovery +--------- + +Agents should use ``skills/README.md`` as the catalog for repo-owned skills. +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 file locations for humans and reviewers; the +frontmatter ``name`` is the stable identifier to use when one skill routes to +another. + Skill contract -------------- diff --git a/skills/README.md b/skills/README.md index 4f04070e7558..22f3457fa1ba 100644 --- a/skills/README.md +++ b/skills/README.md @@ -25,6 +25,10 @@ Planned user skills: - `user/import-robot-urdf-mjcf/` +## Discovery + +Agents should start at this file when looking for repo-owned skills. Match the user's request against each `SKILL.md` frontmatter `description`, then read only the selected skill and its directly linked files. When one skill routes to another, use the frontmatter `name` as the stable identifier and the catalog path as the file location. + ## Authoring Rules Every skill directory must contain a `SKILL.md` file with frontmatter: diff --git a/skills/user/create-environments/SKILL.md b/skills/user/create-environments/SKILL.md index c7cd8101c169..c546f21ce5e2 100644 --- a/skills/user/create-environments/SKILL.md +++ b/skills/user/create-environments/SKILL.md @@ -51,6 +51,7 @@ Keep this skill synchronized with `docs/source/overview/core-concepts/task_workf ## References - [Evaluations](evaluations.md) +- [Examples](examples.md) - [Task workflows](../../../docs/source/overview/core-concepts/task_workflows.rst) - [Create direct workflow environment tutorial](../../../docs/source/tutorials/03_envs/create_direct_rl_env.rst) - [Modify direct workflow environment tutorial](../../../docs/source/tutorials/03_envs/modify_direct_rl_env.rst) diff --git a/skills/user/create-environments/examples.md b/skills/user/create-environments/examples.md new file mode 100644 index 000000000000..3d1dcaad8cd4 --- /dev/null +++ b/skills/user/create-environments/examples.md @@ -0,0 +1,52 @@ +# Environment Creation Examples + +## Direct Workflow + +Use direct workflow when the task has custom step logic or is being migrated from a monolithic task. + +Start from: + +- `docs/source/tutorials/03_envs/create_direct_rl_env.rst` +- `source/isaaclab_tasks/isaaclab_tasks/direct/` + +Smoke-test pattern: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-Direct-v0 --num_envs 8 +``` + +Training pattern: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/rl_games/train.py --task Isaac-Cartpole-Direct-v0 --headless +``` + +## Manager-Based Workflow + +Use manager-based workflow when observations, rewards, commands, events, or terminations should be reusable. + +Start from: + +- `docs/source/tutorials/03_envs/create_manager_base_env.rst` +- `docs/source/tutorials/03_envs/create_manager_rl_env.rst` +- `source/isaaclab_tasks/isaaclab_tasks/manager_based/` + +Smoke-test pattern: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 8 +``` + +## Registration And Agent Configs + +When adding a new Gym task: + +1. Register the task with an `env_cfg_entry_point`. +2. Add one agent config entry point per supported RL framework. +3. Run `random_agent.py` before training. +4. Train only after action, observation, reward, reset, and termination shapes are stable. + +Reference: + +- `docs/source/tutorials/03_envs/register_rl_env_gym.rst` +- `docs/source/tutorials/03_envs/configuring_rl_training.rst` diff --git a/skills/user/select-backends/SKILL.md b/skills/user/select-backends/SKILL.md index 3bca7c3216ae..59c9151148d1 100644 --- a/skills/user/select-backends/SKILL.md +++ b/skills/user/select-backends/SKILL.md @@ -50,6 +50,7 @@ Keep this skill synchronized with `docs/source/overview/core-concepts/multi_back ## References - [Evaluations](evaluations.md) +- [Examples](examples.md) - [Multi-backend architecture](../../../docs/source/overview/core-concepts/multi_backend_architecture.rst) - [Schema cfgs](../../../docs/source/overview/core-concepts/schema_cfgs.rst) - [PhysX installation](../../../docs/source/overview/core-concepts/physical-backends/physx/installation.rst) diff --git a/skills/user/select-backends/evaluations.md b/skills/user/select-backends/evaluations.md index cbfc535428a9..2e8cd050d7bf 100644 --- a/skills/user/select-backends/evaluations.md +++ b/skills/user/select-backends/evaluations.md @@ -44,3 +44,20 @@ Known failure modes: - Treats all visual failures as physics backend bugs. - Ignores renderer and app-launch requirements. + +## Scenario 4: Concrete Backend Smoke Test + +Query: "Give me a command to check whether my Ant task runs on Newton before training." + +Expected behavior: + +- Starts by listing or checking available presets for the task. +- Uses a small `random_agent.py` rollout with a `physics=...` selector. +- Warns not to guess preset names that are not exposed by the task. +- Recommends repeating the same smoke test on PhysX for comparison. + +Known failure modes: + +- Starts training before reset/step validation. +- Invents backend selector names without checking task presets. +- Treats Newton and PhysX contact behavior as directly comparable without validation. diff --git a/skills/user/select-backends/examples.md b/skills/user/select-backends/examples.md new file mode 100644 index 000000000000..a91d169e82f6 --- /dev/null +++ b/skills/user/select-backends/examples.md @@ -0,0 +1,44 @@ +# Backend Selection Examples + +## List Available Presets + +Start by checking which preset selectors the task exposes: + +```bash +./isaaclab.sh -p scripts/environments/list_envs.py --show_presets +``` + +Preset selectors are typed tokens such as `physics=NAME`, `renderer=NAME`, and `presets=NAME`. + +## Smoke Test A Backend + +Use a small random-agent rollout before training: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Ant-v0 --num_envs 4 physics=physx +``` + +For Newton, use the physics preset name exposed by `list_envs.py` for that task, for example: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Ant-v0 --num_envs 4 physics=newton_mjwarp +``` + +If the preset name is not listed, do not guess. Add or update the task's backend presets first. + +## Train After Smoke Tests + +Once reset/step behavior is stable on the selected backend: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Ant-v0 --headless physics=physx +``` + +Repeat the same small smoke test on every backend before comparing training curves. + +## Common Decision Points + +- Use PhysX first when preserving Isaac Gym behavior. +- Use Newton when the task specifically targets kit-less or Warp-native workflows. +- Use backend presets for solver, contact, material, sensor, and renderer differences. +- Do not copy PhysX parameters directly into Newton configs without checking schema docs. diff --git a/skills/user/setup-troubleshooting/SKILL.md b/skills/user/setup-troubleshooting/SKILL.md index a0d0dd26c8b4..c13d30e9558e 100644 --- a/skills/user/setup-troubleshooting/SKILL.md +++ b/skills/user/setup-troubleshooting/SKILL.md @@ -49,6 +49,7 @@ Keep this skill synchronized with installation docs under `docs/source/setup/ins ## References - [Evaluations](evaluations.md) +- [Reference](reference.md) - [Quick installation](../../../docs/source/setup/quick_installation.rst) - [Source installation](../../../docs/source/setup/installation/source_installation.rst) - [Pip installation](../../../docs/source/setup/installation/pip_installation.rst) diff --git a/skills/user/setup-troubleshooting/evaluations.md b/skills/user/setup-troubleshooting/evaluations.md index 61b1808cc8d9..2f77d774c854 100644 --- a/skills/user/setup-troubleshooting/evaluations.md +++ b/skills/user/setup-troubleshooting/evaluations.md @@ -44,3 +44,20 @@ Known failure modes: - Treats backend setup as a task bug. - Gives backend-specific commands without checking the docs. + +## Scenario 4: Minimal Reproduction + +Query: "Training fails with an import error after install. What should I run first?" + +Expected behavior: + +- Asks for the exact command and traceback. +- Verifies the active install path and Python wrapper. +- Uses the minimal import command from `reference.md`. +- Escalates to random-agent or training checks only after imports work. + +Known failure modes: + +- Recommends reinstalling before checking the active Python environment. +- Starts debugging the training runner before validating imports. +- Ignores the official troubleshooting page. diff --git a/skills/user/setup-troubleshooting/reference.md b/skills/user/setup-troubleshooting/reference.md new file mode 100644 index 000000000000..6895ff065828 --- /dev/null +++ b/skills/user/setup-troubleshooting/reference.md @@ -0,0 +1,65 @@ +# Setup Troubleshooting Reference + +## Contents + +- Install path routing +- Minimal verification +- Common failure routing +- Escalation checklist + +## Install Path Routing + +Ask which install path the user is following before prescribing commands: + +| User context | First reference | +| --- | --- | +| Source checkout | `docs/source/setup/installation/source_installation.rst` | +| Pip package | `docs/source/setup/installation/pip_installation.rst` | +| Isaac Lab pip package | `docs/source/setup/installation/isaaclab_pip_installation.rst` | +| Binary package | `docs/source/setup/installation/binaries_installation.rst` | +| Cloud setup | `docs/source/setup/installation/cloud_installation.rst` | +| Kit-less setup | `docs/source/setup/installation/kitless_installation.rst` | +| Newton setup | `docs/source/overview/core-concepts/physical-backends/newton/installation.rst` | +| PhysX setup | `docs/source/overview/core-concepts/physical-backends/physx/installation.rst` | + +## Minimal Verification + +Use the smallest command that exercises the failing layer: + +```bash +./isaaclab.sh -p -c "import isaaclab; print('ok')" +``` + +For task import and stepping: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 4 +``` + +For training entry points: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --headless --max_iterations 1 +``` + +## Common Failure Routing + +| Symptom | First check | +| --- | --- | +| Import fails | Active Python environment and wrapper usage | +| App launch fails | Isaac Sim, display, driver, and launcher docs | +| Task registration fails | Gym registration and task package import | +| Backend preset fails | `scripts/environments/list_envs.py --show_presets` | +| Camera or renderer fails | Renderer selection and sensor docs | +| Training starts but shapes fail | Environment reset/step smoke test before runner | + +## Escalation Checklist + +Before suggesting broad reinstall steps: + +1. Capture the exact command and traceback. +2. Confirm the install path and Python executable. +3. Run a minimal import check. +4. Run a small random-agent task check. +5. Check `docs/source/refs/troubleshooting.rst`. +6. Escalate only after the documented checks do not match the failure. diff --git a/skills/user/train-rl-agents/SKILL.md b/skills/user/train-rl-agents/SKILL.md index 9d625a48d202..8d623193d6b6 100644 --- a/skills/user/train-rl-agents/SKILL.md +++ b/skills/user/train-rl-agents/SKILL.md @@ -50,6 +50,7 @@ Keep this skill synchronized with `docs/source/overview/reinforcement-learning/t ## References - [Evaluations](evaluations.md) +- [Examples](examples.md) - [RL training guide](../../../docs/source/overview/reinforcement-learning/training_guide.rst) - [Configure RL training tutorial](../../../docs/source/tutorials/03_envs/configuring_rl_training.rst) - [Run RL training tutorial](../../../docs/source/tutorials/03_envs/run_rl_training.rst) diff --git a/skills/user/train-rl-agents/evaluations.md b/skills/user/train-rl-agents/evaluations.md index f4e26300a17f..ebd9dc686fde 100644 --- a/skills/user/train-rl-agents/evaluations.md +++ b/skills/user/train-rl-agents/evaluations.md @@ -44,3 +44,20 @@ Known failure modes: - Treats camera observations like low-dimensional state without checking rendering requirements. - Ignores GPU memory and renderer constraints. + +## Scenario 4: Concrete RSL-RL Command + +Query: "How do I train Cartpole with RSL-RL?" + +Expected behavior: + +- Gives the RSL-RL command from `examples.md`. +- Mentions the matching Cartpole agent config location. +- Suggests a random-agent smoke test before training if the environment was just modified. +- Explains where logs/checkpoints are written instead of sending the user hunting through docs. + +Known failure modes: + +- Answers only with a link to the training guide. +- Uses the SB3 command for an RSL-RL request. +- Omits `./isaaclab.sh -p`. diff --git a/skills/user/train-rl-agents/examples.md b/skills/user/train-rl-agents/examples.md new file mode 100644 index 000000000000..cf03840d24a1 --- /dev/null +++ b/skills/user/train-rl-agents/examples.md @@ -0,0 +1,62 @@ +# RL Training Examples + +## Quick Commands + +Use these as starting points, then confirm the task's registered agent config exists. + +RSL-RL: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --headless --run_name ppo +``` + +RL-Games direct Cartpole: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/rl_games/train.py --task Isaac-Cartpole-Direct-v0 --headless +``` + +Stable Baselines 3: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/sb3/train.py --task Isaac-Cartpole-v0 --num_envs 64 +``` + +SKRL: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/skrl/train.py --task Isaac-Cartpole-v0 --headless +``` + +## Before Training + +Always run a small random-action check first: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 8 +``` + +For visual observations or camera tasks, lower `--num_envs` and confirm renderer and sensor support before scaling. + +## After Training + +TensorBoard example: + +```bash +./isaaclab.sh -p -m tensorboard.main --logdir logs/rsl_rl/cartpole +``` + +Play example: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/play.py --task Isaac-Cartpole-v0 --use_last_checkpoint --viz kit +``` + +## Config Lookup + +Agent configs live near the task implementation, for example: + +- `source/isaaclab_tasks/isaaclab_tasks/manager_based/classic/cartpole/agents/` +- `source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/agents/` + +Do not mix framework formats: RSL-RL configs are Python classes, while RL-Games, SKRL, and SB3 commonly use YAML or framework-specific config files. diff --git a/skills/user/use-sensors-actuators/SKILL.md b/skills/user/use-sensors-actuators/SKILL.md index 4dde2c79634a..6b4c418cea6d 100644 --- a/skills/user/use-sensors-actuators/SKILL.md +++ b/skills/user/use-sensors-actuators/SKILL.md @@ -51,6 +51,7 @@ Keep this skill synchronized with sensor and actuator docs under `docs/source/ov ## References - [Evaluations](evaluations.md) +- [Examples](examples.md) - [Add sensors on robot tutorial](../../../docs/source/tutorials/04_sensors/add_sensors_on_robot.rst) - [Contact sensor docs](../../../docs/source/overview/core-concepts/sensors/contact_sensor.rst) - [Joint wrench sensor docs](../../../docs/source/overview/core-concepts/sensors/joint_wrench_sensor.rst) diff --git a/skills/user/use-sensors-actuators/evaluations.md b/skills/user/use-sensors-actuators/evaluations.md index 0e3c7e1207c8..7052cdb6ae2b 100644 --- a/skills/user/use-sensors-actuators/evaluations.md +++ b/skills/user/use-sensors-actuators/evaluations.md @@ -44,3 +44,20 @@ Known failure modes: - Changes actuator type without checking joint names and limits. - Treats actuator behavior as independent of physics backend. + +## Scenario 4: Camera Observation + +Query: "Add image observations to Cartpole training." + +Expected behavior: + +- Points to camera-enabled Cartpole examples and sensor docs. +- Checks renderer requirements, data types, image size, and memory cost. +- Recommends a small environment count before training. +- Verifies the observation shape and framework support before changing agent configs. + +Known failure modes: + +- Adds camera tensors to observations without enabling a compatible renderer. +- Starts with thousands of environments before validating memory usage. +- Ignores whether the selected RL framework can consume the observation space. diff --git a/skills/user/use-sensors-actuators/examples.md b/skills/user/use-sensors-actuators/examples.md new file mode 100644 index 000000000000..9d660821ef00 --- /dev/null +++ b/skills/user/use-sensors-actuators/examples.md @@ -0,0 +1,63 @@ +# Sensors And Actuators Examples + +## Contact Sensors + +Use contact sensors for feet air time, undesired contacts, grasp checks, and termination conditions. + +Examples to inspect: + +- `source/isaaclab_tasks/isaaclab_tasks/direct/anymal_c/anymal_c_env_cfg.py` +- `source/isaaclab_tasks/isaaclab_tasks/manager_based/locomotion/velocity/velocity_env_cfg.py` + +Validation checklist: + +- Body name patterns match the asset. +- `history_length` is sufficient for the reward or termination term. +- Sensor update period matches the control and simulation step. +- Contact data shape is checked before adding observations or rewards. + +## Ray-Cast Height Scanners + +Use ray casters for terrain perception on rough locomotion tasks. + +Examples to inspect: + +- `source/isaaclab_tasks/isaaclab_tasks/direct/anymal_c/anymal_c_env_cfg.py` +- `source/isaaclab_tasks/isaaclab_tasks/manager_based/locomotion/velocity/velocity_env_cfg.py` + +Validation checklist: + +- The scanner is mounted on the intended robot body. +- `mesh_prim_paths` points to the terrain mesh. +- Observation dimensions are updated for the ray pattern. +- Flat-terrain configs remove or disable height scan observations. + +## Cameras + +Use camera or tiled-camera examples before adding visual observations to training. + +Examples to inspect: + +- `source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_camera_presets_env_cfg.py` +- `docs/source/tutorials/04_sensors/add_sensors_on_robot.rst` + +Validation checklist: + +- Renderer requirements are met. +- Data types and image sizes fit memory limits. +- Training starts with a small number of environments. + +## Actuators + +Use actuator configs in robot assets or task overrides, then validate joint names and limits. + +Examples to inspect: + +- `source/isaaclab_tasks/isaaclab_tasks/direct/shadow_hand/shadow_hand_env_cfg.py` +- `source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation/cabinet/cabinet_env_cfg.py` + +Validation checklist: + +- `joint_names_expr` matches the intended joints. +- Effort, velocity, stiffness, damping, and armature are compatible with the robot. +- Backend-specific behavior is checked before adding presets. From 70215f9a7da191fcdc4fdc9c2c7475be79272398 Mon Sep 17 00:00:00 2001 From: Kelly Guo <kellyguo123@hotmail.com> Date: Sun, 24 May 2026 21:38:42 -0700 Subject: [PATCH 4/6] add presets skills --- docs/source/refs/troubleshooting.rst | 27 +++++ skills/README.md | 21 ++++ .../domain-randomization-events/examples.md | 49 ++++++++ .../user/setup-troubleshooting/reference.md | 1 + skills/user/train-rl-agents/examples.md | 8 +- skills/user/use-presets/SKILL.md | 62 ++++++++++ skills/user/use-presets/evaluations.md | 65 +++++++++++ skills/user/use-presets/examples.md | 109 ++++++++++++++++++ skills/user/use-presets/reference.md | 81 +++++++++++++ 9 files changed, 422 insertions(+), 1 deletion(-) create mode 100644 skills/user/use-presets/SKILL.md create mode 100644 skills/user/use-presets/evaluations.md create mode 100644 skills/user/use-presets/examples.md create mode 100644 skills/user/use-presets/reference.md diff --git a/docs/source/refs/troubleshooting.rst b/docs/source/refs/troubleshooting.rst index 3c40fcda85df..a79182a4d65f 100644 --- a/docs/source/refs/troubleshooting.rst +++ b/docs/source/refs/troubleshooting.rst @@ -41,6 +41,33 @@ packages. Include ``assets`` in your install command, or use ``./isaaclab.sh -i`` to install everything. +``ModuleNotFoundError: No module named 'isaaclab_tasks'`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``isaaclab_tasks`` package contains the registered task environments. This +error usually means the command is not running in the Isaac Lab Python +environment or the repository packages were not installed in editable mode. + +Try the following checks: + +1. Run from the Isaac Lab repository root using the wrapper: + + .. code-block:: bash + + ./isaaclab.sh -p -c "import isaaclab_tasks; print('ok')" + +2. If the import still fails, install the repository packages: + + .. code-block:: bash + + ./isaaclab.sh -i + +3. Re-run the task command through the wrapper instead of a system Python: + + .. code-block:: bash + + ./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 4 + ``ModuleNotFoundError: No module named 'rsl_rl'`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/skills/README.md b/skills/README.md index 22f3457fa1ba..f317f8c819ee 100644 --- a/skills/README.md +++ b/skills/README.md @@ -19,6 +19,7 @@ User skills: - `user/train-rl-agents/`: configure and run Isaac Lab reinforcement learning workflows. - `user/use-sensors-actuators/`: add sensors, sensor observations, and actuator models to tasks. - `user/select-backends/`: choose and validate PhysX, Newton, and backend-specific task presets. +- `user/use-presets/`: define and use preset configurations for multi-backend and variant-rich tasks. - `user/setup-troubleshooting/`: route installation, verification, and setup issues to official docs and canonical commands. Planned user skills: @@ -29,6 +30,26 @@ Planned user skills: Agents should start at this file when looking for repo-owned skills. Match the user's request against each `SKILL.md` frontmatter `description`, then read only the selected skill and its directly linked files. When one skill routes to another, use the frontmatter `name` as the stable identifier and the catalog path as the file location. +## Common Import Paths + +Use these current import paths before searching for alternatives: + +| Concept | Import path | +| --- | --- | +| Direct RL environment config | `from isaaclab.envs import DirectRLEnvCfg` | +| Direct multi-agent environment config | `from isaaclab.envs import DirectMARLEnvCfg` | +| Manager-based RL environment config | `from isaaclab.envs import ManagerBasedRLEnvCfg` | +| Event term config | `from isaaclab.managers import EventTermCfg as EventTerm` | +| Scene entity config | `from isaaclab.managers import SceneEntityCfg` | +| Preset config | `from isaaclab_tasks.utils import PresetCfg` | +| Simulation config | `from isaaclab.sim import SimulationCfg` | +| PhysX physics config | `from isaaclab_physx.physics import PhysxCfg` | +| Newton physics config | `from isaaclab_newton.physics import NewtonCfg` | +| Contact sensor config | `from isaaclab.sensors import ContactSensorCfg` | +| Ray caster config | `from isaaclab.sensors import RayCasterCfg` | +| Tiled camera config | `from isaaclab.sensors import TiledCameraCfg` | +| Implicit actuator config | `from isaaclab.actuators import ImplicitActuatorCfg` | + ## Authoring Rules Every skill directory must contain a `SKILL.md` file with frontmatter: diff --git a/skills/user/domain-randomization-events/examples.md b/skills/user/domain-randomization-events/examples.md index b127fcda191e..4010eb0818e1 100644 --- a/skills/user/domain-randomization-events/examples.md +++ b/skills/user/domain-randomization-events/examples.md @@ -71,3 +71,52 @@ Expected setup: - Use PhysX buckets and static/dynamic friction ranges for the PhysX preset. - Use Newton's single friction coefficient behavior for the Newton preset. - Do not assume `dynamic_friction_range`, `num_buckets`, or CPU/GPU behavior are identical across backends. + +Pattern: + +```python +import isaaclab.envs.mdp as mdp +from isaaclab.managers import EventTermCfg as EventTerm +from isaaclab.managers import SceneEntityCfg +from isaaclab.utils.configclass import configclass +from isaaclab_tasks.utils import PresetCfg + + +@configclass +class PhysxEventCfg: + physics_material = EventTerm( + func=mdp.randomize_rigid_body_material, + mode="startup", + params={ + "asset_cfg": SceneEntityCfg("robot", body_names=".*"), + "static_friction_range": (0.6, 1.2), + "dynamic_friction_range": (0.5, 1.0), + "restitution_range": (0.0, 0.1), + "num_buckets": 64, + }, + ) + + +@configclass +class NewtonEventCfg: + physics_material = EventTerm( + func=mdp.randomize_rigid_body_material, + mode="startup", + params={ + "asset_cfg": SceneEntityCfg("robot", body_names=".*"), + "static_friction_range": (0.6, 1.2), + "dynamic_friction_range": (0.6, 1.2), + "restitution_range": (0.0, 0.1), + "num_buckets": 1, + }, + ) + + +@configclass +class EventCfg(PresetCfg): + default = PhysxEventCfg() + physx = PhysxEventCfg() + newton_mjwarp = NewtonEventCfg() +``` + +Then assign `events: EventCfg = EventCfg()` on the environment config. Verify the exact event parameters against `source/isaaclab/isaaclab/envs/mdp/events.py` before using this pattern. diff --git a/skills/user/setup-troubleshooting/reference.md b/skills/user/setup-troubleshooting/reference.md index 6895ff065828..497f37afb544 100644 --- a/skills/user/setup-troubleshooting/reference.md +++ b/skills/user/setup-troubleshooting/reference.md @@ -47,6 +47,7 @@ For training entry points: | Symptom | First check | | --- | --- | | Import fails | Active Python environment and wrapper usage | +| `isaaclab_tasks` import fails | Run through `./isaaclab.sh -p`, then re-run `./isaaclab.sh -i` if needed | | App launch fails | Isaac Sim, display, driver, and launcher docs | | Task registration fails | Gym registration and task package import | | Backend preset fails | `scripts/environments/list_envs.py --show_presets` | diff --git a/skills/user/train-rl-agents/examples.md b/skills/user/train-rl-agents/examples.md index cf03840d24a1..c4307ffa0007 100644 --- a/skills/user/train-rl-agents/examples.md +++ b/skills/user/train-rl-agents/examples.md @@ -49,7 +49,13 @@ TensorBoard example: Play example: ```bash -./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/play.py --task Isaac-Cartpole-v0 --use_last_checkpoint --viz kit +./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/play.py --task Isaac-Cartpole-v0 --checkpoint logs/rsl_rl/cartpole/RUN_NAME/model_100.pt --viz kit +``` + +Resume example: + +```bash +./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --headless --resume --load_run RUN_NAME --checkpoint model_100.pt ``` ## Config Lookup diff --git a/skills/user/use-presets/SKILL.md b/skills/user/use-presets/SKILL.md new file mode 100644 index 000000000000..8ff64d7b6a94 --- /dev/null +++ b/skills/user/use-presets/SKILL.md @@ -0,0 +1,62 @@ +--- +name: isaaclab-using-presets +description: Defines and uses Isaac Lab preset configurations for multi-backend tasks. Use when adding PhysX/Newton variants, renderer variants, domain presets, or deciding whether a task needs PresetCfg. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Using Presets + +## When To Use + +Use this skill when a user needs to define, select, or debug Isaac Lab `PresetCfg` variants for environments, physics backends, renderers, sensors, events, or task-specific configuration options. + +Do not use presets for simple one-backend tasks with no meaningful configuration variants. Prefer a plain config until the task needs a real selectable alternative. + +## Workflow + +1. Identify whether the task needs variants. Common reasons are physics backend differences, renderer differences, camera data types, event randomization differences, or play/train variants. +2. If there is only one supported behavior, keep the config simple and do not add `PresetCfg`. +3. If variants are needed, choose the selector category: + - Use a `PhysicsCfg(PresetCfg)` field for physics backend variants selected by `physics=NAME`. + - Use a renderer preset for renderer variants selected by `renderer=NAME`. + - Use task/domain presets for environment-specific variants selected by `presets=NAME[,NAME,...]`. +4. Define a `default` variant. Add explicit named variants such as `physx`, `newton_mjwarp`, `newton_kamino`, `ovphysx`, `rgb`, or `depth` only when the task supports them. +5. Assign the preset wrapper to the owning environment config field, for example `sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg())`. +6. Keep backend-specific values inside preset classes rather than scattering runtime conditionals through task logic. +7. List available preset names before using them in commands. +8. Smoke-test every preset with a small random-agent rollout before training. + +## Validation + +Use this checklist: + +1. Confirm a plain config would not be sufficient. +2. Confirm every preset variant has a clear reason to exist. +3. Confirm `default` points to a valid config. +4. Confirm selector names are discoverable through the task's preset help or environment list. +5. Run a small reset/step smoke test for every new preset. +6. Run training only after preset-specific shape, device, backend, and renderer behavior is stable. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py`, `source/isaaclab_tasks/isaaclab_tasks/utils/preset_cli.py`, `source/isaaclab_tasks/isaaclab_tasks/utils/preset_target.py`, the environment catalog, and maintained preset examples under `source/isaaclab_tasks/isaaclab_tasks/`. If preset selector behavior changes, update the source docs or examples first and keep this skill as a routing checklist. + +## References + +- [Reference](reference.md) +- [Examples](examples.md) +- [Evaluations](evaluations.md) +- [Preset utility source](../../../source/isaaclab_tasks/isaaclab_tasks/utils/hydra.py) +- [Preset CLI source](../../../source/isaaclab_tasks/isaaclab_tasks/utils/preset_cli.py) +- [Preset targets source](../../../source/isaaclab_tasks/isaaclab_tasks/utils/preset_target.py) +- [Environment catalog](../../../docs/source/overview/environments.rst) +- [Quick installation preset examples](../../../docs/source/setup/quick_installation.rst) diff --git a/skills/user/use-presets/evaluations.md b/skills/user/use-presets/evaluations.md new file mode 100644 index 000000000000..ccbed914c651 --- /dev/null +++ b/skills/user/use-presets/evaluations.md @@ -0,0 +1,65 @@ +# Preset System Evaluations + +## Scenario 1: No Preset Needed + +Query: "I have a simple direct task that only runs on PhysX. Should I add PresetCfg?" + +Expected behavior: + +- Recommends a plain config without `PresetCfg`. +- Explains that presets are useful only when there are meaningful named variants. +- Shows the simplified `SimulationCfg(physics=PhysxCfg())` pattern. + +Known failure modes: + +- Adds a preset wrapper with only one variant. +- Claims every task must use presets. + +## Scenario 2: Add PhysX And Newton Variants + +Query: "Make this locomotion environment support PhysX and Newton MJWarp." + +Expected behavior: + +- Uses a `PhysicsCfg(PresetCfg)` wrapper. +- Provides `default`, `physx`, and `newton_mjwarp` variants. +- Keeps solver-specific values in the preset definitions. +- Recommends random-agent smoke tests with `physics=physx` and `physics=newton_mjwarp`. + +Known failure modes: + +- Copies PhysX parameters directly into Newton. +- Uses runtime conditionals instead of config variants. +- Omits the default preset. + +## Scenario 3: Camera Data-Type Presets + +Query: "Expose RGB and depth versions of my camera task." + +Expected behavior: + +- Uses a domain preset selected by `presets=rgb` or `presets=depth`. +- Updates observation shape per data type. +- Calls out renderer and camera requirements. +- Points to maintained Cartpole camera preset examples. + +Known failure modes: + +- Uses `physics=` for a camera data-type preset. +- Forgets `--enable_cameras` in command examples. +- Leaves observation shape unchanged when switching RGB to depth. + +## Scenario 4: Discover Available Options + +Query: "What preset names can I pass for this task?" + +Expected behavior: + +- Recommends listing available presets before guessing names. +- Explains `physics=`, `renderer=`, and `presets=` selector categories. +- Warns that not every task supports every common preset name. + +Known failure modes: + +- Invents preset names not exposed by the task. +- Confuses typed selectors with task-specific domain presets. diff --git a/skills/user/use-presets/examples.md b/skills/user/use-presets/examples.md new file mode 100644 index 000000000000..8541399d7d55 --- /dev/null +++ b/skills/user/use-presets/examples.md @@ -0,0 +1,109 @@ +# Preset Examples + +## Contents + +- Simplified config without presets +- Physics presets +- Domain presets +- Combined presets +- Existing source examples + +## Simplified Config Without Presets + +Use this when the environment has one supported physics setup and no user-selectable variants. + +```python +from isaaclab.sim import SimulationCfg +from isaaclab_physx.physics import PhysxCfg + + +class MySimpleEnvCfg: + sim: SimulationCfg = SimulationCfg(physics=PhysxCfg()) +``` + +This is enough when the task only supports PhysX and there are no renderer, sensor, event, or domain variants to expose. + +## Physics Presets + +Use `PresetCfg` when the same task supports multiple physics backends. + +```python +from isaaclab.sim import SimulationCfg +from isaaclab.utils.configclass import configclass +from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg +from isaaclab_physx.physics import PhysxCfg +from isaaclab_tasks.utils import PresetCfg + + +@configclass +class PhysicsCfg(PresetCfg): + default = PhysxCfg(gpu_max_rigid_patch_count=10 * 2**15) + physx = default + newton_mjwarp = NewtonCfg( + solver_cfg=MJWarpSolverCfg(njmax=120, nconmax=15), + num_substeps=1, + ) + + +@configclass +class MyMultiBackendEnvCfg: + sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg()) +``` + +Command examples: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Ant-v0 --num_envs 4 physics=physx +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Ant-v0 --num_envs 4 physics=newton_mjwarp +``` + +## Domain Presets + +Use domain presets for environment-specific variants such as camera output type. + +```python +from isaaclab.envs import DirectRLEnvCfg +from isaaclab.utils.configclass import configclass +from isaaclab_tasks.utils import PresetCfg + + +@configclass +class CameraTaskCfg(PresetCfg): + @configclass + class BaseCfg(DirectRLEnvCfg): + observation_space = [100, 100, 3] + + default = BaseCfg() + rgb = default + depth = BaseCfg(observation_space=[100, 100, 1]) +``` + +Command examples: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-Camera-Direct-v0 --num_envs 4 presets=rgb +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-Camera-Direct-v0 --num_envs 4 presets=depth +``` + +## Combined Presets + +For camera tasks that expose physics, renderer, and data-type variants, combine selectors: + +```bash +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-Camera-Direct-v0 --num_envs 4 physics=physx renderer=isaacsim_rtx_renderer presets=rgb --enable_cameras +./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-Camera-Direct-v0 --num_envs 4 physics=newton_mjwarp renderer=newton_renderer presets=depth --enable_cameras +``` + +Before using a name, list the task's exposed presets: + +```bash +./isaaclab.sh -p scripts/environments/list_envs.py --show_presets +``` + +## Existing Source Examples + +Inspect these maintained examples before adding new preset patterns: + +- `source/isaaclab_tasks/isaaclab_tasks/manager_based/locomotion/velocity/config/anymal_c/flat_env_cfg.py` +- `source/isaaclab_tasks/isaaclab_tasks/manager_based/locomotion/velocity/config/go1/flat_env_cfg.py` +- `source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_camera_presets_env_cfg.py` diff --git a/skills/user/use-presets/reference.md b/skills/user/use-presets/reference.md new file mode 100644 index 000000000000..ac54f6ab2963 --- /dev/null +++ b/skills/user/use-presets/reference.md @@ -0,0 +1,81 @@ +# Preset System Reference + +## Contents + +- When presets are useful +- When presets are unnecessary +- Selector types +- Definition pattern +- Validation checklist + +## When Presets Are Useful + +Use `PresetCfg` when a field has multiple meaningful named variants that users should select from the command line or through task registration. + +Good candidates: + +- Physics backend settings, such as PhysX versus Newton MJWarp. +- Renderer settings, such as Isaac RTX, Newton Warp, or OVRTX renderers. +- Camera data types, such as RGB, depth, albedo, or segmentation. +- Backend-specific event or sensor configs. +- Domain variants where one task supports multiple authored modes. + +## When Presets Are Unnecessary + +Do not add presets when: + +- The task supports only one backend or renderer. +- The difference is a one-off training override. +- A plain config field is clearer. +- The variant is not exposed or tested. + +Prefer the simple config first. Add presets after the task has at least two tested variants. + +## Selector Types + +Isaac Lab preset-aware entry points recognize three selector forms: + +| Selector | Purpose | +| --- | --- | +| `physics=NAME` | Selects variants whose values are physics config objects. | +| `renderer=NAME` | Selects variants whose values are renderer config objects. | +| `presets=NAME[,NAME,...]` | Applies domain-specific variants or broadcasts preset names across matching preset fields. | + +Use `scripts/environments/list_envs.py --show_presets` to inspect available names before guessing. + +## Definition Pattern + +Import paths: + +```python +from isaaclab.sim import SimulationCfg +from isaaclab.utils.configclass import configclass +from isaaclab_newton.physics import MJWarpSolverCfg, NewtonCfg +from isaaclab_physx.physics import PhysxCfg +from isaaclab_tasks.utils import PresetCfg +``` + +Pattern: + +```python +@configclass +class PhysicsCfg(PresetCfg): + default = PhysxCfg() + physx = default + newton_mjwarp = NewtonCfg(solver_cfg=MJWarpSolverCfg()) + + +@configclass +class MyEnvCfg: + sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg()) +``` + +For multi-backend tasks, keep backend-specific solver values in the preset wrapper. Do not branch on backend names inside step, reward, or reset logic unless behavior truly cannot be represented as config. + +## Validation Checklist + +- The `default` variant is valid. +- Every named variant is tested. +- Selector names match existing conventions such as `physx`, `newton_mjwarp`, `newton_kamino`, `ovphysx`, `rgb`, and `depth`. +- A small random-agent rollout succeeds for each variant. +- Training commands include only preset names that the task exposes. From d039e50bb68997b793118811b4fa827599d863fe Mon Sep 17 00:00:00 2001 From: Kelly Guo <kellyguo123@hotmail.com> Date: Fri, 29 May 2026 22:21:41 -0700 Subject: [PATCH 5/6] add more skills from Seun --- skills/README.md | 4 ++ skills/user/create-environments/SKILL.md | 3 +- skills/user/debug-rl-training/SKILL.md | 58 ++++++++++++++++ skills/user/debug-rl-training/evaluations.md | 47 +++++++++++++ skills/user/debug-rl-training/examples.md | 36 ++++++++++ skills/user/debug-rl-training/reference.md | 69 +++++++++++++++++++ skills/user/diagnose-joint-poses/SKILL.md | 54 +++++++++++++++ .../user/diagnose-joint-poses/evaluations.md | 47 +++++++++++++ skills/user/diagnose-joint-poses/examples.md | 35 ++++++++++ skills/user/plan-manipulation-tasks/SKILL.md | 59 ++++++++++++++++ .../plan-manipulation-tasks/evaluations.md | 47 +++++++++++++ .../user/plan-manipulation-tasks/examples.md | 36 ++++++++++ .../user/prepare-assets-for-newton/SKILL.md | 59 ++++++++++++++++ .../prepare-assets-for-newton/evaluations.md | 47 +++++++++++++ .../prepare-assets-for-newton/examples.md | 35 ++++++++++ .../prepare-assets-for-newton/reference.md | 47 +++++++++++++ skills/user/select-backends/SKILL.md | 3 +- skills/user/train-rl-agents/SKILL.md | 3 +- 18 files changed, 686 insertions(+), 3 deletions(-) create mode 100644 skills/user/debug-rl-training/SKILL.md create mode 100644 skills/user/debug-rl-training/evaluations.md create mode 100644 skills/user/debug-rl-training/examples.md create mode 100644 skills/user/debug-rl-training/reference.md create mode 100644 skills/user/diagnose-joint-poses/SKILL.md create mode 100644 skills/user/diagnose-joint-poses/evaluations.md create mode 100644 skills/user/diagnose-joint-poses/examples.md create mode 100644 skills/user/plan-manipulation-tasks/SKILL.md create mode 100644 skills/user/plan-manipulation-tasks/evaluations.md create mode 100644 skills/user/plan-manipulation-tasks/examples.md create mode 100644 skills/user/prepare-assets-for-newton/SKILL.md create mode 100644 skills/user/prepare-assets-for-newton/evaluations.md create mode 100644 skills/user/prepare-assets-for-newton/examples.md create mode 100644 skills/user/prepare-assets-for-newton/reference.md diff --git a/skills/README.md b/skills/README.md index f317f8c819ee..6e4c1adddd97 100644 --- a/skills/README.md +++ b/skills/README.md @@ -17,9 +17,13 @@ User skills: - `user/domain-randomization-events/`: implement domain randomization through Isaac Lab event terms. - `user/create-environments/`: create direct and manager-based Isaac Lab environments from task requirements. - `user/train-rl-agents/`: configure and run Isaac Lab reinforcement learning workflows. +- `user/debug-rl-training/`: diagnose RL rewards, task metrics, checkpoint compatibility, and training experiments. +- `user/plan-manipulation-tasks/`: stage manipulation tasks through scene, reset, action, reward, and behavior gates. - `user/use-sensors-actuators/`: add sensors, sensor observations, and actuator models to tasks. +- `user/diagnose-joint-poses/`: measure and correct robot initial joint poses from semantic or visual pose requests. - `user/select-backends/`: choose and validate PhysX, Newton, and backend-specific task presets. - `user/use-presets/`: define and use preset configurations for multi-backend and variant-rich tasks. +- `user/prepare-assets-for-newton/`: validate and prepare PhysX-compatible USD assets for Newton task workflows. - `user/setup-troubleshooting/`: route installation, verification, and setup issues to official docs and canonical commands. Planned user skills: diff --git a/skills/user/create-environments/SKILL.md b/skills/user/create-environments/SKILL.md index c546f21ce5e2..44c49eb87e14 100644 --- a/skills/user/create-environments/SKILL.md +++ b/skills/user/create-environments/SKILL.md @@ -13,7 +13,7 @@ owners: Use this skill when a user wants to create a new Isaac Lab environment, choose the right task workflow, or adapt an existing task example. -Do not use this skill for migrating Isaac Gym tasks. Use the `isaaclab-migrating-from-isaac-gym` skill when the source is an Isaac Gym or IsaacGymEnvs task. +Do not use this skill for migrating Isaac Gym tasks. Use the `isaaclab-migrating-from-isaac-gym` skill when the source is an Isaac Gym or IsaacGymEnvs task. For contact-rich manipulation task staging, pair this with `isaaclab-planning-manipulation-tasks`. ## Workflow @@ -52,6 +52,7 @@ Keep this skill synchronized with `docs/source/overview/core-concepts/task_workf - [Evaluations](evaluations.md) - [Examples](examples.md) +- [Manipulation planning skill](../plan-manipulation-tasks/SKILL.md) - [Task workflows](../../../docs/source/overview/core-concepts/task_workflows.rst) - [Create direct workflow environment tutorial](../../../docs/source/tutorials/03_envs/create_direct_rl_env.rst) - [Modify direct workflow environment tutorial](../../../docs/source/tutorials/03_envs/modify_direct_rl_env.rst) diff --git a/skills/user/debug-rl-training/SKILL.md b/skills/user/debug-rl-training/SKILL.md new file mode 100644 index 000000000000..91a2c4a340cc --- /dev/null +++ b/skills/user/debug-rl-training/SKILL.md @@ -0,0 +1,58 @@ +--- +name: isaaclab-debugging-rl-training +description: Diagnoses Isaac Lab reinforcement learning behavior, rewards, metrics, checkpoints, and training experiments. Use when reward curves look wrong, policies fail despite training, checkpoints mismatch, or RL changes need focused ablations. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Debugging RL Training + +## When To Use + +Use this skill when a user needs to debug learned behavior, reward hacking, checkpoint compatibility, unstable training, or training-result trustworthiness. + +Do not use this skill for first-time training commands. Use `isaaclab-training-rl-agents` for launch commands and agent config wiring. + +## Workflow + +1. Identify task name, workflow type, RL library, agent config, seed, backend, and exact launch command. +2. Confirm the environment contract: action space, observation space, reward terms, termination terms, reset logic, and success metric. +3. Run the smallest reproduction: import, reset/step, one-iteration training, or deterministic playback depending on where the failure appears. +4. Change one variable per training experiment. Mark multi-variable runs as exploratory. +5. Compare reward curves against task metrics. Reward increases are not proof that the task behavior improved. +6. For reward issues, map every reward term to a named task phase and check that success reward, termination, and evaluation metric use consistent geometry. +7. For checkpoint issues, compare current observation/action dimensions with the saved training configuration before editing policy code. +8. For contact-rich tasks, collect state traces for controlled-frame pose, object pose, contacts, gripper state, per-term rewards, and termination flags. +9. Select checkpoints by task metrics, rollout behavior, and stability, not reward alone. + +## Validation + +Use this checklist: + +1. The exact command and failing symptom are recorded. +2. The failed layer is classified as environment, reward, reset, physics, runner, or checkpoint compatibility. +3. A focused reproduction isolates one variable. +4. Reward terms and task metrics are inspected together. +5. A deterministic rollout or state trace confirms the behavior change. +6. Any recommended next run changes only one variable. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with `skills/user/train-rl-agents/`, `docs/source/overview/reinforcement-learning/training_guide.rst`, RL training scripts under `scripts/reinforcement_learning/`, and task examples under `source/isaaclab_tasks/isaaclab_tasks/`. If recurring reward or checkpoint guidance belongs in user docs, update `docs/source/` first. + +## References + +- [Reference](reference.md) +- [Examples](examples.md) +- [Evaluations](evaluations.md) +- [RL training skill](../train-rl-agents/SKILL.md) +- [RL training guide](../../../docs/source/overview/reinforcement-learning/training_guide.rst) +- [Task examples](../../../source/isaaclab_tasks/isaaclab_tasks) diff --git a/skills/user/debug-rl-training/evaluations.md b/skills/user/debug-rl-training/evaluations.md new file mode 100644 index 000000000000..5c4348d19ba5 --- /dev/null +++ b/skills/user/debug-rl-training/evaluations.md @@ -0,0 +1,47 @@ +# RL Debugging Evaluations + +## Scenario 1: Reward Hacking + +Query: "My reward goes up, but the robot never completes the task." + +Expected behavior: + +- Separates reward curves from task success metrics. +- Audits per-term rewards against task phases. +- Checks success reward, termination, and metric geometry. +- Recommends deterministic rollout or state traces before retuning PPO. + +Known failure modes: + +- Declares the run successful from reward alone. +- Changes PPO hyperparameters before checking reward and observation semantics. + +## Scenario 2: Checkpoint Mismatch + +Query: "My old checkpoint no longer loads after I changed observations." + +Expected behavior: + +- Compares current observation/action spaces with the checkpoint training config. +- Treats shape mismatch as an environment-contract issue. +- Recommends retraining or reverting unintended contract changes. + +Known failure modes: + +- Patches the runner to ignore shape mismatches. +- Assumes the checkpoint is corrupt before checking environment dimensions. + +## Scenario 3: One-Variable Ablation + +Query: "I changed reward, observations, and reset randomization. Which run should I trust?" + +Expected behavior: + +- Marks the run as exploratory because multiple variables changed. +- Recommends control runs or one-variable ablations. +- Defines success metrics before launching the next run. + +Known failure modes: + +- Attributes behavior to one change without controls. +- Chooses checkpoints only from total reward. diff --git a/skills/user/debug-rl-training/examples.md b/skills/user/debug-rl-training/examples.md new file mode 100644 index 000000000000..c13b44116544 --- /dev/null +++ b/skills/user/debug-rl-training/examples.md @@ -0,0 +1,36 @@ +# RL Debugging Examples + +## Reward Improves But Success Does Not + +Input: a run has increasing reward, but the success rate stays near zero. + +Expected workflow: + +1. Inspect per-term rewards and success metric definitions. +2. Check whether dense shaping saturates before task completion. +3. Compare success reward, termination, and metric geometry. +4. Run deterministic playback and inspect task-state traces. +5. Change only the smallest reward or observation issue before retraining. + +## Checkpoint Shape Mismatch + +Input: playback or resume fails after changing observations. + +Expected workflow: + +1. Print current action and observation spaces. +2. Compare them to the checkpoint's saved config. +3. Revert accidental environment-contract changes or retrain. +4. Do not patch the runner to ignore shape mismatches. + +## Contact-Rich Manipulation Stall + +Input: a manipulation policy reaches the object but cannot grasp, insert, or lift. + +Expected workflow: + +1. Check controlled-frame, object, goal, gripper, and contact observations. +2. Validate reset geometry and gripper/object initial state. +3. Inspect action scaling and controlled joints or body names. +4. Confirm contacts and physics are stable before tuning reward scales. +5. Train one subtask at a time if end-to-end behavior is too hard to interpret. diff --git a/skills/user/debug-rl-training/reference.md b/skills/user/debug-rl-training/reference.md new file mode 100644 index 000000000000..74b5132f5758 --- /dev/null +++ b/skills/user/debug-rl-training/reference.md @@ -0,0 +1,69 @@ +# RL Debugging Reference + +## Contents + +- Experiment discipline +- Reward audit +- Checkpoint compatibility +- State traces +- Decision rules + +## Experiment Discipline + +Record these before a run: + +- Task name and environment config. +- RL library and agent config. +- Backend, renderer, device, seed, number of environments, and iteration count. +- Checkpoint path if resuming. +- Single variable being tested. +- Primary success metric and stop condition. + +One-iteration training proves only runner plumbing. Use short deterministic rollout or task metrics before judging behavior. + +## Reward Audit + +Reward is a training signal, not a success metric. For every reward term, record: + +- The task phase it is intended to teach. +- The state variables it reads. +- The scale and units. +- Whether it saturates before real success. +- Whether it shares geometry with success termination and evaluation metrics. + +Common reward failures: + +- Reward increases while success stays flat. +- Dense shaping reward can be maximized without completing the task. +- Success reward, termination, and metric use different thresholds. +- The policy cannot observe the state needed to optimize the reward. +- Stateful reward buffers are not reset for the correct `env_ids`. + +## Checkpoint Compatibility + +Before replaying or resuming: + +- Compare current observation and action dimensions with the checkpoint's training config. +- Confirm task ID and agent config match the run. +- Confirm the backend and sensor presets are compatible. +- Treat shape mismatches as environment-contract changes, not runner bugs. + +## State Traces + +When reward and behavior disagree, inspect task state directly. Useful trace fields include: + +- Raw and processed policy actions. +- Observation term names and shapes. +- Per-term reward values. +- Termination and truncation flags. +- Robot root, joint, and controlled-frame pose. +- Object pose, velocity, goal error, and contact state. +- Reset state for robot, object, and goal. + +## Decision Rules + +- Reward rises and success rises: continue or scale. +- Reward rises and success stays flat: inspect reward saturation, observations, and success geometry. +- Reward is flat from the start: check action interface, target reachability, reset state, and observation coverage. +- Entropy collapses early: inspect exploration settings and overly strong penalties. +- Physics warnings appear: fix assets, contacts, or buffers before interpreting RL curves. diff --git a/skills/user/diagnose-joint-poses/SKILL.md b/skills/user/diagnose-joint-poses/SKILL.md new file mode 100644 index 000000000000..88727592cda0 --- /dev/null +++ b/skills/user/diagnose-joint-poses/SKILL.md @@ -0,0 +1,54 @@ +--- +name: isaaclab-diagnosing-joint-poses +description: Diagnoses and validates Isaac Lab robot initial joint poses from semantic or visual requests. Use when a robot starts with the wrong wrist, gripper, tool, camera, or end-effector orientation and the fix should be measured from articulation state instead of guessed from screenshots. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Diagnosing Joint Poses + +## When To Use + +Use this skill when a user asks to set, fix, or validate an initial robot pose from language such as "gripper fingers down", "tool points forward", "camera looks at the object", or "end effector aligns with the target". + +## Workflow + +1. Translate the visual request into a measurable body-axis or target-pose condition. +2. Inspect the actual articulation `body_names` and `joint_names`; do not rely only on USD prim names. +3. Measure current body position and orientation from simulation state. +4. Sweep candidate joints one variable at a time, respecting joint limits. +5. Choose the pose that satisfies the axis target while preserving reachability and avoiding self-collision. +6. Patch the task's initial joint positions or reset configuration. +7. Validate with compile checks and a one-env reset or zero-action smoke. +8. Report the measured before/after axis alignment, not just visual appearance. + +## Validation + +Use these acceptance checks: + +1. The body or frame being measured is named explicitly. +2. The requested local axis and target world axis are documented. +3. Body-axis dot product is reported before and after the change. +4. Joint values are inside joint limits. +5. The pose remains reachable for the task target. +6. Observation and action dimensions remain unchanged unless the user requested a contract change. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with robot and articulation APIs under `source/isaaclab/isaaclab/assets/`, environment smoke-test patterns, and examples that use `ArticulationCfg.InitialStateCfg`. Do not include generated screenshots, private assets, or local machine paths in the skill. + +## References + +- [Examples](examples.md) +- [Evaluations](evaluations.md) +- [Articulation assets](../../../source/isaaclab/isaaclab/assets/articulation) +- [Asset configuration APIs](../../../source/isaaclab/isaaclab/assets/asset_base_cfg.py) +- [Zero-agent script](../../../scripts/environments/zero_agent.py) diff --git a/skills/user/diagnose-joint-poses/evaluations.md b/skills/user/diagnose-joint-poses/evaluations.md new file mode 100644 index 000000000000..7fad4c5bfa33 --- /dev/null +++ b/skills/user/diagnose-joint-poses/evaluations.md @@ -0,0 +1,47 @@ +# Joint Pose Diagnostics Evaluations + +## Scenario 1: Gripper Orientation + +Query: "Set the initial gripper pose so the fingers point downward." + +Expected behavior: + +- Converts the request into a measured body-axis target. +- Inspects actual articulation body and joint names. +- Sweeps candidate joints within limits. +- Reports measured before/after alignment. + +Known failure modes: + +- Guesses joint values from a screenshot. +- Assumes USD prim names are articulation body names. + +## Scenario 2: Pose Fix Breaks Reachability + +Query: "The wrist now points the right way, but the robot can no longer reach the object." + +Expected behavior: + +- Treats axis alignment and target reachability as separate acceptance checks. +- Rechecks body-to-target distance or task-specific reach metric. +- Suggests another joint combination or reset pose instead of only maximizing axis alignment. + +Known failure modes: + +- Optimizes orientation while ignoring task reachability. +- Changes observations or actions unnecessarily. + +## Scenario 3: Ambiguous Frame Request + +Query: "Make the tool face forward." + +Expected behavior: + +- Identifies ambiguity in body and local-axis convention. +- Measures candidate axes and states which convention is used. +- Avoids claiming visual success without state evidence. + +Known failure modes: + +- Picks a body and axis silently. +- Reports only a rendered view. diff --git a/skills/user/diagnose-joint-poses/examples.md b/skills/user/diagnose-joint-poses/examples.md new file mode 100644 index 000000000000..dca6f0f0cbfc --- /dev/null +++ b/skills/user/diagnose-joint-poses/examples.md @@ -0,0 +1,35 @@ +# Joint Pose Diagnostics Examples + +## Gripper Fingers Should Point Down + +Input: "The gripper should start with the fingers pointing down." + +Expected workflow: + +1. Identify the finger, tool, or gripper-base body that represents the visual request. +2. Measure local body axes in world frame after reset. +3. Define the target direction, such as local `+Z` or `-Z` aligned to world `[0, 0, -1]`. +4. Sweep wrist joints inside joint limits. +5. Patch `init_state.joint_pos` only after the measured axis meets the tolerance. + +## Camera Should Look At Object + +Input: "The wrist camera should face the cube at reset." + +Expected workflow: + +1. Confirm the camera or camera mount is an exposed body or sensor frame. +2. Measure camera forward axis and object position after reset. +3. Compare the camera forward axis with the camera-to-object direction. +4. Adjust wrist or mount joints only if the camera frame is controlled through articulation joints. +5. Validate the result with a reset smoke and state measurement. + +## Ambiguous Tool Axis + +Input: "Make the tool point forward." + +Expected workflow: + +1. Ask or infer which body and local axis represents "tool forward". +2. If ambiguous, measure multiple candidate axes and explain the selected convention. +3. Report the final measured axis, dot product, and any reachability tradeoff. diff --git a/skills/user/plan-manipulation-tasks/SKILL.md b/skills/user/plan-manipulation-tasks/SKILL.md new file mode 100644 index 000000000000..862c722b8c15 --- /dev/null +++ b/skills/user/plan-manipulation-tasks/SKILL.md @@ -0,0 +1,59 @@ +--- +name: isaaclab-planning-manipulation-tasks +description: Plans Isaac Lab manipulation tasks through phase gates for reaching, grasping, lifting, placing, insertion, and contact-rich workflows. Use when building or debugging manipulation environments where scene setup, reset geometry, action contracts, rewards, and validation must be staged. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Planning Manipulation Tasks + +## When To Use + +Use this skill when a user is creating, migrating, or debugging manipulation tasks such as reach, grasp, lift, place, insertion, or tool-use environments. + +Do not use this skill as a replacement for environment construction details. Pair it with `isaaclab-creating-environments`, `isaaclab-debugging-rl-training`, and `isaaclab-using-sensors-actuators` as needed. + +## Workflow + +1. Define the task objective as measurable phases: approach, align, pre-contact, contact or grasp, transport or lift, and final goal. +2. Build the minimum scene needed for the first phase: robot, support surfaces, task object, goal, lights, and required sensors. +3. Validate asset physics before training: collision geometry, mass, inertia, joint limits, friction, and contact materials. +4. Validate reset geometry before stepping: robot pose, object pose, goal pose, reachability, and absence of interpenetration. +5. Prove the action contract with scripted or zero-action probes before interpreting PPO results. +6. Add observations that expose the state required by the current phase, especially controlled-frame pose for end-effector or contact tasks. +7. Add rewards for one phase at a time. Keep success reward, termination, and metric geometry consistent. +8. Run a training smoke only after scene, reset, action, observation, and reward checks pass. +9. Validate behavior using deterministic rollout state metrics, not just total reward. + +## Validation + +Use these gates before calling a manipulation task ready: + +1. Environment launches with the intended backend and task ID. +2. Scene assets spawn with usable collision and support geometry. +3. Reset state is physically valid and reachable. +4. Action dimensions and controlled joints or bodies match the agent config. +5. Observation terms expose the task frames needed by rewards and actions. +6. Reward, termination, and metric geometry agree. +7. A deterministic rollout or scripted probe satisfies the current phase. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with manipulation examples in `source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation/`, environment authoring docs, and RL debugging guidance. Put project-specific history and experiment logs in the project, not in this public skill. + +## References + +- [Examples](examples.md) +- [Evaluations](evaluations.md) +- [Create environments skill](../create-environments/SKILL.md) +- [Debug RL training skill](../debug-rl-training/SKILL.md) +- [Use sensors and actuators skill](../use-sensors-actuators/SKILL.md) +- [Manipulation tasks](../../../source/isaaclab_tasks/isaaclab_tasks/manager_based/manipulation) diff --git a/skills/user/plan-manipulation-tasks/evaluations.md b/skills/user/plan-manipulation-tasks/evaluations.md new file mode 100644 index 000000000000..e0214358cf05 --- /dev/null +++ b/skills/user/plan-manipulation-tasks/evaluations.md @@ -0,0 +1,47 @@ +# Manipulation Task Evaluations + +## Scenario 1: Contact-Rich Task Planning + +Query: "Help me create a grasp-and-place task for a new gripper." + +Expected behavior: + +- Decomposes the task into reach, align, grasp, lift, transport, and place phases. +- Requires asset physics and reset checks before training. +- Recommends controlled-frame observations and phase-specific rewards. +- Routes command details to environment and training skills. + +Known failure modes: + +- Proposes one monolithic reward before validating the scene and action contract. +- Ignores gripper contacts, support collision, or reset geometry. + +## Scenario 2: Insertion Failure + +Query: "My insertion policy reaches the hole but never inserts." + +Expected behavior: + +- Checks action interface, task-frame alignment, collision geometry, and controlled-frame observations. +- Separates approach/alignment from descent and insertion-depth success. +- Recommends deterministic state traces before reward-scale tuning. + +Known failure modes: + +- Tunes PPO first. +- Uses object-center distance as the only diagnostic. + +## Scenario 3: Visual Success But Bad Metrics + +Query: "The policy looks like it solved the task, but the success metric is zero." + +Expected behavior: + +- Compares success reward, termination, and evaluation metric geometry. +- Checks offsets, target frames, and thresholds. +- Recommends logging task-state metrics from rollout. + +Known failure modes: + +- Declares success from visual inspection alone. +- Changes metric thresholds without checking reward and termination definitions. diff --git a/skills/user/plan-manipulation-tasks/examples.md b/skills/user/plan-manipulation-tasks/examples.md new file mode 100644 index 000000000000..2633c6039b96 --- /dev/null +++ b/skills/user/plan-manipulation-tasks/examples.md @@ -0,0 +1,36 @@ +# Manipulation Task Examples + +## Reaching Before Grasping + +Input: a user wants to train a grasp-and-lift task from scratch. + +Recommended staging: + +1. Validate reachability to the pregrasp pose without object contact. +2. Add alignment rewards and controlled-frame observations. +3. Validate gripper open and close behavior with a scripted command. +4. Add contact or hold rewards only after grasp geometry is reliable. +5. Add lift or transport success last. + +## Insertion Task + +Input: a user wants a peg-in-hole task. + +Recommended staging: + +1. Separate approach, alignment, descent, contact, and insertion-depth phases. +2. Use task-frame or keypoint geometry instead of generic object-center distance. +3. Validate the action interface can move in the insertion direction. +4. Check that collision geometry permits insertion under the intended backend. +5. Select checkpoints by insertion-depth metrics and sustained success, not reward alone. + +## Object Falls Through Table + +Input: an object falls through a visually correct table. + +Recommended staging: + +1. Check whether the table is visual-only. +2. Add or reference explicit support collision geometry. +3. Validate object height and contacts immediately after reset. +4. Only resume training after the physics scene is valid. diff --git a/skills/user/prepare-assets-for-newton/SKILL.md b/skills/user/prepare-assets-for-newton/SKILL.md new file mode 100644 index 000000000000..80e158ab4d72 --- /dev/null +++ b/skills/user/prepare-assets-for-newton/SKILL.md @@ -0,0 +1,59 @@ +--- +name: isaaclab-preparing-assets-for-newton +description: Validates and prepares PhysX-compatible USD assets for Isaac Lab Newton workflows. Use when an asset runs under PhysX but Newton reports missing mass or inertia, placeholder inertials, unsupported collision or joint topology, unstable control, or task-level action and actuator mismatches. +audience: user +status: experimental +owners: + - isaaclab-maintainers +--- + +# Preparing Assets For Newton + +## When To Use + +Use this skill when a user needs to validate or prepare a USD robot, object, or scene asset for Newton after it already works or partially works under PhysX. + +Do not use this skill for choosing a backend at the environment level. Use `isaaclab-selecting-backends` for backend selection and `isaaclab-using-presets` for backend-specific configuration variants. + +## Workflow + +1. Establish a PhysX baseline for the same asset path and task spawn path. +2. Classify the asset as PhysX-compatible, Newton-runnable, or Newton-clean. +3. Audit authored physics metadata: rigid bodies, colliders, mass, inertia, center of mass, joint topology, and material properties. +4. Fix authored USD physics data instead of hiding Newton warnings with task code. +5. If runtime-resolved mass properties are needed, produce a local package or authored layer with explicit mass, diagonal inertia, and center of mass. +6. Re-audit the converted asset under Newton. +7. Validate the asset inside the target Isaac Lab task, not only in a standalone USD viewer. +8. Check actuator joint patterns, controller body names, action dimensions, and zero-action rollout stability. +9. Record source path, converted path, audit verdicts, smoke command, and residual warnings in project documentation. + +## Validation + +An asset is Newton-clean only when: + +1. All rigid bodies have intentional mass properties. +2. Runtime mass and inertia values are finite and positive. +3. Collision geometry is parseable by Newton. +4. Joint topology is accepted by Newton. +5. The target task can spawn and reset the asset under Newton. +6. Zero-action rollout has finite observations, rewards, positions, and velocities. +7. Actuator and controller names still resolve after any USD conversion. + +For skill changes, run: + +```bash +./isaaclab.sh -p tools/skills/cli.py check +``` + +## Maintenance + +Keep this skill synchronized with Newton backend documentation, asset conversion utilities, and backend-specific examples. Avoid storing converted USD packages, generated audit logs, or private asset paths in this skill. + +## References + +- [Reference](reference.md) +- [Examples](examples.md) +- [Evaluations](evaluations.md) +- [Backend selection skill](../select-backends/SKILL.md) +- [Preset skill](../use-presets/SKILL.md) +- [Newton documentation](../../../docs/source/overview/core-concepts/physical-backends/newton) diff --git a/skills/user/prepare-assets-for-newton/evaluations.md b/skills/user/prepare-assets-for-newton/evaluations.md new file mode 100644 index 000000000000..87d1d12b57d6 --- /dev/null +++ b/skills/user/prepare-assets-for-newton/evaluations.md @@ -0,0 +1,47 @@ +# Newton Asset Preparation Evaluations + +## Scenario 1: Placeholder Inertia + +Query: "My PhysX robot runs, but Newton reports placeholder inertia." + +Expected behavior: + +- Establishes a PhysX baseline. +- Audits authored mass, inertia, and center of mass. +- Recommends fixing authored USD physics metadata or producing a local package. +- Requires task-level Newton validation after the asset audit. + +Known failure modes: + +- Treats PhysX runtime success as proof of Newton readiness. +- Suppresses warnings without fixing asset metadata. + +## Scenario 2: Asset Imports But Control Fails + +Query: "The converted robot spawns under Newton, but the policy actions do nothing." + +Expected behavior: + +- Checks actuator joint patterns, controller body names, and action dimensions. +- Runs zero-action and small nonzero-action rollouts. +- Separates asset import success from control readiness. + +Known failure modes: + +- Keeps changing USD mass properties when the task action config is stale. +- Declares the asset ready after standalone import only. + +## Scenario 3: Task-Level Failure + +Query: "The object passes a standalone Newton check but fails inside my environment." + +Expected behavior: + +- Validates the exact task spawn path and overrides. +- Audits support collision, contact materials, and nested references. +- Checks reset and first-step finite state in the target task. + +Known failure modes: + +- Assumes standalone USD parsing covers task-level material and collision overrides. +- Ignores support geometry and contact-relevant scene assets. diff --git a/skills/user/prepare-assets-for-newton/examples.md b/skills/user/prepare-assets-for-newton/examples.md new file mode 100644 index 000000000000..684c50c56ba9 --- /dev/null +++ b/skills/user/prepare-assets-for-newton/examples.md @@ -0,0 +1,35 @@ +# Newton Asset Preparation Examples + +## Missing Mass Properties + +Input: Newton reports placeholder inertia for a robot that works in PhysX. + +Expected workflow: + +1. Confirm the same asset path works in a PhysX baseline. +2. Inspect whether rigid bodies have authored mass, inertia, and center of mass. +3. Author or bake explicit physical metadata in a reusable USD layer or package. +4. Re-run a Newton smoke in the target task. +5. Record residual warnings and modeling choices. + +## Converted Robot Does Not Move + +Input: the converted asset spawns under Newton, but actions do not move the robot. + +Expected workflow: + +1. Check action dimensions and actuator joint name patterns. +2. Check controller body or frame names after conversion. +3. Run zero-action and small nonzero-action rollouts. +4. Fix task config names or actuator gains rather than assuming asset import is enough. + +## Object Works Alone But Fails In Task + +Input: a standalone object audit passes, but the task fails under Newton. + +Expected workflow: + +1. Validate the exact task spawn path. +2. Check task-level material or collision overrides. +3. Inspect support surfaces and contact-relevant rigid objects separately. +4. Confirm observations and rewards remain finite during reset and first steps. diff --git a/skills/user/prepare-assets-for-newton/reference.md b/skills/user/prepare-assets-for-newton/reference.md new file mode 100644 index 000000000000..79f1f84ec64c --- /dev/null +++ b/skills/user/prepare-assets-for-newton/reference.md @@ -0,0 +1,47 @@ +# Newton Asset Preparation Reference + +## Contents + +- Asset classifications +- Audit checklist +- Task-level control checks +- Common failures + +## Asset Classifications + +Use these labels when reporting status: + +- PhysX-compatible: the asset works in the current PhysX task or standalone smoke. +- Newton-runnable: Newton can parse and simulate the asset enough for a limited smoke. +- Newton-clean: authored metadata, task spawn path, and control path pass the validation checklist. + +## Audit Checklist + +Inspect: + +- Rigid body APIs and authored mass properties. +- Diagonal inertia and center-of-mass values. +- Collider types and collision approximation. +- Joint topology and fixed-joint structure. +- Friction and material overrides. +- Nested references and package dependencies. +- Whether task-level overrides apply to the same prims under Newton. + +## Task-Level Control Checks + +Passing asset import is not enough. Also verify: + +- Actuator joint name patterns resolve to the converted USD joint names. +- Controller body names and frame names resolve. +- Action dimensions match the environment action term. +- Stiffness, damping, armature, effort limits, and friction are intentional for Newton. +- Zero-action and small nonzero-action rollouts are finite and move the expected joints or bodies. + +## Common Failures + +- Missing authored mass, inertia, or center of mass. +- Placeholder inertia warnings. +- Fixed-joint topology rejected by Newton. +- Nested references resolve locally but fail in CI or containers. +- Visual-only support geometry causes objects to fall or contact counts to spike. +- Asset import passes, but stale actuator or controller names break the task. diff --git a/skills/user/select-backends/SKILL.md b/skills/user/select-backends/SKILL.md index 59c9151148d1..0492097c0154 100644 --- a/skills/user/select-backends/SKILL.md +++ b/skills/user/select-backends/SKILL.md @@ -13,7 +13,7 @@ owners: Use this skill when a user needs to choose, configure, compare, or debug Isaac Lab physical backends or renderer-related behavior. -Do not use this skill to duplicate backend reference material. Link to the multi-backend docs, schema cfg docs, and source examples for current configuration details. +Do not use this skill to duplicate backend reference material. Link to the multi-backend docs, schema cfg docs, and source examples for current configuration details. If the user is converting or validating a specific USD asset for Newton, use `isaaclab-preparing-assets-for-newton`. ## Workflow @@ -51,6 +51,7 @@ Keep this skill synchronized with `docs/source/overview/core-concepts/multi_back - [Evaluations](evaluations.md) - [Examples](examples.md) +- [Prepare assets for Newton skill](../prepare-assets-for-newton/SKILL.md) - [Multi-backend architecture](../../../docs/source/overview/core-concepts/multi_backend_architecture.rst) - [Schema cfgs](../../../docs/source/overview/core-concepts/schema_cfgs.rst) - [PhysX installation](../../../docs/source/overview/core-concepts/physical-backends/physx/installation.rst) diff --git a/skills/user/train-rl-agents/SKILL.md b/skills/user/train-rl-agents/SKILL.md index 8d623193d6b6..da3975d3e1ed 100644 --- a/skills/user/train-rl-agents/SKILL.md +++ b/skills/user/train-rl-agents/SKILL.md @@ -13,7 +13,7 @@ owners: Use this skill when a user wants to train, resume, evaluate, or configure reinforcement learning for an Isaac Lab task. -Do not use this skill to design environment observations, rewards, or resets from scratch. Use `isaaclab-building-environments` (`skills/user/create-environments/`) for environment construction first. +Do not use this skill to design environment observations, rewards, or resets from scratch. Use `isaaclab-building-environments` (`skills/user/create-environments/`) for environment construction first, and use `isaaclab-debugging-rl-training` when training behavior or reward metrics are already failing. ## Workflow @@ -51,6 +51,7 @@ Keep this skill synchronized with `docs/source/overview/reinforcement-learning/t - [Evaluations](evaluations.md) - [Examples](examples.md) +- [Debug RL training skill](../debug-rl-training/SKILL.md) - [RL training guide](../../../docs/source/overview/reinforcement-learning/training_guide.rst) - [Configure RL training tutorial](../../../docs/source/tutorials/03_envs/configuring_rl_training.rst) - [Run RL training tutorial](../../../docs/source/tutorials/03_envs/run_rl_training.rst) From 3834bc4f4939ac90ab395e5e325e104654900cc6 Mon Sep 17 00:00:00 2001 From: Kelly Guo <kellyguo123@hotmail.com> Date: Fri, 29 May 2026 22:24:22 -0700 Subject: [PATCH 6/6] fix --- skills/user/setup-troubleshooting/SKILL.md | 2 +- skills/user/use-presets/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/user/setup-troubleshooting/SKILL.md b/skills/user/setup-troubleshooting/SKILL.md index c13d30e9558e..a3742d47c77e 100644 --- a/skills/user/setup-troubleshooting/SKILL.md +++ b/skills/user/setup-troubleshooting/SKILL.md @@ -50,7 +50,7 @@ Keep this skill synchronized with installation docs under `docs/source/setup/ins - [Evaluations](evaluations.md) - [Reference](reference.md) -- [Quick installation](../../../docs/source/setup/quick_installation.rst) +- [Quickstart](../../../docs/source/setup/quickstart.rst) - [Source installation](../../../docs/source/setup/installation/source_installation.rst) - [Pip installation](../../../docs/source/setup/installation/pip_installation.rst) - [Isaac Lab pip installation](../../../docs/source/setup/installation/isaaclab_pip_installation.rst) diff --git a/skills/user/use-presets/SKILL.md b/skills/user/use-presets/SKILL.md index 8ff64d7b6a94..4847d1442708 100644 --- a/skills/user/use-presets/SKILL.md +++ b/skills/user/use-presets/SKILL.md @@ -59,4 +59,4 @@ Keep this skill synchronized with `source/isaaclab_tasks/isaaclab_tasks/utils/hy - [Preset CLI source](../../../source/isaaclab_tasks/isaaclab_tasks/utils/preset_cli.py) - [Preset targets source](../../../source/isaaclab_tasks/isaaclab_tasks/utils/preset_target.py) - [Environment catalog](../../../docs/source/overview/environments.rst) -- [Quick installation preset examples](../../../docs/source/setup/quick_installation.rst) +- [Quickstart preset details](../../../docs/source/setup/quickstart_details.rst)