rust-systems
Rust patterns for CLI tools, backend services, and general application code. Use when working with Rust, Cargo workspaces, axum/tokio services, clap CLIs, async concurrency, or configuring clippy, rustfmt, cargo-nextest, or Cargo.toml.
Install
npx skills add https://github.com/iliaal/ai-skills/tree/master/skills/rust-systems
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install iliaal-ai-skills@llmmart
git clone https://github.com/iliaal/ai-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole iliaal/ai-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Rust Systems & Services
Covers modern application-layer Rust (edition 2024): CLIs, web services, libraries. Not no_std/embedded.
Working rules
- Preserve error variants in libraries and add operational context at application boundaries.
- Distinguish missing configuration from unreadable or invalid files before writing replacements.
- Keep blocking work off async workers, bound queues and spawned work, and define shutdown behavior.
- Trace exported interfaces before treating a change as internal; verify installed runtime capabilities.
- Do not mutate process-wide state in concurrent tests; exercise the real binary and relevant feature combinations.
Unsafe Discipline
- Default: no
unsafe. If clippy flags it, don't#[allow]it; refactor. The#[expect]escape hatch below does not apply here; unsafe findings get fixed, not annotated. - Every
unsafeblock gets a// SAFETY:comment above it explaining why each invariant holds. No comment = reviewer rejects. - Keep
unsafeblocks minimal: wrap in a safe abstraction at module boundary, mark the modulepub(crate). - Use
miri(cargo +nightly miri test) on any crate containingunsafeor raw pointer arithmetic; it catches UB that optimizers mask. - Prefer
bytemuck,zerocopy,bytesover hand-rolled transmutes for zero-copy patterns. - Env-var writes are
unsafein edition 2024. Write them only inmain, before the runtime starts or any thread spawns. Concurrentgetenvis UB;OnceLockdoes not make it safe. Watch for lazyLD_LIBRARY_PATH-style writes on first use; hoist them to startup.
Discipline
- Simplicity first: every change as simple as possible, impact minimal code.
- Only touch what's necessary; avoid unrelated changes in a PR.
- No
#[allow(clippy::...)]as a shortcut; fix the underlying issue. When a suppression is genuinely warranted, write#[expect(clippy::lint_name, reason = "...")]instead:expectwarns once the lint stops firing, so a suppression that has outlived its cause reports itself, whereallowrots silently forever. (expectneeds Rust 1.81+; edition 2024 clears that floor.) - Before adding a trait or generic, verify it's used in 3+ places. Otherwise a concrete type is clearer.
bool::then_some(x)takesxby value: the argument is computed before the bool is consulted, so a guard written as a condition plus a fixed-width slice panics on exactly the inputs the condition was checking for:(b.len() >= 19 && b[4] == b'-').then_some(&v[..19])panics on any shorter value, exiting 101 inside the one function written to report the case as undetermined. Usethen(|| …), which is lazy. Clippy does not flag the difference. Grepthen_some(for an argument that indexes, slices, unwraps, or allocates. Related: a fixed-width slice is not a parse.&v[..19]also panics mid-character on non-ASCII, and comparing two such prefixes lexicographically drops the timezone offset, so01:00+02:00sorts after00:00Zwhile being an hour earlier. Parse and normalize, or reject.
Verify
cargo fmt --all -- --checkpasses with zero diffscargo clippy --workspace --all-targets --all-features -- -D warningspassescargo nextest run --workspace(orcargo test --workspace) passes with zero failures- When using nextest,
cargo test --doc --workspacealso passes; nextest does not run doctests cargo deny checkpasses (licenses, advisories, duplicates) for any crate going to production- No new
unsafewithout// SAFETY:comment
Task-specific references
Read the relevant reference before implementing or reviewing the matching behavior:
- For Cargo setup, workspace changes, public API reachability, build profiles, or CI: toolchain-and-interfaces.md.
- For errors, ownership, parsing boundaries, Tokio, shutdown, or concurrency: ownership-and-execution.md.
- For CLI/service entrypoints, production resilience, telemetry, or tests: applications-and-testing.md.
Existing specialized references, when the corresponding topic applies:
Files (ai-skills)
-
references
-
applications-and-testing.md 5 KB
Loading… -
axum-service.md 9.2 KB
Loading… -
build-profiles.md 2.1 KB
Loading… -
ci-pipeline.md 1.4 KB
Loading… -
cli-tools.md 8 KB
Loading… -
macros-and-os-boundaries.md 3.9 KB
Loading… -
observability.md 3.3 KB
Loading… -
ownership-and-execution.md 8.9 KB
Loading… -
performance.md 2.6 KB
Loading… -
production-resilience.md 3.7 KB
Loading… -
rustdoc.md 2.5 KB
Loading… -
toolchain-and-interfaces.md 5.6 KB
Loading…
-
-
SKILL.md 4.9 KB
--- name: rust-systems class: language description: >- Rust patterns for CLI tools, backend services, and general application code. Use when working with Rust, Cargo workspaces, axum/tokio services, clap CLIs, async concurrency, or configuring clippy, rustfmt, cargo-nextest, or Cargo.toml. paths: - "**/*.rs" - "**/Cargo.toml" --- # Rust Systems & Services Covers modern application-layer Rust (edition 2024): CLIs, web services, libraries. Not `no_std`/embedded. ## Working rules - Preserve error variants in libraries and add operational context at application boundaries. - Distinguish missing configuration from unreadable or invalid files before writing replacements. - Keep blocking work off async workers, bound queues and spawned work, and define shutdown behavior. - Trace exported interfaces before treating a change as internal; verify installed runtime capabilities. - Do not mutate process-wide state in concurrent tests; exercise the real binary and relevant feature combinations. ## Unsafe Discipline - Default: no `unsafe`. If clippy flags it, don't `#[allow]` it; refactor. The `#[expect]` escape hatch below does not apply here; unsafe findings get fixed, not annotated. - Every `unsafe` block gets a `// SAFETY:` comment above it explaining why each invariant holds. No comment = reviewer rejects. - Keep `unsafe` blocks minimal: wrap in a safe abstraction at module boundary, mark the module `pub(crate)`. - Use `miri` (`cargo +nightly miri test`) on any crate containing `unsafe` or raw pointer arithmetic; it catches UB that optimizers mask. - Prefer `bytemuck`, `zerocopy`, `bytes` over hand-rolled transmutes for zero-copy patterns. - **Env-var writes are `unsafe` in edition 2024. Write them only in `main`, before the runtime starts or any thread spawns.** Concurrent `getenv` is UB; `OnceLock` does not make it safe. Watch for lazy `LD_LIBRARY_PATH`-style writes on first use; hoist them to startup. ## Discipline - Simplicity first: every change as simple as possible, impact minimal code. - Only touch what's necessary; avoid unrelated changes in a PR. - No `#[allow(clippy::...)]` as a shortcut; fix the underlying issue. When a suppression is genuinely warranted, write `#[expect(clippy::lint_name, reason = "...")]` instead: `expect` warns once the lint stops firing, so a suppression that has outlived its cause reports itself, where `allow` rots silently forever. (`expect` needs Rust 1.81+; edition 2024 clears that floor.) - Before adding a trait or generic, verify it's used in 3+ places. Otherwise a concrete type is clearer. - **`bool::then_some(x)` takes `x` by value: the argument is computed before the bool is consulted**, so a guard written as a condition plus a fixed-width slice panics on exactly the inputs the condition was checking for: `(b.len() >= 19 && b[4] == b'-').then_some(&v[..19])` panics on any shorter value, exiting 101 inside the one function written to report the case as undetermined. Use `then(|| …)`, which is lazy. Clippy does not flag the difference. Grep `then_some(` for an argument that indexes, slices, unwraps, or allocates. Related: **a fixed-width slice is not a parse**. `&v[..19]` also panics mid-character on non-ASCII, and comparing two such prefixes lexicographically drops the timezone offset, so `01:00+02:00` sorts after `00:00Z` while being an hour earlier. Parse and normalize, or reject. ## Verify - `cargo fmt --all -- --check` passes with zero diffs - `cargo clippy --workspace --all-targets --all-features -- -D warnings` passes - `cargo nextest run --workspace` (or `cargo test --workspace`) passes with zero failures - When using nextest, `cargo test --doc --workspace` also passes; nextest does not run doctests - `cargo deny check` passes (licenses, advisories, duplicates) for any crate going to production - No new `unsafe` without `// SAFETY:` comment ## Task-specific references Read the relevant reference before implementing or reviewing the matching behavior: - For Cargo setup, workspace changes, public API reachability, build profiles, or CI: [toolchain-and-interfaces.md](./references/toolchain-and-interfaces.md). - For errors, ownership, parsing boundaries, Tokio, shutdown, or concurrency: [ownership-and-execution.md](./references/ownership-and-execution.md). - For CLI/service entrypoints, production resilience, telemetry, or tests: [applications-and-testing.md](./references/applications-and-testing.md). Existing specialized references, when the corresponding topic applies: - [macros-and-os-boundaries.md](./references/macros-and-os-boundaries.md). - [rustdoc.md](./references/rustdoc.md). - [build-profiles.md](./references/build-profiles.md). - [performance.md](./references/performance.md). - [cli-tools.md](./references/cli-tools.md). - [production-resilience.md](./references/production-resilience.md). - [axum-service.md](./references/axum-service.md). - [observability.md](./references/observability.md). - [ci-pipeline.md](./references/ci-pipeline.md). -
SPEC.md 4.3 KB
Loading…
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.