rust-crate-ci — Claude Code skill: Rust crate CI checks before push
rust-crate-ci — a skill for editing the runners/swarm-sandbox-runner crate: it fixes the order of local checks and flags Windows breakage that only CI would catch.
MIT ★ 539 updated 2026-10-29
npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-ci -a claude-codeWhat rust-crate-ci does
The skill covers one crate in the repo, runners/swarm-sandbox-runner, and the rust-sandbox-runner job that gates it on windows-latest. Four commands, in a fixed order: cargo fmt --check, then cargo clippy --all-targets -- -D warnings, then cargo test --all-targets, then cargo build --release. Order matters. A formatting failure hides the clippy output, so nothing else runs.
Most of the text is about traps. rustfmt decides per syntax item, so a format! you split by hand may collapse onto one line, while a call you thought fit gets broken up. The advice: run cargo fmt and read the diff instead of formatting manually. Clippy notes cover the pinned windows-rs version, raw HANDLE values that cannot cross threads, imports that exist only under #[cfg(windows)], and Win32 structs that should use ..Default::default().
The path section is where real bugs sit. canonicalize returns a \\?\ prefix on Windows, GitHub Actions hands out %TEMP% as RUNNER~1, and comparing one form with the other fails silently, so both sides get canonicalized. Codes 64–69 in error.rs are frozen for runner-client.ts, and an exit event must fire on the timeout and quota paths too. No cargo in PATH? Push a draft PR and read the CI log.
What it helps with
- run fmt, clippy, tests and the release build in the right order
- fix a clippy failure caused by
-D warnings - catch a
\\?\path mismatch before CI does - keep the IPC exit codes intact while editing
error.rs - explain why
%TEMP%on GitHub Actions does not match the policy root
Example prompts for the agent
- Load rust-crate-ci and run the pre-push checks for
runners/swarm-sandbox-runner. - Fix the path comparison in
temp_watcher.rsfollowing rust-crate-ci. - Check rust-crate-ci: why does clippy reject this
HANDLE?
How to install rust-crate-ci
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-ci -a claude-code2Manually: put the files in place
~/.claude/skills/rust-crate-ci/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rust-crate-ci/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-ci -a codex2Manually: put the files in place
.agents/skills/rust-crate-ci/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-ci -a cursor2Manually: put the files in place
.cursor/skills/rust-crate-ci/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ZaxbyHub/opencode-swarm .claude/skills/rust-crate-ci2Manually: put the files in place
.github/skills/rust-crate-ci/SKILL.md1Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-ci -a gemini-cli2Platform CLI
gemini skills install https://github.com/ZaxbyHub/opencode-swarm --path .claude/skills/rust-crate-ciManually: put the files in place
.devin/skills/rust-crate-ci/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-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 rust-crate-ci
How do I install rust-crate-ci in Claude Code?
Run npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-ci -a claude-code. The skill file lands at ~/.claude/skills/rust-crate-ci/SKILL.md.
What does rust-crate-ci do?
It tells the agent how to validate the runners/swarm-sandbox-runner crate locally and which Windows-specific mistakes the windows-latest job will reject.
Do I need a Windows toolchain to use it?
No. The skill accounts for machines without cargo in PATH: open a draft PR and read the CI log instead of guessing what failed.
Source text
SKILL.md · MIT
---
name: rust-crate-ci
description: >
Load before editing any Rust crate in this repo (currently runners/swarm-sandbox-runner).
Covers the mandatory local validation gate, common rustfmt/clippy pitfalls, and
Windows-specific Rust correctness patterns that CI enforces but are hard to catch locally
without a Windows toolchain.
metadata:
audience: swarm-plugin
effort: low
---
# Rust Crate CI Guide
This repo contains a Rust crate at `runners/swarm-sandbox-runner/`. The CI job that
validates it is `rust-sandbox-runner` (runs on `windows-latest`). This guide prevents
the most common failure modes before they reach CI.
## Mandatory local gate (run in order before pushing)
```powershell
cd runners/swarm-sandbox-runner
# 1. Format check — CI fails here first; clippy will not run if this fails
cargo fmt --check
# 2. Clippy — -D warnings makes all warnings hard errors; --all-targets matches CI,
# which also lints tests, examples, and benches (ci.yml rust-sandbox-runner job)
cargo clippy --all-targets -- -D warnings
# 3. Tests — --all-targets matches CI; Windows-specific tests are gated with #[cfg(windows)]
cargo test --all-targets
# 4. Release build — confirms the binary compiles with optimizations
cargo build --release
```
Run them in this exact order. If `cargo fmt --check` fails, fix formatting first —
clippy errors may be masked until fmt passes.
If `cargo` is not in PATH locally (e.g. you are on a machine without Rust installed),
push to a draft PR and let CI run the checks. Read the CI log carefully; do not guess
at what failed.
## How rustfmt makes decisions
rustfmt (current stable — `rust-toolchain.toml` floats on `channel = "stable"`)
applies line-length thresholds per syntax item, not per file or per block.
Two patterns that look equivalent locally can format differently:
**Long `format!` macros:** If the total length of `format!("...", arg)` exceeds the
line limit, rustfmt splits it. If it fits on one line, rustfmt collapses it.
```rust
// rustfmt will COLLAPSE this to one line if it fits:
return Err(RunnerError::PolicyViolation {
reason: format!(
"cwd resolves outside allowed roots (symlink egress): {canonical_str}"
),
});
// rustfmt will SPLIT this if it exceeds the limit:
events::emit(&events::denial_event("deny_symlink_egress", Some(canonical_str)));
// becomes:
events::emit(&events::denial_event(
"deny_symlink_egress",
Some(canonical_str),
));
```
**Rule of thumb:** After editing, always run `cargo fmt` (not `--check`) locally to
apply rustfmt's opinion, then read the diff before committing. Do not hand-format
and assume rustfmt agrees.
## Common clippy errors in this codebase
**`windows-rs` 0.58 API changes:** Several Win32 APIs changed signatures between
`windows` crate versions. The `Cargo.toml` pins the version; do not bump it without
checking the full API diff.
**`HANDLE` is not `Send + Sync`:** Raw `HANDLE` values cannot be sent across threads.
Wrap them in a newtype with `unsafe impl Send` and `unsafe impl Sync`, or use
`OwnedHandle` from `std::os::windows::io`. The kill-callback pattern in
`temp_watcher.rs` uses raw `isize` (handle as integer) to sidestep this.
**Unused imports:** `#[cfg(windows)]` blocks frequently hide imports that are used
only on Windows. On non-Windows builds, the import becomes dead code. Use
`#[cfg(windows)]` on the `use` statement itself or accept the `#[allow(unused_imports)]`
annotation for platform-conditional code.
**`struct` default initialization:** For Win32 structs like `STARTUPINFOW`, use a
struct initializer with `..Default::default()` rather than `unsafe { std::mem::zeroed() }`
— clippy flags the latter when `Default` is available.
## Windows path normalization (critical correctness patterns)
These bugs are invisible on Linux/macOS CI and will only appear on `windows-latest`.
### `std::fs::canonicalize` always prepends `\\?\`
On Windows, `canonicalize` typically returns a verbatim extended-length path with
the `\\?\` prefix, but this is not guaranteed across all Windows configurations and
path forms. Always use `.strip_prefix` with a fallback:
```
C:\foo\bar → \\?\C:\foo\bar (typical)
```
If you compare a canonicalized path against a policy root stored without this prefix,
the comparison silently fails. Strip the prefix before comparing, always with `.unwrap_or`:
```rust
let lower = canonical.to_string_lossy().to_lowercase();
let canonical_str = lower.strip_prefix("\\\\?\\").unwrap_or(&lower);
```
Apply the same strip to both sides of any comparison.
### GitHub Actions CI uses 8.3 short names in `%TEMP%`
`std::env::temp_dir()` on GitHub Actions Windows runners returns a path like:
```
C:\Users\RUNNER~1\AppData\Local\Temp
```
But `std::fs::canonicalize` expands it to:
```
C:\Users\runneradmin\AppData\Local\Temp
```
If your code stores the `temp_dir()` path as a policy root and then canonicalizes
the cwd, the comparison will fail because `RUNNER~1` ≠ `runneradmin`.
**Fix:** Canonicalize both the policy root AND the cwd before comparing. Fall back
to the raw value if the root does not exist on disk yet:
```rust
let root_resolved = std::fs::canonicalize(root)
.map(|p| p.to_string_lossy().to_lowercase())
.unwrap_or_else(|_| root.to_lowercase());
let root_cmp = root_resolved
.strip_prefix("\\\\?\\")
.unwrap_or(&root_resolved)
.to_owned();
```
### `WaitForSingleObject` return value semantics
`WAIT_TIMEOUT` is `0x00000102u32`, not a Rust `Err`. Check the return value
explicitly before treating the child as having exited normally.
## IPC contract stability
The exit codes in `error.rs` are **frozen** — do not renumber them. TypeScript
callers in `runner-client.ts` depend on these values:
| Code | Meaning |
|------|---------|
| 0 | Child exited zero (or non-zero child exit code passed through directly) |
| 64 | Policy violation |
| 65 | Temp quota exceeded |
| 66 | Wall-clock timeout |
| 67 | Launcher misconfiguration or policy parse error (invalid JSON from caller) |
| 68 | OS API failure, I/O error, or JSON error |
| 69 | Probe failed |
The NDJSON event types on stderr (`start`, `denial`, `quota_exceeded`, `exit`) are
also frozen. Adding new event types is safe; renaming or removing existing ones
is a breaking IPC change.
**Exit events are required on every termination path.** Emit `exit_event` before
returning from both the wall-clock timeout path and the temp-cap kill path, not
only on the normal exit path. TypeScript consumers block waiting for an `exit` event.
## CI workflow reference
The job is defined in `.github/workflows/ci.yml` as `rust-sandbox-runner`.
It runs on `windows-latest` with the toolchain pinned in `runners/swarm-sandbox-runner/rust-toolchain.toml`.
All third-party `uses:` actions are pinned to 40-character SHAs per the repo policy.
Steps in order: fmt check → clippy → tests → release build → probe smoke test.
© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm