docs: add AI coding agent skills and cross-reference throughout documentation#247
docs: add AI coding agent skills and cross-reference throughout documentation#247
Conversation
…entation Add Claude Code / AI agent skill files for common development tasks (add-functor, add-task-env, add-test, pre-commit-check, pr, benchmark) and replace verbose boilerplate examples in AGENTS.md with concise skill references. Add contextual tip boxes in guides, tutorials, and reference pages pointing developers to relevant skills. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
yuecideng
added
docs
There was a problem hiding this comment.
Pull request overview
This PR introduces a set of built-in “skills” for AI coding agents (e.g., Claude Code / Copilot CLI) and updates EmbodiChain documentation to reference those skills instead of repeating long boilerplate snippets.
Changes:
- Added new
.claude/skills/*/SKILL.mddocuments describing common development workflows (env scaffolding, functors, tests, pre-commit checks). - Updated
AGENTS.mdto point to the skills and added a “Skills Quick Reference” table. - Added tip/admonition cross-references to skills across tutorials, guides, and gym overview docs.
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/source/tutorial/modular_env.rst | Adds an RST tip linking to relevant skills for modular env workflows. |
| docs/source/tutorial/basic_env.rst | Adds an RST tip pointing readers to env/test/pre-commit skills. |
| docs/source/quick_start/install.md | Adds an “AI Coding Agent” section listing available skills/commands. |
| docs/source/overview/gym/reward_functors.md | Adds a MyST tip pointing to /add-functor and /add-test. |
| docs/source/overview/gym/observation_functors.md | Adds a MyST tip pointing to /add-functor and /add-test. |
| docs/source/overview/gym/event_functors.md | Adds a MyST tip pointing to /add-functor and /add-test. |
| docs/source/overview/gym/env.md | Adds a MyST tip summarizing key env-related skills. |
| docs/source/overview/gym/dataset_functors.md | Adds a MyST tip pointing to /add-functor for dataset functors. |
| docs/source/overview/gym/action_functors.md | Adds a MyST tip pointing to /add-functor for action terms. |
| docs/source/guides/add_robot.rst | Adds an RST tip cross-referencing skills relevant to robot extensions. |
| AGENTS.md | Replaces verbose examples with skill references and adds a quick reference table. |
| .claude/skills/pre-commit-check/SKILL.md | New skill doc for local CI-style checks before committing. |
| .claude/skills/add-test/SKILL.md | New skill doc describing EmbodiChain test conventions and patterns. |
| .claude/skills/add-task-env/SKILL.md | New skill doc for scaffolding new task environments. |
| .claude/skills/add-functor/SKILL.md | New skill doc for adding observation/reward/event/action/dataset/randomization functors. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Benchmark | `/benchmark` | Write benchmark scripts for EmbodiChain modules | | ||
|
|
||
| Run `/pre-commit-check` before every commit to catch formatting, header, annotation, and export issues locally — the same checks the CI pipeline enforces. | ||
| ``` |
There was a problem hiding this comment.
There is a stray Markdown code fence (), which will start an unclosed code block at end-of-file and can break/garble the rendered page in the Sphinx/MyST build. Remove the trailing or replace it with the intended content.
| ``` |
| Managers (observation, event, reward, randomization) use a `Functor`/`FunctorCfg` pattern with two styles: | ||
|
|
||
| - **Function-style**: a plain function with signature `(env, env_ids, ...) -> None`. | ||
| - **Class-style**: a class inheriting `Functor`, with `__init__(cfg, env)` and `__call__(env, env_ids, ...)`. |
There was a problem hiding this comment.
The Functor/Manager section states function-style functors have signature (env, env_ids, ...) -> None, but reward/observation functors in this codebase take (env, obs, ...) / (env, obs, action, info, ...) and return tensors (see embodichain/lab/gym/envs/managers/rewards.py and observations.py). Please adjust this documentation to describe signatures as manager-specific (or point readers to the /add-functor skill’s signature table).
| description: Use before committing or creating a PR for EmbodiChain to verify code style, headers, annotations, exports, and docstrings pass CI checks | ||
| --- | ||
|
|
||
| # Pre-Commit Check | ||
|
|
||
| Run all local checks that the CI pipeline enforces, catching issues before pushing. | ||
|
|
There was a problem hiding this comment.
This skill claims these are "checks that the CI pipeline enforces", but the CI workflow only runs Black, pytest, and the Sphinx docs build (.github/workflows/main.yml). Headers/__future__/__all__/docstring checks are useful conventions, but they aren’t currently enforced by CI—please reword to avoid misleading users about what will fail CI vs what is best-practice guidance.
| |-------|---------------| | ||
| | Black formatting | `black --check --diff --color ./` | | ||
| | Auto-fix formatting | `black .` | | ||
| | Header check | Verify first line is `# ---...---` | |
There was a problem hiding this comment.
The quick reference says the header check is to verify the first line is # ---...---, but earlier in this doc the actual required first line is shown as # ----------------------------------------------------------------------------. Please make these consistent to avoid false positives when users follow the checklist.
| | Header check | Verify first line is `# ---...---` | | |
| | Header check | Verify first line is `# ----------------------------------------------------------------------------` | |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| If you want to implement your tasks in a new repo and with some customized functors and utilities, you can also use the [Task Template Repo](https://github.com/DexForce/embodichain_task_template). No newline at end of file | ||
| * For large features, break the work into small, focused tasks and handle them one at a time using the appropriate skill for each step. | ||
| * If you add a new skill to `.claude/skills/`, make sure to also add it to the Skills table and "When to use each skill" list in this document so contributors can discover it. No newline at end of file |
There was a problem hiding this comment.
The <details> block opened above is never closed. This can cause the remainder of the rendered page (or following sections) to be swallowed into the details element depending on the Markdown renderer. Add a closing </details> tag at the end of the Claude Code section (after the Tips list).
| * If you add a new skill to `.claude/skills/`, make sure to also add it to the Skills table and "When to use each skill" list in this document so contributors can discover it. | |
| * If you add a new skill to `.claude/skills/`, make sure to also add it to the Skills table and "When to use each skill" list in this document so contributors can discover it. | |
| </details> |
| Managers (observation, event, reward, randomization) use a `Functor`/`FunctorCfg` pattern with two styles: | ||
|
|
||
| - **Function-style**: a plain function with signature `(env, env_ids, ...) -> None`. | ||
| - **Class-style**: a class inheriting `Functor`, with `__init__(cfg, env)` and `__call__(env, env_ids, ...)`. | ||
| - Registered in a manager config via `FunctorCfg(func=..., params={...})`. | ||
|
|
There was a problem hiding this comment.
The Functor signature guidance here is inaccurate for several of the listed managers. Observation functors typically take (env, obs, entity_cfg, ...) and return a tensor, and reward functors take (env, obs, action, info, ...) and return a tensor; (env, env_ids, ...) -> None is primarily for event/randomization-style functors. Please update the bullets to either (a) list signatures per manager type, or (b) describe the pattern without hardcoding the env_ids/None signature.
| 2. **test** job: `pytest tests` | ||
| 3. **build** job: Sphinx docs build | ||
|
|
||
| This skill covers items 1 and 2 locally. Docs build is heavier and typically only needed for documentation changes. |
There was a problem hiding this comment.
This section describes CI as running lint → test → build, but .github/workflows/main.yml runs lint, then (on PRs) runs build and test in parallel after lint (and test is PR-only). Please update this list to reflect the actual workflow so contributors aren’t misled about which jobs run when and in what order.
| 2. **test** job: `pytest tests` | |
| 3. **build** job: Sphinx docs build | |
| This skill covers items 1 and 2 locally. Docs build is heavier and typically only needed for documentation changes. | |
| 2. After **lint** passes, PRs run these jobs in parallel: | |
| - **build** job: Sphinx docs build | |
| - **test** job: `pytest tests` | |
| This skill helps you run the local checks that most closely match CI, especially `lint` and targeted test runs before opening a PR. Docs build is heavier and typically only needed for documentation changes. |
| Tests mirror the source tree under `tests/`: | ||
|
|
||
| ``` | ||
| embodichain/lab/sim/solvers/pytorch_solver.py → tests/sim/solvers/test_pytorch_solver.py | ||
| embodichain/lab/gym/envs/managers/rewards.py → tests/gym/envs/managers/test_reward_functors.py | ||
| embodichain/toolkits/graspkit/pg_grasp/foo.py → tests/toolkits/test_pg_grasp.py | ||
| embodichain/lab/gym/envs/tasks/rl/push_cube.py → tests/gym/envs/tasks/test_push_cube.py | ||
| ``` | ||
|
|
||
| Rules: | ||
| - File name: `test_<module>.py` | ||
| - Directory path mirrors `embodichain/` structure under `tests/` | ||
| - Create `__init__.py` files in new `tests/` subdirectories if needed |
There was a problem hiding this comment.
The “Tests mirror the source tree under tests/” / “Directory path mirrors embodichain/ structure” guidance is not accurate for the current repo layout (e.g., embodichain/lab/... tests live under tests/sim, tests/gym, etc., and some toolkits collapse into a single test module). Consider rewording this to match the established structure (grouped by top-level domain like tests/gym, tests/sim, tests/agents, tests/toolkits) and recommend locating the nearest existing test file/directory for the module being changed rather than implying a strict 1:1 path mirror.
| | Benchmark | `/benchmark` | Write benchmark scripts for EmbodiChain modules | | ||
|
|
||
| Run `/pre-commit-check` before every commit to catch formatting, header, annotation, and export issues locally — the same checks the CI pipeline enforces. | ||
| ``` |
There was a problem hiding this comment.
There is an extra closing triple-backtick at the end of this page (after the /pre-commit-check paragraph). This leaves an unterminated/stray code fence in the rendered Markdown and is likely to break the Sphinx/MyST docs build. Remove the trailing ``` or convert the surrounding content into a properly opened+closed code block if that was the intent.
| ``` |
Description
This PR adds built-in AI coding agent skills (Claude Code / Copilot CLI) for common EmbodiChain development tasks and replaces verbose boilerplate examples in
AGENTS.mdwith concise skill references.Changes
.claude/skills/):add-functor,add-task-env,add-test,pre-commit-check,pr,benchmarkSkill summary
/add-task-envEmbodiedEnvtask/add-functor/add-test/pre-commit-check/pr/benchmarkType of change
Checklist
black .command to format the code base.🤖 Generated with Claude Code