dart-ci — Claude Code skill: debugging DART CI on GitHub Actions
Walks an agent through a failed DART CI run: gh calls for logs, a table of platform-specific breakages, and a local repro loop.
BSD-2-Clause 1 installs ★ 1,232 updated 2026-10-29
npx skills add dartsim/dart --skill dart-ci -a claude-codeWhat dart-ci does
The skill fires when a PR check goes red or something looks off in GitHub Actions. It hands the agent a set of gh calls: list runs for a branch, pull the failing job log with gh run view <RUN_ID> --job <JOB_ID> --log-failed, read status and URL as JSON. Reruns are gated: the skill says to do them only once a maintainer or the user says yes.
A table maps common breakages to fixes. Lint failures go through pixi run lint. A Codecov patch complaint means writing tests for the lines nobody covered. On FreeBSD, RTTI trouble is fixed by swapping dynamic_cast for static_cast with a type enum; a SEGFAULT on macOS ARM64 by moving from alloca() and VLAs to std::vector<T>. Filament has its own lane: configure with -DDART_ENABLE_GUI_SMOKE_TESTS=ON, then pixi run test-gui, and native-window failures on headless Linux go under xvfb-run. That smoke option is off by default and wants a graphics device.
There is also a workflow map covering the Ubuntu, macOS, Windows, FreeBSD, SIMD, toolchain and Gazebo pipelines with their platforms. FreeBSD, toolchain, CodeQL, wheels and a few other legs run only in nightly.yml; their failures land as nightly-failure issues rather than PR checks. A red nightly will not show up in the PR list, so looking there wastes time. On cache problems the skill is blunt: read the restore and save steps and the job timestamps instead of trusting any estimate of how long a run should take.
What it helps with
- read the failing job log to see which step broke the PR
- reproduce a gz-physics failure locally with
pixi run -e gazebo test-gz - clear a macOS ARM64 SEGFAULT by dropping
alloca()forstd::vector<T> - work out why a failure never appeared among PR checks
- run the Filament GUI smoke tests and locate the window problem
Example prompts for the agent
- Check why
ci_macos.ymlfailed on PR<PR_NUMBER>and show me the failing job log. - Reproduce the gz-physics failure in the gazebo environment and tell me what to change.
- Get the status of run
<RUN_ID>; do not rerun anything until I approve.
How to install dart-ci
1Skills CLI (Vercel)
npx skills add dartsim/dart --skill dart-ci -a claude-code2Manually: put the files in place
~/.claude/skills/dart-ci/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dart-ci/
1Skills CLI (Vercel)
npx skills add dartsim/dart --skill dart-ci -a codex2Manually: put the files in place
.agents/skills/dart-ci/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add dartsim/dart --skill dart-ci -a cursor2Manually: put the files in place
.cursor/skills/dart-ci/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install dartsim/dart .claude/skills/dart-ci2Manually: put the files in place
.github/skills/dart-ci/SKILL.md1Skills CLI (Vercel)
npx skills add dartsim/dart --skill dart-ci -a gemini-cli2Platform CLI
gemini skills install https://github.com/dartsim/dart --path .claude/skills/dart-ciManually: put the files in place
.devin/skills/dart-ci/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add dartsim/dart --skill dart-ci -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about dart-ci
How do I install dart-ci in Claude Code?
Run npx skills add dartsim/dart --skill dart-ci -a claude-code. The skill lands at ~/.claude/skills/dart-ci/SKILL.md.
What does dart-ci do?
It gives the agent gh commands, a failure-mode table and repro steps for broken DART runs in GitHub Actions.
Where do nightly failures show up?
Several legs run only in nightly.yml and report as nightly-failure issues instead of PR checks.
Source text
SKILL.md · BSD-2-Clause
---
name: dart-ci
description: "DART CI: GitHub Actions, cache debugging, and platform-specific failures"
---
# DART CI/CD Troubleshooting
Load this skill when debugging CI failures or working with GitHub Actions.
When the failing claim depends on model/scene structure, physics behavior, or
Filament output, also load `dart-verify-sim` and reproduce it with a text oracle plus
assessed visual evidence. Document a visual exception when graphics support is
unavailable or not applicable in the failing environment.
## Quick Commands
```bash
# Monitor PR checks
gh pr checks <PR_NUMBER>
gh pr view <PR_NUMBER> --json headRefOid,mergeStateStatus,statusCheckRollup
# View run details
gh run list --branch <BRANCH> -e pull_request -L 20
gh run view <RUN_ID> --json status,conclusion,url
# Debug failures
gh run view <RUN_ID> --job <JOB_ID> --log-failed
gh run view <RUN_ID> --json jobs --jq '.jobs[] | {name, databaseId}'
# Rerun failed jobs only after explicit maintainer/user approval
gh run rerun <RUN_ID> --failed
gh run rerun <RUN_ID> --job <DATABASE_ID>
```
## Full Documentation
For complete CI/CD guide: `docs/onboarding/ci-cd.md`
## Common Failure Modes
| Failure Type | Solution |
| -------------------- | -------------------------------------------------------- |
| Formatting fails | `pixi run lint`; push only after approval |
| Codecov patch fails | Add tests for uncovered lines |
| FreeBSD RTTI fails | Use type enums + `static_cast` instead of `dynamic_cast` |
| macOS ARM64 SEGFAULT | Replace `alloca()`/VLAs with `std::vector<T>` |
| RTD build fails | Use defensive `.get(key, default)` patterns |
| gz-physics fails | Reproduce with `pixi run -e gazebo test-gz` |
| CI Filament fails | Configure with `pixi run config -- -DDART_ENABLE_GUI_SMOKE_TESTS=ON`, then run `pixi run test-gui`; native-window failures with `pixi run ctest --test-dir build/<env>/cpp/Release -L filament-native` (`pixi run ctest --test-dir build/<env>/cpp -C Release -L filament-native` on Windows; under `xvfb-run` on headless Linux); consumer failures with `pixi run python scripts/test_gui_install.py` on that build directory |
## Workflow Architecture
The CI workflows that a failing PR check belongs to (full workflow index:
`docs/onboarding/ci-cd.md` § "Workflow Index"):
| Workflow | Purpose | Platforms |
| ------------------- | -------------------------------------- | ---------- |
| `ci_ubuntu.yml` | AI checks, lint, build, test, coverage | Ubuntu |
| `ci_macos.yml` | Lint, build, test | macOS |
| `ci_windows.yml` | Lint, build, test | Windows |
| `ci_filament.yml` | Filament GUI functional lane (`<runner>-Filament-functional`; not yet required) | Ubuntu, macOS; Windows nightly |
| `ci_freebsd.yml` | Build + test (VM) | FreeBSD |
| `ci_simd.yml` | SIMD x86 instruction-level matrix | Ubuntu x86_64 |
| `ci_toolchain.yml` | Alternate toolchain build + test | Ubuntu |
| `ci_gz_physics.yml` | Gazebo integration | Ubuntu |
| `api_doc.yml` | Doxygen API docs build | Ubuntu |
FreeBSD, toolchain, CodeQL, wheels, Linux ASan/coverage/Eigen alignment, macOS
install, the Windows VS 2022 leg and build-requirement checks, and the Filament
Windows leg run only in `nightly.yml`; their failures arrive as
`nightly-failure` issues, not PR checks.
Default test gates exclude device-dependent CTests labeled `gui-device` and
Python rendering tests; device-free GUI tests still run. `pixi run test-gui`
selects all `gui` CTests except `filament-native`. The capture smoke option
`DART_ENABLE_GUI_SMOKE_TESTS` defaults to `OFF`, needs a graphics device, and
replaces `DART_ENABLE_GUI_OSG_SMOKE_TESTS`; `CI Filament` enables it.
## Downstream Compatibility Policy
Package, exported-target, collision, constraint, and dependency changes can
affect Gazebo/gz-physics even when local unit tests pass. Reproduce those
failures with the Gazebo Pixi environment when practical:
`pixi run -e gazebo test-gz`.
## Fast Iteration Loop
1. Identify failing step from job logs
2. Reproduce locally with same build toggles
3. Fix the smallest failing test
4. Push only after explicit maintainer/user approval, then monitor:
`gh run view <RUN_ID> --json status,conclusion,url`
## Caching And Duration
Treat the current run and job logs as authoritative. Inspect cache restore/save
steps and job timestamps before changing a key; do not rely on fixed duration
or cache-speed estimates in this skill.
© dartsim · BSD-2-Clause · dartsim/dart