Skip to content

Adds skills for Isaac Lab#5769

Open
kellyguo11 wants to merge 22 commits into
isaac-sim:developfrom
kellyguo11:consolidate-skills
Open

Adds skills for Isaac Lab#5769
kellyguo11 wants to merge 22 commits into
isaac-sim:developfrom
kellyguo11:consolidate-skills

Conversation

@kellyguo11

@kellyguo11 kellyguo11 commented May 25, 2026

Copy link
Copy Markdown
Contributor

Description

Summary

  • Added a repo-owned agent skills framework with developer and user skill categories, authoring guidance, validation rules, and path-scoped CI.
  • Seeded developer skills for PR workflow, changelog fragments, and coding style.
  • Seeded user skills for Isaac Gym migration, Isaac Lab 2.x to 3.x migration, domain randomization events, environment building, RL training, sensors/actuators, backend selection, and setup troubleshooting.

Details

  • Added skills/ as the canonical home for Isaac Lab agent skills.
  • Added tools/skills/cli.py to validate skill frontmatter, required sections, links, portable paths, user evaluations, and scenario quality.
  • Added docs/source/overview/developer-guide/agent_skills.rst and linked it from the developer guide.
  • Added .github/workflows/skills-check.yml so skill validation runs only when skills, validator code, or the skills workflow change.
  • Updated AGENTS.md with high-level skill ownership, structure, and validation guidance.

Validation

  • Ran python tools/skills/cli.py check
    • Result: Validated 11 skills.
  • Ran python -m py_compile tools/skills/cli.py tools/skills/test/test_validate.py
  • Checked edited files for linter issues.

Includes skills from #4927

Type of change

  • Documentation update

Checklist

  • I have read and understood the contribution guidelines
  • I have run the pre-commit checks with ./isaaclab.sh --format
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • I have updated the changelog and the corresponding version in the extension's config/extension.toml file
  • I have added my name to the CONTRIBUTORS.md or my name already exists there

@kellyguo11 kellyguo11 marked this pull request as draft May 25, 2026 03:52
@github-actions github-actions Bot added documentation Improvements or additions to documentation infrastructure labels May 25, 2026
@greptile-apps

greptile-apps Bot commented May 25, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This PR introduces a repo-owned agent skills framework for Isaac Lab, adding 16 skills (3 developer, 13 user) with a Python validator (tools/skills/cli.py), a pytest-based test suite, path-scoped CI, and developer guide documentation.

  • tools/skills/cli.py validates frontmatter, required sections, unique names, link integrity, backtick path existence, evaluation scenarios, and portable paths; it is well-tested with 9 unit tests plus a live repo-skill validation test.
  • skills/user/plan-manipulation-tasks/SKILL.md contains a broken inter-skill name reference (isaaclab-creating-environments) that does not match the registered frontmatter name isaaclab-building-environments in create-environments/SKILL.md, which would cause agents following the routing instruction to fail to find the target skill.
  • _validate_user_evaluations in cli.py compares the raw link target against \"evaluations.md\" without stripping a ./ prefix, creating an inconsistency with the path-resolving _validate_links check for the same file.

Confidence Score: 4/5

Safe to merge after fixing the broken skill name reference in plan-manipulation-tasks/SKILL.md; the validator and CI infrastructure are solid.

The plan-manipulation-tasks skill routes agents to isaaclab-creating-environments, a name that does not exist in the catalog — the target skill registers itself as isaaclab-building-environments. Any agent following this instruction would silently get no result or pick the wrong skill. This is the only correctness issue; the validator, test suite, CI workflow, and all other skill files are well-structured.

skills/user/plan-manipulation-tasks/SKILL.md — contains the stale cross-skill name reference that would break agent routing.

Important Files Changed

