Adds skills for Isaac Lab

.github/workflows/skills-check.yml

@@ -0,0 +1,46 @@
+# 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: 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

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/<package>/changelog.d/`; the changelog and version are compiled by the nightly CI workflow.

docs/source/overview/developer-guide/agent_skills.rst

@@ -0,0 +1,196 @@
+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-name>/
+   │       ├── SKILL.md
+   │       └── examples.md
+   └── user/
+       └── <skill-name>/
+           ├── SKILL.md
+           ├── evaluations.md
+           ├── reference.md       # optional, recommended for longer guidance
+           └── examples.md        # optional, recommended for concrete workflows
+
+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.
+
+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
+--------------
+
+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:
+
+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``.
+
+``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 <https://platform.claude.com/docs/en/agents-and-tools/agent-skills/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.

docs/source/overview/developer-guide/index.rst

@@ -13,3 +13,4 @@ using VSCode.
   VS Code <vs_code>
   repo_structure
   development
+  agent_skills

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'``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

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://github.com/threedworld-mit/tdw
 .. _RoboSuite: https://github.com/ARISE-Initiative/robosuite
 .. _MuJoCo: https://mujoco.org/
 .. _MuJoCo Playground: https://playground.mujoco.org/

skills/README.md

@@ -0,0 +1,92 @@
+# 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/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:
+
+- `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.
+
+## 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:
+
+```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
+```