智能体技能

智能体技能#

Isaac Lab 智能体技能是一组随仓库维护的说明，帮助编程智能体遵循 Isaac Lab 工作流程。它们是 Markdown 指南文件，不是运行时 Python 软件包。技能库覆盖安装、环境构建、训练、调试、迁移和贡献代码等工作。Codex 和 Claude 会从仓库工作副本中自动发现技能，见 技能发现；完整目录位于 skills/README.md。

技能分类#

技能通常分为两类：由用户调用的技能，以及由智能体自动应用的技能。两类并不互斥；user/ 或 developer/ 目录表示技能面向的使用者。

通常由用户调用的技能

可以描述任务或指定技能名称来调用，例如在 Claude Code 中使用 /isaaclab-installing-isaac-lab。这些技能处理由用户发起的工作：安装 Isaac Lab、创建和转换环境、训练和调试强化学习、选择后端和预设、为 Newton 准备资产、从 Isaac Gym 或 Isaac Lab 2.x 迁移，以及排查安装问题。它们位于 skills/user/。skills/developer/ 中部分维护工作也按需调用，例如 isaaclab-auditing-an-issue 和 isaaclab-triaging-issue-backlog。

通常由智能体自动应用的技能

任务符合技能描述时，智能体通常遵循 AGENTS.md 自行加载这些技能。它们规定贡献代码时的约定，包括代码风格、测试审查、变更日志片段、环境文档同步和 PR 准备，位于 skills/developer/。

用户技能在请求符合其描述时也会自动触发，因此不必指定名称。希望明确使用某项技能时，可以直接点名。

目录布局#

技能位于仓库根部的 skills/ 目录：

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

技能文件#

文件

开发者技能

用户技能

用途

SKILL.md

必需

必需

面向智能体的主要工作流与参考链接。

evaluations.md

可选

必需

代表性提示词、预期行为，以及通过或失败的判定标准。

reference.md

可选

推荐

不宜放入 SKILL.md 的较长背景说明。

examples.md

推荐

推荐

工作流的具体示例。

scripts/

可选

可选

具有明确运行或阅读说明的确定性辅助工具。

发现技能#

Codex 和 Claude 通过项目原生别名自动发现仓库技能：

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

Codex 扫描 .agents/skills ，Claude 扫描 .claude/skills 。别名使用前置元数据中的 name ，使两个智能体使用同一稳定标识。它们指向 skills/ 下的正式目录，使每个技能只维护一份，并保留相对仓库的引用。不要将技能平铺复制到全局智能体技能目录。

不支持原生技能发现的智能体应使用 skills/README.md 作为目录。根据每个 SKILL.md 前置元数据的 description 字段匹配用户请求，再只阅读选中的技能和直接链接的文件。目录名是供人和审阅者使用的正式文件位置；技能互相指引时，应使用前置元数据中的 name 作为稳定标识。

技能约定#

每个技能必须包含带有前置元数据的 SKILL.md ：

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

前置元数据的必需字段如下：

前置元数据有意只使用少量 YAML 语法：单行标量字段和 owners 列表。不要在 SKILL.md 的前置元数据中使用 | 或 > 等块标量；较长细节应放在 Markdown 正文或链接的参考文件中。

name

由小写字母、数字和连字符组成的唯一标识。建议使用 isaaclab- 前缀，避免 helper 、 utils 、 tools 等泛化名称。标识必须与 .agents/skills/ 下的原生别名一致。

description

用第三人称描述发现技能所需的信息，包括技能做什么，以及智能体何时应使用它。

合适的示例：

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.

不合适的示例：

description: Helps with tasks.
audience

取值为 developer 或 user ，必须与 skills/ 下的目录一致。

status

取值为 experimental 、 stable 或 deprecated 。

新指导或尚不完整、需要实际使用验证的指导，应使用 experimental 。只有具备持续维护的参考资料、验证说明，并经过负责领域的审阅后，才能升为 stable 。工作流被替代或不再推荐时，使用 deprecated ；已弃用技能必须指向替代工作流或迁移路径。

owners

对该技能负责的一个或多个维护者组或负责人。