Filename Overview
tools/skills/cli.py New skill validator with frontmatter parsing, section/link/path/evaluation checks. One logic gap: the evaluations-link check uses exact string equality instead of normalising ./ prefixes, inconsistent with the path-resolution approach used elsewhere.
tools/skills/test/test_validate.py Thorough unit tests covering frontmatter, sections, broken links, evaluation details, duplicate names, block scalars, and first-person descriptions. Includes a live repo-skill validation test.
.github/workflows/skills-check.yml Path-scoped CI workflow that now correctly runs pytest; the py_compile step is ordered after pytest, making it redundant rather than a safety gate.
skills/user/plan-manipulation-tasks/SKILL.md Manipulation task planning skill with good phase-gate workflow, but references isaaclab-creating-environments which does not exist — the correct frontmatter name for that skill is isaaclab-building-environments.
skills/README.md Complete catalog of all 16 skills with correct directory paths; all referenced directories are present in the diff.
skills/user/create-environments/SKILL.md Well-structured environment-building skill; note its frontmatter name is isaaclab-building-environments, not isaaclab-creating-environments, which matters for cross-skill references.
tools/skills/pyproject.toml Scopes pytest rootdir to tools/skills/ and adds . to pythonpath so import cli works in tests without a shim. Clean and correct.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Agent receives user request] --> B[Read skills/README.md catalog]
    B --> C{Match description frontmatter field}
    C -->|Match found| D[Read SKILL.md]
    C -->|No match| E[No skill applied]
    D --> F{audience == user?}
    F -->|Yes| G[Read evaluations.md]
    F -->|No| H[Read linked reference files]
    G --> H
    H --> I[Execute Workflow section]
    I --> J[Run Validation checklist]
    J --> K{Cross-skill routing?}
    K -->|Yes| L[Look up skill by frontmatter name]
    K -->|No| M[Done]
    L --> D

    subgraph Validator
        Q[Parse frontmatter] --> R[Validate metadata]
        R --> S[Validate body sections]
        S --> T[Validate links]
        T --> U[Validate backtick paths]
        U --> V{user skill?}
        V -->|Yes| W[Validate evaluations.md]
        V -->|No| X[Done]
        W --> X
    end
Loading

Reviews (2): Last reviewed commit: "fix" | Re-trigger Greptile

Comment thread .github/workflows/skills-check.yml Outdated
Comment on lines +32 to +40
- 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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Test suite compiled but never executed

The workflow compiles test_validate.py with py_compile but never actually runs the tests. Any regression in validator logic — incorrect scenario counting, broken link detection, frontmatter parsing edge cases — will be silently missed in CI. The docs and pyproject.toml both describe how to run pytest tools/skills/, but no pytest step exists here. Adding python3 -m pytest tools/skills/ after the check step would run all nine test cases, including test_validate_current_repo_skills which validates every skill in the repo on each PR.

Comment thread skills/README.md
- `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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Catalog lists user/build-environments/ but the skill directory is never created

The catalog section presents user/build-environments/ as a current user skill alongside the other eight shipped skills, but no skills/user/build-environments/ directory appears in this PR. Only user/import-robot-urdf-mjcf/ is explicitly called out as planned. Anyone following the README to locate this skill will find nothing. Either move this entry to "Planned user skills" or include the directory (with at least a stub SKILL.md) in this PR.

Comment thread tools/skills/cli.py Outdated
Comment on lines +252 to +253
if "evaluations.md" not in body:
errors.append(f"{_display_path(self.path)}: user-facing skills must link to evaluations.md from SKILL.md")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Weak "link to evaluations.md" check passes on prose mentions

The current guard matches any occurrence of the literal string "evaluations.md" in the body, including text like "Do not edit evaluations.md" or a code fence. A SKILL.md that references the file only in prose would silently pass. Checking that a proper markdown link exists is more reliable.

Suggested change
if "evaluations.md" not in body:
errors.append(f"{_display_path(self.path)}: user-facing skills must link to evaluations.md from SKILL.md")
if not re.search(r"(?<!!)\[[^\]]+\]\(evaluations\.md\)", body):
errors.append(f"{_display_path(self.path)}: user-facing skills must link to evaluations.md from SKILL.md")

@isaaclab-review-bot isaaclab-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review Summary

Well-structured introduction of a repo-owned agent skills framework with thorough validation tooling. The design philosophy—keeping skills as routing/sequencing guides rather than duplicating docs—is sound. The validator enforces good hygiene (frontmatter, sections, link validity, portable paths, evaluation quality).

A few items to address:

1. 🔴 CI Failure: Missing skills/user/build-environments/ directory

The Skills Check CI is failing because skills/user/train-rl-agents/SKILL.md references `skills/user/build-environments/` in a backtick path, but that directory doesn't exist in this PR:

skills/user/train-rl-agents/SKILL.md: backtick path does not exist: skills/user/build-environments/

Additionally, skills/README.md lists user/build-environments/ in the active catalog section (not the "Planned" section). Either:

  • Include the build-environments skill in this PR, or
  • Move it to the "Planned user skills" section in the README and remove the backtick-path reference from train-rl-agents/SKILL.md (e.g., mention it as a planned skill name without the path assertion).

2. 🟡 Broken Links CI failure is pre-existing

The "Check for Broken Links" failure is in docs/source/setup/ecosystem.rst (not modified by this PR). This is a pre-existing issue on the base branch and not blocking for this PR specifically.

3. 🟡 Frontmatter parser doesn't handle quoted multi-line or special YAML

The custom YAML frontmatter parser in cli.py uses simple split(":", 1) parsing. This works for the current skills but would silently break on:

  • Values containing colons (e.g., description: Use when: something happens)
  • Multi-line YAML strings or block scalars

Currently all existing descriptions avoid colons after "Use when" by natural language, but this is fragile. Consider either:

  • Adding a note in the authoring guidelines that descriptions must not contain bare colons beyond the first, or
  • Using yaml.safe_load() (stdlib-free alternative: document the constraint clearly)

Since the current skills all pass validation, this is non-blocking but worth documenting as a known limitation.

4. 🟡 validate_all runs _parse_frontmatter twice per skill

In validate_all(), frontmatter is parsed once to collect names for duplicate detection, then skill.validate() parses it again internally. For 11 skills this is negligible, but a minor refactor (e.g., caching the parse result or extracting it once) would be cleaner as the skill count grows.

5. 💡 Consider pinning the actions/checkout and actions/setup-python by tag + hash comment

The workflow pins actions by full SHA (good security practice), but the comment # v6 / # v5 could drift from the actual pinned SHA over time. Consider using the format:

uses: actions/checkout@de0fac2e...  # v6.x.y

with the specific minor version to make future audits easier. Minor nit.


Verdict: The skills check CI failure (#1 above) needs to be resolved before merge. The architecture, validation tooling, skill content quality, and documentation integration are all solid.


Update (1f78c4d): All critical issues from the initial review have been addressed:

  • #1 Fixedskills/user/create-environments/ now exists with full SKILL.md and evaluations.md; README and cross-references updated.
  • #3 Partially addressed — Validator now explicitly rejects block scalars (| and >) with a clear error, and the docs note the YAML subset constraint.
  • Inline: tests not run — CI now installs pytest and runs python3 -m pytest tools/skills/.
  • Inline: weak evaluations.md check — Now uses proper markdown link detection via LINK_RE.
  • Inline: README catalog — Correctly lists user/create-environments/.
  • 🧹 Bonus — Removed dead ThreeDWorld link from ecosystem.rst (addresses pre-existing broken link issue #2).

No new issues found in the incremental changes. LGTM.


Update (6ff9f18): Validated each skill by spawning agents to follow them on representative user queries. The new revision adds examples.md to all skills that were missing them, and adds reference.md to setup-troubleshooting. Results:

Agent Validation Results

Skill Query Tested Result
train-rl-agents "Train Cartpole with RSL-RL on GPU" ✅ Correct command, config path, pre-flight check produced
domain-randomization-events "Randomize friction for PhysX and Newton" ✅ Correctly identified backend differences, chose reset mode, recommended PresetCfg
create-environments "Quadruped with custom commands: direct or manager-based?" ✅ Correctly recommended direct workflow with reasoning
setup-troubleshooting "ModuleNotFoundError: isaaclab_tasks" 🟡 Correct diagnostic workflow but referenced docs don't cover this specific module
pr-workflow "Preparing a PR after fixing schemas.py" ✅ Complete checklist produced with correct commands

Gaps Found During Validation

  1. domain-randomization-events: No concrete PresetCfg code example showing how to wire backend-specific event configs. The skill describes what to do ("use PresetCfg") but not the import path or syntax pattern. An agent inferred the pattern correctly but had to guess at imports.

  2. setup-troubleshooting: The skill correctly routes to docs/source/refs/troubleshooting.rst, but that doc doesn't cover isaaclab_tasks import failures (only isaacsim, isaaclab_physx, etc.). The skill's own philosophy says "update docs first" — this is a docs gap, not a skill gap.

  3. train-rl-agents: Missing --resume/checkpoint flag syntax for RSL-RL. The workflow says "resume or load a checkpoint only after initial run writes expected artifacts" but doesn't show the command.

  4. All user skills: None show import paths for the config classes they reference. An agent with access to the codebase can resolve these, but a standalone user following the skill would need to search.

Verdict

The skills framework is well-designed and the updated revision addresses the examples gap from the initial review. All skills produce correct guidance when followed by an agent. The remaining gaps are minor (missing import examples, one docs gap) and don't block merge. The domain-randomization and migration skills are production-quality; the rest meet the bar for an initial seed.

No blocking concerns.


Update (70215f9): All 4 previously flagged gaps have been addressed in this commit:

Previous Gap Fix
No PresetCfg code example in domain-randomization ✅ Added complete PresetCfg pattern with imports to examples.md
isaaclab_tasks missing from troubleshooting docs ✅ Added to docs/source/refs/troubleshooting.rst AND setup-troubleshooting/reference.md
No checkpoint resume in train-rl examples ✅ Added --resume --load_run RUN_NAME --checkpoint model_100.pt example
Import paths missing ✅ New use-presets skill provides complete import paths in reference.md

New use-presets Skill Validation

Spawned an agent to follow the new skill on: "Add Newton MJWarp support to a PhysX-only locomotion task."

Result: ✅ PASS — Agent produced complete, correct code:

  • Correct PresetCfg wrapper with default, physx, and newton_mjwarp variants
  • Correct import paths (from isaaclab_tasks.utils import PresetCfg, etc.)
  • Proper placement in env config (sim: SimulationCfg = SimulationCfg(physics=PhysicsCfg()))
  • Correct smoke-test commands with physics=physx and physics=newton_mjwarp

The skill's reference.md provides the definition pattern with imports, examples.md shows concrete physics/domain/combined examples, and evaluations.md covers 4 scenarios including "no preset needed."

Final Summary (all 12 skills validated)

All 12 skills (3 developer, 9 user) have been validated by spawning agents. Every skill produces correct, actionable guidance. The pr-workflow skill has minor gaps (test discovery conventions, changelog filename convention) but these are non-blocking for the initial seed. No remaining concerns.


Update (3834bc4): New commits add 4 user skills (debug-rl-training, plan-manipulation-tasks, diagnose-joint-poses, prepare-assets-for-newton) with full SKILL.md, evaluations.md, examples.md, and reference.md files. Cross-references updated in existing skills (train-rl-agents, select-backends, create-environments, use-presets, setup-troubleshooting). Doc references updated to match develop rename (quick_installation.rstquickstart.rst). Also includes a merge from develop with unrelated Newton/OvRTX/PhysX refactoring.

All new skills follow the established patterns and pass the same quality bar. No new issues.


Update (7fc51dc): New commits are a mechanical update of all skill reference paths to track the isaaclab_tasks restructuring (direct/ + manager_based/core/ + contrib/). All affected skills (train-rl-agents, create-environments, use-presets, use-sensors-actuators, plan-manipulation-tasks, setup-troubleshooting, debug-rl-training, migrate-from-isaac-gym, select-backends, migrate-2x-to-3x) correctly reference the new module paths. Training commands updated from deprecated per-library scripts to unified ./isaaclab.sh train and ./isaaclab.sh play entry points.

  • Inline #4 (stale path in plan-manipulation-tasks): Fixed — references updated to core/lift/ and contrib/stack/.
  • ✅ All skill cross-references and example paths are consistent with the new layout.

No new issues introduced. LGTM.

@kellyguo11 kellyguo11 marked this pull request as ready for review May 30, 2026 05:24

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Stale inter-skill name reference breaks agent routing

The prose here directs an agent to use `isaaclab-creating-environments`, but no skill in the catalog has that frontmatter name. The create-environments/ skill is actually named isaaclab-building-environments (see skills/user/create-environments/SKILL.md). An agent following this routing instruction would scan the catalog, find no match, and either silently skip it or use the wrong skill. The train-rl-agents skill gets this right — it uses isaaclab-building-environments — but this file uses the directory slug pattern instead of the registered name.

@AntoineRichard AntoineRichard left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced all these skills are required, but I can see how some of these could provide some good QOL improvement for users. My main concern is that the sync request between the doc and the skill is only listed in the skills themselves but not in the doc, which mean skills may not be updated. I would add a comment into the right documentation files to let agents know these are the skills that need to be updated to match potential doc changes.


## Workflow

1. Identify the install mode: pip, source, binary, cloud, kitless, or backend-specific setup.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this list uv?

Comment on lines +48 to +50
## 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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also add the same to the docs that need to be kept in sync so agents can update the skills automatically when the doc changes.

Comment thread skills/user/select-backends/SKILL.md
Comment thread skills/user/setup-troubleshooting/SKILL.md
Comment thread skills/user/train-rl-agents/SKILL.md
Comment on lines +49 to +51
## 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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also add the same to the docs that need to be kept in sync so agents can update the skills automatically when the doc changes.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe agents.md should reference that skill?

Comment on lines +49 to +52
## 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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also add the same to the docs that need to be kept in sync so agents can update the skills automatically when the doc changes.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That might be pushing it a bit, do we need that coding style skill? When would it be invoked?

Comment on lines +45 to +47
## 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.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also add the same to the docs that need to be kept in sync so agents can update the skills automatically when the doc changes.

.. _AirSim: https://microsoft.github.io/AirSim/
.. _DoorGym: https://github.com/PSVL/DoorGym/
.. _ManiSkill: https://github.com/haosulab/ManiSkill
.. _ThreeDWorld: https://github.com/threedworld-mit/tdw

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this change related?

@AntoineRichard AntoineRichard left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These RL skills launch training/eval via the deprecated per-library scripts (scripts/reinforcement_learning/<library>/train.py|play.py). On develop those shims emit a DeprecationWarning and instruct users to use the unified entrypoint (./isaaclab.sh train --rl_library <lib> --task <TASK>, and ./isaaclab.sh play ...). Since these skills are meant to teach the current, recommended workflow — and train-rl-agents/examples.md already adopts other 3.0 conventions (it notes --headless is deprecated and uses --viz) — the launch commands should use the unified train/play subcommands too. Inline suggestions below for each occurrence.

Training pattern:

```bash
./isaaclab.sh -p scripts/reinforcement_learning/rl_games/train.py --task Isaac-Cartpole-Direct-v0

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/rl_games/train.py --task Isaac-Cartpole-Direct-v0
./isaaclab.sh train --rl_library rl_games --task Isaac-Cartpole-Direct-v0

