Physics Engine Tutor Skill

A comprehensive skill for learning physics engine concepts and implementations across multiple engines.

What This Skill Does

Helps users deeply understand physics simulation concepts and their implementations at the source code level. Designed for robotics researchers working on humanoid robots, whole-body control (WBC), reinforcement learning (RL), and Sim-to-Real transfer.

When to Use

Trigger this skill when you want to:

• Learn about physics engine concepts (solvers, collision detection, constraints, integrators, etc.)
• Understand source code implementations in C++/CUDA/Python
• Compare implementations across different engines
• Deep dive into specific algorithms (GJK, EPA, PGS, LCP, ABA, CRBA)
• Connect theory to practice for robotics applications

Trigger phrases:

• "学习", "讲解", "理解", "explain", "teach me about" + physics topics
• "对比 Newton 和 MuJoCo 的求解器"
• "How does constraint solving work in PhysX?"
• "Show me the Jacobian mapping code in MuJoCo"

Supported Engines

The skill covers the physics engine workspace at /home/fan/physics-engine:

• Newton — GPU-accelerated physics on NVIDIA Warp with MuJoCo Warp backend
• Genesis World — Unified multi-physics platform (rigid, FEM, MPM, SPH, PBD)
• MuJoCo — Google DeepMind's Multi-Joint dynamics with Contact (C/C++ core)
• MuJoCo Warp — GPU-accelerated MuJoCo for high-throughput parallel simulation
• Warp — NVIDIA Warp framework, foundation for Newton and MuJoCo Warp
• PhysX — NVIDIA's real-time physics SDK with ovphysx, Blast, Flow
• IsaacLab — External installation for RL environments

Key Features

1. User-Focused Teaching

• Tailored for humanoid robotics researchers (29 DoF, 50Hz control loops)
• Prioritizes user's weak points: Jacobian mapping, LCP/PGS solvers, integrators
• Connects source code to practical scenarios (Sim-to-Real parameter tuning)

2. Source Code Navigation

• Provides exact file paths with clickable links
• Shows line numbers for C/C++ implementations
• Extracts only critical 10-20 lines of code
• Explains math-to-code mapping explicitly

3. Comprehensive Coverage

• Forward dynamics & free acceleration
• Collision detection (broad phase, narrow phase, GJK, EPA)
• Contact solving (Jacobian construction, PGS iteration, friction cone)
• Time integration (semi-implicit Euler, RK4)
• Sim-to-Real interfaces (domain randomization parameters)

4. Multi-Engine Comparison

• Side-by-side comparisons when needed
• Highlights design differences (soft contact vs hard constraint)
• Explains tradeoffs and use cases

Output Format

Every explanation includes:

• ✅ Concise concepts (2-3 sentences)
• ✅ Clickable file links with line numbers
• ✅ Critical code snippets (10-20 lines)
• ✅ Design decisions (explains "why", not just "what")
• ✅ File index table for navigation
• ✅ Sim-to-Real connections when applicable

Example Usage

User: "讲解一下 MuJoCo 的接触求解器，特别是雅可比矩阵怎么映射的"

Skill output:
- Locates engine_solver.c with exact line numbers
- Shows Jacobian construction code (efc_J)
- Explains J_c^T * λ mapping from contact space to joint space
- Shows PGS iteration loop with friction cone projection
- Connects to Sim-to-Real: which parameters to tune for foot slip
- Provides file index with clickable links

Structure

This skill follows progressive disclosure principles:

physics-engine-tutor/
├── SKILL.md                          # Main skill (loaded when triggered)
├── README.md                         # This file
├── evals/
│   └── evals.json                    # Test cases for skill evaluation
├── references/                       # Loaded on-demand
│   ├── topic-locations.md            # Quick reference for finding topics
│   ├── explanation-templates.md      # Templates for different explanation types
│   └── platform-compatibility.md     # Cross-platform tool compatibility
└── scripts/                          # Executable scripts (not loaded into context)
    ├── grade_evals.py                # Grading script for evaluations
    └── grade_eval_2.py               # Additional grading utilities

Recent Updates (2026-05-31)

Critical Corrections

• PhysX Solver Definitions — Fixed errors about TGS and PGS
  • ✅ PGS = Projected Gauss-Seidel (not "Parallel")
  • ✅ TGS = Temporal Gauss-Seidel (not "Time-step")
  • Added comprehensive references/physx-solvers.md with source code verification
  • All definitions verified against PhysX source code (PxSceneDesc.h, DySolverCore.cpp)