SKILL.md 必须包含以下章节：

  • When To Use

  • Workflow

  • Validation

  • Maintenance

  • References

面向用户的技能还必须包含 evaluations.md ，至少提供三个代表性场景。每个场景应包含示例提示词或任务、预期行为，以及已知失败模式或通过与失败的判定标准。

编写指南#

本指南参考 Anthropic 的 技能编写最佳实践 ，并根据 Isaac Lab 文档与贡献工作流作了调整。

保持 SKILL.md 简洁。上下文是共享资源，应假设智能体已理解通用编程概念。 SKILL.md 只放完成任务必需的工作流。

逐步提供细节。从 SKILL.md 直接链接到同一层的 reference.md 、 examples.md 或 evaluations.md 等文件。避免通过多个文件跳转，才能找到实际指导。

较长参考文件应包含目录。超过 100 行的参考文件应以 # Contents 或 ## Contents 开始，便于智能体在部分阅读时导航。

不要包含凭据、从其他系统复制的私有内容、生成的日志、特定硬件的基准数据转储，或大份内置第三方文档。如果这些信息有用，应概述工作流并链接到持续维护的来源。

选择合适的自由度：

  • 审阅和设计工作使用高自由度指导。

  • Isaac Lab 有推荐模式时，使用中等自由度模板。

  • 验证等容易出错的工作流，使用低自由度的精确命令或脚本。

先给出一个明确的默认方案，再列出替代方案。如果需要例外路径，说明何时使用。

避免容易过时的措辞。迁移说明应使用 Current Workflow 和 Old Patterns 章节，而不是基于日期的指令。

整个技能使用一致的 Isaac Lab 术语，例如基于管理器的环境、事件项、关节体配置和变更日志片段。

保持技能同步#

技能不应成为另一套独立文档。权威依据是 docs/source/ 下的 Isaac Lab 文档，以及 source/ 、 scripts/ 下持续维护的源码和示例。

每个技能必须包含 Maintenance 章节，列出代码变更时要复查的权威文件。如果技能需要文档级内容，应先更新官方文档，再从技能链接过去。

保持双向链接。如果 docs/source/ 下某页是技能的权威依据，应在该页开头附近添加 .. seealso:: 提示，注明技能名并链接回技能。这能提醒文档作者在同一项修改中更新关联技能，避免二者偏离。技能的 Maintenance 章节列出文档页时，如果文档页没有回链，应在审阅中指出。

审阅时遵循以下规则：

  • 如果官方文档已覆盖相关主题，应拒绝大段复制的 API 表格或独立安装指南。

  • 优先链接到文档、源码和持续维护的示例，避免重复代码片段。

  • 技能只保留对智能体有针对性价值的内容：指引、任务顺序、验证循环、搜索词和已知决策点。

  • 如果技能暴露了缺失的迁移说明或故障排查条目，应将其添加到 docs/source/ ，而不是扩充技能。

  • 对于仿真、资产、传感器或随机化工作流，应说明指导是否适用于所有后端，还是只适用于 PhysX、Newton 或某个渲染、可视化后端。应链接到多后端文档和源码实现，而不是将后端表格复制到技能中。

  • 每次修改技能后，都运行技能验证器。

验证流程#

在本地使用以下命令验证技能：

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

验证器检查前置元数据、必需章节、名称唯一性、受众与路径的一致性、链接有效性、参考层级、路径可移植性、原生 Codex 和 Claude 别名、必需的用户评估、评估场景最少数量，以及各场景的示例查询、预期行为、已知失败模式或判定标准等细节。

使用以下命令运行验证器测试：

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

技能 CI 检查仅在 PR 修改 skills/ 、 tools/skills/ 或技能工作流时运行。这样既能检查验证器变更，也不会因技能验证阻止无关的 Isaac Lab PR。

审阅规则#

开发者技能影响贡献者工作流，需要负责领域的维护者批准。

用户技能必须具备持续维护的参考资料、验证方式、与文档的一致性，以及至少三个评估场景。

技能如果只是重复通用知识，而没有说明 Isaac Lab 专用工作流，审阅者应拒绝它。已弃用技能必须提供迁移说明；有替代技能时，也必须注明。

目录