Comment thread skills/user/select-backends/examples.md Outdated
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 physics=physx

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Ant-v0 physics=physx
./isaaclab.sh train --rl_library rsl_rl --task Isaac-Ant-v0 physics=physx

For training entry points:

```bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --max_iterations 1

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --max_iterations 1
./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-v0 --max_iterations 1

Comment thread skills/user/train-rl-agents/examples.md Outdated
RSL-RL:

```bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --run_name ppo

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --run_name ppo
./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-v0 --run_name ppo

Comment thread skills/user/train-rl-agents/examples.md Outdated
RL-Games direct Cartpole:

```bash
./isaaclab.sh -p scripts/reinforcement_learning/rl_games/train.py --task Isaac-Cartpole-Direct-v0

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/rl_games/train.py --task Isaac-Cartpole-Direct-v0
./isaaclab.sh train --rl_library rl_games --task Isaac-Cartpole-Direct-v0

Comment thread skills/user/train-rl-agents/examples.md Outdated
Stable Baselines 3:

```bash
./isaaclab.sh -p scripts/reinforcement_learning/sb3/train.py --task Isaac-Cartpole-v0 --num_envs 64

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/sb3/train.py --task Isaac-Cartpole-v0 --num_envs 64
./isaaclab.sh train --rl_library sb3 --task Isaac-Cartpole-v0 --num_envs 64

