Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill rust-crate-ci -a claude-code
Open on GitHub

What 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.rs following 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-code

2Manually: put the files in place

~/.claude/skills/rust-crate-ci/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/rust-crate-ci/

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

Similar skills

All skills for Programming languages →

From the same set121

The whole set →
commit-pr The commit-pr skill guides commits, pull request updates, and CI checks in opencode-swarm. Use it when publishing issue-related code changes or closing out a PR. CX Codex +1 ★ 539repo stars contributing contributing walks an agent through the full pull-request cycle in the opencode-swarm repo: branch naming, commit format, a release-notes fragment, local checks and the PR template. CX Codex +1 ★ 539repo stars clarify-spec clarify-spec resolves spec clarification markers and ambiguous requirements in Swarm projects by asking targeted questions one at a time. CX Codex +1 ★ 539repo stars pre-phase-briefing pre-phase-briefing builds phase-start context, reviews prior retrospectives, and checks whether the referenced codebase matches the planned work. CX Codex +1 ★ 539repo stars clarify clarify filters requirements through a four-stage funnel with critic evaluation to build decision packets without noisy questions. CX Codex +1 ★ 539repo stars editing-skills Use this skill before editing SKILL.md files in opencode-swarm. It explains the repository’s mirror, adapter, and package-shipping rules. CX Codex +1 ★ 539repo stars pr-reviewer pr-reviewer — a read-only subagent that reviews pull requests in the opencode-swarm plugin. It rebuilds what the PR was meant to do, then checks the code against that. CX Codex +1 ★ 539repo stars git-revert-safety git-revert-safety guides safe Git commit reverts and merge rollbacks without corrupting version manifests or lockfiles. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open