Added Coverage

• MuJoCo Warp — GPU-accelerated MuJoCo implementation
• Warp — NVIDIA Warp framework and native kernels
• Enhanced C/C++ support — Better navigation for MuJoCo/PhysX source code
• PhysX Solver Comparison — Detailed PGS vs TGS technical comparison

Improved Teaching

• User context integration — Based on learning_tutorial.md guidance
• Weak point focus — Prioritizes Jacobian mapping, PGS/TGS solver, integrator details
• Math-to-code mapping — Explicit connections between equations and implementations
• Line number precision — Exact locations for C/C++ code

Updated Documentation

• New workspace structure — Reflects current directory organization
• Enhanced topic locations — Added MuJoCo/PhysX/Warp source file references
• Learning path — Four-module progression from dynamics to Sim-to-Real
• PhysX reference — New comprehensive solver comparison document

Cross-Platform Compatibility

Works across:

• Claude Code
• OpenAI Codex
• Gemini CLI
• Claude.ai

Tool names automatically adapt to platform conventions (see references/platform-compatibility.md).

Quality Standards

• Concise and direct (no verbosity)
• All file paths are clickable links
• Mandatory file index table and design decisions
• Focus on "why" not just "what"
• Match user's language (Chinese/English)
• Provide exact line numbers for C/C++ code
• Show math-to-code mapping for key equations

Improvements from Feedback

Based on user feedback from iteration-1:

Fixed Issues

1. ❌ Was too verbose → ✅ Now concise (2-3 sentences for concepts)
2. ❌ Plain text file paths → ✅ Clickable markdown links [file](path)
3. ❌ Missing file index → ✅ Required file index table
4. ❌ Missing design rationale → ✅ Required design decisions section
5. ❌ Large code dumps → ✅ Only 10-20 lines of critical code
6. ❌ Scripts in workspace → ✅ Moved to scripts/ folder
7. ❌ No progressive disclosure → ✅ Organized into SKILL.md + references/
8. ❌ Claude Code only → ✅ Cross-platform compatible

User Feedback Addressed

"我认为有点过于啰嗦，并且我需要对应文件的参考位置，以便于我直接点击到那个文件"

Translation: "I think it's too verbose, and I need clickable file reference locations so I can directly click to that file"

Solutions implemented:

• Mandatory conciseness requirements (2-3 sentences, 10-20 lines)
• ALL file paths must use [filename](path) format for VSCode navigation
• File index table is now REQUIRED
• Quality checklist enforces these requirements

Evaluation

Test cases in evals/evals.json verify:

1. Conciseness (not verbose)
2. Clickable file links (markdown format)
3. File index table (required)
4. Design decisions (required)
5. Short code snippets (10-20 lines)
6. Language matching (Chinese/English)

Run evaluations using the skill-creator workflow.

Related Skills

• mujoco_skillkit — MuJoCo development and debugging
• isaaclab-rl-skillkit — IsaacLab reinforcement learning
• mjlab-skillkit — mjlab project development

Development

Testing the Skill

1. Use the skill-creator workflow
2. Run test cases from evals/evals.json
3. Review outputs in the eval viewer
4. Check benchmark results for pass rates

Grading Scripts

Located in scripts/:

• grade_evals.py — Main grading script
• grade_eval_2.py — Additional grading utilities

These scripts check assertions like:

• Conciseness
• Clickable links
• File index table presence
• Design decisions section
• Code snippet length
• Language matching

Iteration History

• Iteration 1: Initial version, 87.5% pass rate (21/24 assertions)
  • Issues: Too verbose, plain text paths, missing file index
  • User feedback: Need clickable links, less verbosity
• Version 2.0 (2026-05-31): Major update
  • Added MuJoCo Warp, Warp, enhanced C/C++ support
  • Integrated user context from learning_tutorial.md
  • Enhanced weak point focus (Jacobian, PGS, integrators)
  • Added math-to-code mapping examples
  • Updated topic locations with C/C++ file references

Contributing

When improving this skill:

1. Keep SKILL.md under 300 lines
2. Move detailed guidance to references/
3. Keep scripts in scripts/ (never load into context)
4. Test across platforms (Claude Code, Codex, Gemini)
5. Run evaluations to verify improvements
6. Update this README with changes

Version

Last updated: 2026-05-31 Version: 2.0 (Major update with MuJoCo Warp, Warp, enhanced C/C++ support)

License

Part of the physics-engine workspace. See workspace CLAUDE.md for details.