Comment thread skills/user/train-rl-agents/examples.md Outdated
SKRL:

```bash
./isaaclab.sh -p scripts/reinforcement_learning/skrl/train.py --task Isaac-Cartpole-v0

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/skrl/train.py --task Isaac-Cartpole-v0
./isaaclab.sh train --rl_library skrl --task Isaac-Cartpole-v0

Comment thread skills/user/train-rl-agents/examples.md Outdated
Play example:

```bash
./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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./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
./isaaclab.sh play --rl_library rsl_rl --task Isaac-Cartpole-v0 --checkpoint logs/rsl_rl/cartpole/RUN_NAME/model_100.pt --viz kit

Comment thread skills/user/train-rl-agents/examples.md Outdated
Resume example:

```bash
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --resume --load_run RUN_NAME --checkpoint model_100.pt

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Uses the deprecated per-library entrypoint, which emits a DeprecationWarning on develop (the shim in scripts/reinforcement_learning/rsl_rl/train.py points to exactly this form). Use the unified CLI subcommand:

Suggested change
./isaaclab.sh -p scripts/reinforcement_learning/rsl_rl/train.py --task Isaac-Cartpole-v0 --resume --load_run RUN_NAME --checkpoint model_100.pt
./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-v0 --resume --load_run RUN_NAME --checkpoint model_100.pt

@isaaclab-review-bot isaaclab-review-bot Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review Update (7fc51dc)

New commits since the last review (3834bc4) include a major merge from develop and skill-specific updates.

Merge from develop includes:

  • Demo script fixes (h1_locomotion, quadcopter, bin_packing)
  • Environment shutdown race condition fix
  • Environment/installation docs regeneration tooling
  • MJCF importer extension fix
  • Prim resolution cleanup
  • Cartpole task consolidation via preset CLI
  • Deferred pxr loading fix for Kit visualizer startup
  • Kit version logging on AppLauncher startup
  • isaaclab_tasks restructuring (direct/ + manager_based/core/ + contrib/)
  • Wheel extension discoverability fix with rl-games added back
  • Frame transformer tutorial and docs viz parsing fixes

Skill-specific changes (cfbc742, 7fc51dc):

  • ✅ All skill reference paths updated to track the new core/ + contrib/ task layout
  • ✅ Training commands updated from deprecated per-library scripts to unified ./isaaclab.sh train and ./isaaclab.sh play entry points
  • ✅ Added doc-to-skill sync notes in Maintenance sections
  • setup-troubleshooting/reference.md now routes uv-managed environments
  • ✅ Cross-references in plan-manipulation-tasks correctly point to core/lift/ and contrib/stack/

Verified path updates in skills:

Skill Old Paths New Paths Status
train-rl-agents scripts/reinforcement_learning/rsl_rl/train.py ./isaaclab.sh train --rl_library rsl_rl
create-environments isaaclab_tasks/direct/, isaaclab_tasks/manager_based/ isaaclab_tasks/core/direct_cartpole/, isaaclab_tasks/core/manager_cartpole/
use-presets contrib/velocity/config/anymal_c/ contrib/velocity/config/anymal_c/
use-sensors-actuators direct/anymal_c/, manager_based/locomotion/velocity/ contrib/anymal_c_direct/, core/velocity/
plan-manipulation-tasks manager_based/manipulation/ core/lift/, contrib/stack/
migrate-from-isaac-gym direct/humanoid/ core/direct_humanoid/
select-backends scripts/reinforcement_learning/rsl_rl/train.py ./isaaclab.sh train --rl_library rsl_rl
debug-rl-training per-library scripts unified CLI

All skill references are consistent with the new layout. The --headless deprecation is reflected (training runs headless by default; --viz kit for visualization).

No new issues introduced. LGTM.


Update (c54ad10): New commits since 7fc51dc are entirely Isaac Lab framework changes (cloner refactoring to queue-based ReplicateSession, CircularBuffer stack_dim mode, fused Warp uint8 image normalize kernel, NewtonSDFCollisionPropertiesCfg schema forwarding, sensor clone-plan integration, test updates). None of these touch the skills directory, validation tooling, or documentation paths reviewed previously.

Previous inline comments (CI workflow missing pytest step, catalog listing non-existent build-environments/ skill, weak evaluations.md link check, stale inter-skill name reference) remain unaddressed — original comments still visible on the PR.

No new issues introduced by the incremental diff.


Update (4b1688a): New commits fix RST cross-reference paths in documentation (:doc:\/overview/developer-guide/agent_skills`:doc:`/source/overview/developer-guide/agent_skills`) and reorder RST label directives to appear after .. seealso::` blocks in a few tutorial/installation pages. These are minor doc formatting fixes only.

Previous inline comments (CI workflow missing pytest step, catalog listing non-existent build-environments/ skill, weak evaluations.md link check, stale inter-skill name reference) remain unaddressed — original comments still visible on the PR.

No new issues introduced.

@AntoineRichard AntoineRichard left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should double check v0s and --headless flags.

Smoke-test pattern:

```bash
./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 8

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No more v0 for carpole

