Contributing to EmbodiChain

Claude Code is an AI-powered CLI that can assist you throughout the contribution workflow — from understanding the codebase to writing, reviewing, and debugging code.

Setup

Install Claude Code and authenticate:

npm install -g @anthropic-ai/claude-code
claude

A CLAUDE.md file is present at the root of this repository. Claude Code reads it automatically at startup to load project conventions, structure, and style rules, so it is context-aware from the first prompt.

Skills

Claude Code skills are built-in slash commands that automate common development tasks. They scaffold code, run checks, and enforce project conventions so you can focus on your logic instead of boilerplate. Invoke any skill by typing its command in the Claude Code prompt.

When to use each skill

/add-functor — Use when adding a new observation, event, reward, action, dataset, or randomization functor to an EmbodiChain environment. The skill will ask for the functor type and name, then generate the function- or class-style implementation with proper docstrings, type hints, and __all__ exports.

/add-task-env — Use when creating a new task environment, including expert demonstration tasks, RL tasks, or any EmbodiedEnv subclass. The skill scaffolds the task file with _setup_scene, _reset_idx, and evaluation logic, plus a test stub.

/add-test — Use when writing tests for any EmbodiChain module — functors, solvers, sensors, environments, or utilities. The skill determines the correct test file location, style (pytest function vs class), and generates tests with the standard Apache 2.0 header and named constants.

/pre-commit-check — Run this before committing or creating a PR. It verifies code formatting (black), file headers, type annotations, __all__ exports, and docstring completeness — the same checks the CI pipeline enforces.

/pr — Use after committing your changes to create a pull request. The skill checks git state, determines the PR type, drafts a description following the project template, runs formatting, creates a feature branch, and opens the PR via gh CLI with the correct labels.

/benchmark — Use when you need to measure the performance of a module (IK solvers, grasp samplers, metrics, etc.). The skill generates a well-structured benchmark script following project conventions.

Suggested workflows

Explore the codebase before making changes

> Explain how the Functor/Manager pattern works in embodichain/lab/gym/envs/managers/
> How does the Action Manager work with EmbodiedEnv for RL tasks?
> Show me an example of how a randomization functor is registered in a task config.

Implement a new feature

> I want to add a new observation functor that returns the end-effector velocity.
  Which existing functor should I model it after?
> /add-functor

Validate style and formatting before submitting

> Review my changes in embodichain/lab/gym/envs/managers/randomization/visual.py
  for style issues, missing type hints, and docstring completeness.
> /pre-commit-check

Write or update tests

> /add-test

Understand a bug

> I'm getting a KeyError in observation_manager.py at line 42 when env_ids is None.
  What could cause this and how should it be fixed?

Create a pull request

After you've made your changes and committed them:

> /pr

The /pr skill will guide you through checking git state, determining the PR type, drafting a description, running formatting, and creating the PR with proper labels.

Tips

• Always run /pre-commit-check after making changes — it catches the same issues the CI pipeline checks.
• Claude Code respects the CLAUDE.md conventions. If you notice it deviating (wrong docstring style, missing __all__, etc.), point it out and it will correct the output.
• 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.