--- title: "rust-best-practices by massimodeluisa · skilld" canonical_url: "https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill" meta: description: "Write and review production Rust using the official API Guidelines, Style Guide, and this engineering standard: allocation contracts, ownership, Result… From massimodeluisa/rust-best-practices-skill." "og:description": "Write and review production Rust using the official API Guidelines, Style Guide, and this engineering standard: allocation contracts, ownership, Result… From massimodeluisa/rust-best-practices-skill." "og:title": "rust-best-practices by massimodeluisa" "twitter:description": "Write and review production Rust using the official API Guidelines, Style Guide, and this engineering standard: allocation contracts, ownership, Result… From massimodeluisa/rust-best-practices-skill." "twitter:title": "rust-best-practices by massimodeluisa" --- ` [All skills](https://skilld.dev/skills) [![massimodeluisa avatar](https://skilld.dev/_img/avatar?url=https%3A%2F%2Fgithub.com%2Fmassimodeluisa.png%3Fsize%3D96)](https://skilld.dev/gh/massimodeluisa) # **/rust-best-practices** [@d521b51](https://github.com/massimodeluisa/rust-best-practices-skill/commit/d521b511ddced77690a0f3e9ac476b7565afcc32 "Your agent reads SKILL.md at commit d521b51") by [MDL](https://skilld.dev/gh/massimodeluisa)· [massimodeluisa](https://skilld.dev/gh/massimodeluisa)/ [rust-best-practices-skill](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill)·1 stars Write and review production Rust using the official API Guidelines, Style Guide, and this engineering standard: allocation contracts, ownership, Result vs panic, debug\_assert, Clippy, tests, rustdoc, unsafe, and Cargo CI. Use when writing, reviewing, or refactoring Rust; choosing borrow vs clone; designing crate APIs; handling errors; bounding heap use; configuring clippy or rustfmt; or when the user runs /rust-best-practices. Do not use for other languages. Triggers: rust, rustc, cargo, clippy, rustfmt, ownership, clone, borrow, Result, unwrap, expect, panic, thiserror, anyhow, heapless, no\_std, allocation, debug\_assert, type-state, Send, Sync, unsafe, FFI, rustdoc, MSRV, rust-best-practices, rust style, rust guidelines - 11 files - 67.7 KB - MIT - Updated 2 weeks ago - [GitHub](https://github.com/massimodeluisa/rust-best-practices-skill/blob/d521b511ddced77690a0f3e9ac476b7565afcc32/skills/rust-best-practices/SKILL.md "View SKILL.md on GitHub") - [No alerts](#third-party-checks "Third-party checks: No alerts · 3 checks · Risk SAFE") ## SKILL.md 6 KB **≈188** tokens always: the name and description. **≈1.3k** when used: this file. **≈16k** more on demand in 10 files. ## Rust Best Practices Apply this standard when writing or reviewing Rust. Engineering guide, not a tutorial. ### Authority 1. **Live official docs** for language, naming, formatting, and public API shape. Start with the [Style Guide](https://doc.rust-lang.org/stable/style-guide/) and the [API Guidelines](https://rust-lang.github.io/api-guidelines/). Map: [references/official.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/official.md). 2. **This skill** for allocation contracts, bounds, `debug_assert!`, heapless cores, determinism, and CI. Load the matching reference; do not invent a rule that lives there. MUST / MUST NOT: required unless an approved architecture decision documents an exception. SHOULD / SHOULD NOT: default; a deviation needs a concrete reason in review. MAY: optional and context-dependent. Correctness, safety, determinism, and maintainability outrank cleverness. Measure performance. Design allocation and bounds into the API before profiling. Fetch current official docs for library or toolchain syntax. Do not invent APIs from memory. ### How to use - `/rust-best-practices`: apply the standard to the current Rust work. - `/rust-best-practices `: review that crate or file. For each finding: quote the line, name the rule (official `C-*` id or a heading in this skill), give the fix. Load only what the task needs, same turn, in parallel: | Task | Read | | --- | --- | | Naming, rustdoc sections, official checklist | [official.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/official.md) | | Memory profile, heapless, output buffers, hidden alloc | [allocation.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/allocation.md) | | Borrow vs clone, Copy, `into_`/`to_`/`as_` | [ownership.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/ownership.md) | | `Result`, panic, `thiserror`/`anyhow`, checked math, `debug_assert!` | [errors.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/errors.md) | | Functions, iterators, dispatch, type-state, boolean blindness | [design.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/design.md) | | Pointers, `Send`/`Sync`, `unsafe`, FFI | [unsafe.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/unsafe.md) | | Measure, layout, clones, flamegraph | [performance.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/performance.md) | | rustfmt, Clippy, tests, docs, deps, MSRV, CI | [quality.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/quality.md) | | Review pass, anti-patterns | [review.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/review.md) | ### Always-on rules #### Types and APIs - MUST make invalid states hard to represent: newtypes, enums, `Option`, `Result`, type-state where lifecycle matters. - MUST keep fields private unless direct access is the contract ([C-STRUCT-PRIVATE](https://rust-lang.github.io/api-guidelines/future-proofing.html#c-struct-private)). - MUST follow official `as_` / `to_` / `into_` conversion naming ([C-CONV](https://rust-lang.github.io/api-guidelines/naming.html#c-conv)). - SHOULD return values from general library APIs ([C-NO-OUT](https://rust-lang.github.io/api-guidelines/predictability.html#c-no-out)). MUST use caller-owned buffers when the declared memory profile is heapless or allocation-free ([C-CALLER-CONTROL](https://rust-lang.github.io/api-guidelines/flexibility.html#c-caller-control)). - NEVER use a raw `u32` for every identifier merely because the representation matches. #### Memory - MUST declare a memory profile for each crate and performance-sensitive public operation: **strict heapless**, **allocation-free steady state**, or **allocation-conscious**. Details: [allocation.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/allocation.md). - MUST keep runtime work bounded (iterations, recursion, queues, retries, output, concurrency). - MUST report capacity exhaustion as a typed error. MUST NOT spill to the heap, drop entries, or switch to an unbounded fallback in silence. - NEVER treat `Cow::into_owned()`, `format!()`, or a spill-capable small-vector as heapless. #### Ownership - SHOULD take `&T`, `&str`, `&[T]`, `&Path` unless ownership transfer is required. - SHOULD pass small `Copy` values by value. Measure ABI and target when size is in question; do not apply a universal byte cutoff. - NEVER clone to silence the borrow checker. #### Errors and asserts - MUST return `Result` for recoverable failure. MUST NOT `unwrap()` / `expect()` on production paths. - MUST use checked arithmetic at trust boundaries before indexing or allocating. - MUST validate external input in all builds. NEVER use `debug_assert!` as caller validation or as the only `unsafe` precondition. - SHOULD use `thiserror` in libraries, `anyhow` only at binary boundaries. #### Unsafe and concurrency - MUST `#![forbid(unsafe_code)]` in crates that do not need unsafe. - MUST document every unsafe block with `SAFETY:`. - MUST NOT add unsafe `Send`/ `Sync` impls without a written proof. - SHOULD prefer a single owner or bounded message passing over `Arc>` as an ownership escape hatch. #### Quality - MUST run `cargo fmt --all -- --check` and `cargo clippy --workspace --all-targets --all-features --locked -- -D warnings` in CI (explicit feature matrix if `--all-features` is invalid). - SHOULD prefer `#[expect(...)]` over `#[allow(...)]`, local and justified. - MUST link every committed TODO to an issue: `// TODO(#123): ...`. ### Official docs Cite the live page. Do not restate official rules as if they originated here. Minimum set: Style Guide, API Guidelines checklist, `debug_assert!`, `no_std`, `alloc`, Clippy configuration, Cargo profiles. Full list: [official.md](https://skilld.dev/gh/massimodeluisa/rust-best-practices-skill/rust-best-practices/-/references/official.md). Source: [SKILL.md on GitHub](https://github.com/massimodeluisa/rust-best-practices-skill/blob/d521b511ddced77690a0f3e9ac476b7565afcc32/skills/rust-best-practices/SKILL.md) ## Third-party checks
No alerts15d3 checks · Risk SAFE - Gen Agent Trust Hub15d The skill provides a comprehensive set of Rust engineering standards and best practices for writing and reviewing code. It covers memory allocation, API design, error handling, and performance optimization. No malicious behavior or security risks were identified. - Socket15d No alerts - Snyk15d Risk: LOW · No issues
## Provenance [Signed by skilld at d521b51.](https://github.com/massimodeluisa/rust-best-practices-skill/commit/d521b511ddced77690a0f3e9ac476b7565afcc32 "d521b511ddced77690a0f3e9ac476b7565afcc32") This ties the file your Agent reads to that commit on GitHub. It does not review the instructions. Last checked against GitHub 2 weeks ago. Activeupdated 2 weeks ago ## Capability
Other metadata
metadata
``` { "author": "massimodeluisa", "version": "1.0.0", "website": "https://www.rust-lang.org/" } ```
## README badge ![README badge for massimodeluisa/rust-best-practices-skill](https://skilld.dev/b/massimodeluisa/rust-best-practices-skill?theme=light&label=0) ## Related skills - - - - - -