Comment thread skills/user/select-backends/examples.md Outdated
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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no more v0 for ant?

Comment thread skills/user/select-backends/examples.md Outdated
Once reset/step behavior is stable on the selected backend:

```bash
./isaaclab.sh train --rl_library rsl_rl --task Isaac-Ant-v0 physics=physx

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no more v0 for ant?

For task import and stepping:

```bash
./isaaclab.sh -p scripts/environments/random_agent.py --task Isaac-Cartpole-v0 --num_envs 4

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no more v0 for cartpole

For training entry points:

```bash
./isaaclab.sh train --rl_library rsl_rl --task Isaac-Cartpole-v0 --max_iterations 1

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no more v0 for cartpole

Comment thread skills/user/train-rl-agents/examples.md
Comment thread skills/user/use-presets/examples.md Outdated
Comment on lines +56 to +57
./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

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

v0s

@kellyguo11 kellyguo11 force-pushed the consolidate-skills branch from 8075b0a to b79775a Compare June 28, 2026 07:00
kellyguo11 and others added 8 commits June 28, 2026 00:01
Switch skill examples from deprecated per-library scripts to ./isaaclab.sh train/play, add doc-to-skill sync notes, uv install routing, and an AGENTS.md pointer to the PR workflow skill.
kellyguo11 and others added 5 commits June 28, 2026 00:01
Point cartpole, locomotion, and camera examples at core/cartpole and core/locomotion paths after the develop task reorganization.
Clarify direct-vs-manager environment selection for custom locomotion tasks and point agents at current source examples. Add explicit skill evaluation checks to the PR workflow and fix a stale Shadow Hand example path.
Update skill references for current task locations.

Document backend-specific sensor configs and the latest PhysX/Newton schema cfg classes.

Avoid deprecated core schema shims in new guidance.
@kellyguo11 kellyguo11 force-pushed the consolidate-skills branch from b79775a to 335a05e Compare June 28, 2026 07:16
Steer new environment guidance toward manager-based workflows while keeping Isaac Gym migrations direct-first for parity.

Add a direct-to-manager conversion skill and record the fresh Ant migration validation, including the local runtime blocker.
Record the corrected Ant validation using the local _isaac_sim runtime.

Clarify scratch PYTHONPATH setup and force-torque sensor mapping expectations.
Prefer pip-based Isaac Sim setup guidance for new full-feature installs.

Record Anymal direct locomotion training gates and remove binary-install-specific runtime wording.
Capture the fresh-agent IsaacGymEnvs Anymal migration outcome.

Clarify command staging before claiming locomotion policy success.
Document the repeatable train, metric parsing, checkpoint rollout, and iteration process for migrated Isaac Gym tasks before claiming policy success.
Capture the fresh-agent flat Anymal migration run that trained a successful policy with parsed metrics and checkpoint rollout evidence.
Guide Isaac Gym migration agents to scaffold external validation work with the Isaac Lab template generator and avoid deprecated --headless command examples.
Update Isaac Gym migration guidance to use uv run for template generation, preflight, tests, training, and validation commands.
Refresh skill guidance to prefer uv entry points, current task paths, and split backend schema imports. Update setup, training, backend, preset, and environment examples so agents copy current commands.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation infrastructure

Projects

Status: In review

Development

Successfully merging this pull request may close these issues.

2 participants