name: rust-skills
description: >
Comprehensive Rust coding guidelines with 179 rules across 14 categories.
Use when writing, reviewing, or refactoring Rust code. Covers ownership,
error handling, async patterns, API design, memory optimization, performance,
testing, and common anti-patterns. Invoke with /rust-skills.
license: MIT
metadata:
author: leonardomso
version: "1.0.0"
sources:
- Rust API Guidelines
- Rust Performance Book
- ripgrep, tokio, serde, polars codebases

Rust Best Practices

Comprehensive guide for writing high-quality, idiomatic, and highly optimized Rust code. Contains 179 rules across 14 categories, prioritized by impact to guide LLMs in code generation and refactoring.

When to Apply

Reference these guidelines when:
- Writing new Rust functions, structs, or modules
- Implementing error handling or async code
- Designing public APIs for libraries
- Reviewing code for ownership/borrowing issues
- Optimizing memory usage or reducing allocations
- Tuning performance for hot paths
- Refactoring existing Rust code

Rule Categories by Priority

Quick Reference

1. Ownership & Borrowing (CRITICAL)

• own-borrow-over-clone - Prefer &T borrowing over .clone()
• own-slice-over-vec - Accept &[T] not &Vec<T>, &str not &String
• own-cow-conditional - Use Cow<'a, T> for conditional ownership
• own-arc-shared - Use Arc<T> for thread-safe shared ownership
• own-rc-single-thread - Use Rc<T> for single-threaded sharing
• own-refcell-interior - Use RefCell<T> for interior mutability (single-thread)
• own-mutex-interior - Use Mutex<T> for interior mutability (multi-thread)
• own-rwlock-readers - Use RwLock<T> when reads dominate writes
• own-copy-small - Derive Copy for small, trivial types
• own-clone-explicit - Make Clone explicit, avoid implicit copies
• own-move-large - Move large data instead of cloning
• own-lifetime-elision - Rely on lifetime elision when possible

2. Error Handling (CRITICAL)

• err-thiserror-lib - Use thiserror for library error types
• err-anyhow-app - Use anyhow for application error handling
• err-result-over-panic - Return Result, don't panic on expected errors
• err-context-chain - Add context with .context() or .with_context()
• err-no-unwrap-prod - Never use .unwrap() in production code
• err-expect-bugs-only - Use .expect() only for programming errors
• err-question-mark - Use ? operator for clean propagation
• err-from-impl - Use #[from] for automatic error conversion
• err-source-chain - Use #[source] to chain underlying errors
• err-lowercase-msg - Error messages: lowercase, no trailing punctuation
• err-doc-errors - Document errors with # Errors section
• err-custom-type - Create custom error types, not Box<dyn Error>

3. Memory Optimization (CRITICAL)

• mem-with-capacity - Use with_capacity() when size is known
• mem-smallvec - Use SmallVec for usually-small collections
• mem-arrayvec - Use ArrayVec for bounded-size collections
• mem-box-large-variant - Box large enum variants to reduce type size
• mem-boxed-slice - Use Box<[T]> instead of Vec<T> when fixed
• mem-thinvec - Use ThinVec for often-empty vectors
• mem-clone-from - Use clone_from() to reuse allocations
• mem-reuse-collections - Reuse collections with clear() in loops
• mem-avoid-format - Avoid format!() when string literals work
• mem-write-over-format - Use write!() instead of format!()
• mem-arena-allocator - Use arena allocators for batch allocations
• mem-zero-copy - Use zero-copy patterns with slices and Bytes
• mem-compact-string - Use CompactString for small string optimization
• mem-smaller-integers - Use smallest integer type that fits
• mem-assert-type-size - Assert hot type sizes to prevent regressions

4. API Design (HIGH)

• api-builder-pattern - Use Builder pattern for complex construction
• api-builder-must-use - Add #[must_use] to builder types
• api-newtype-safety - Use newtypes for type-safe distinctions
• api-typestate - Use typestate for compile-time state machines
• api-sealed-trait - Seal traits to prevent external implementations
• api-extension-trait - Use extension traits to add methods to foreign types
• api-parse-dont-validate - Parse into validated types at boundaries
• api-impl-into - Accept impl Into<T> for flexible string inputs
• api-impl-asref - Accept impl AsRef<T> for borrowed inputs
• api-must-use - Add #[must_use] to Result returning functions
• api-non-exhaustive - Use #[non_exhaustive] for future-proof enums/structs
• api-from-not-into - Implement From, not Into (auto-derived)
• api-default-impl - Implement Default for sensible defaults
• api-common-traits - Implement Debug, Clone, PartialEq eagerly
• api-serde-optional - Gate Serialize/Deserialize behind feature flag

5. Async/Await (HIGH)

• async-tokio-runtime - Use Tokio for production async runtime
• async-no-lock-await - Never hold Mutex/RwLock across .await
• async-spawn-blocking - Use spawn_blocking for CPU-intensive work
• async-tokio-fs - Use tokio::fs not std::fs in async code
• async-cancellation-token - Use CancellationToken for graceful shutdown
• async-join-parallel - Use tokio::join! for parallel operations
• async-try-join - Use tokio::try_join! for fallible parallel ops
• async-select-racing - Use tokio::select! for racing/timeouts
• async-bounded-channel - Use bounded channels for backpressure
• async-mpsc-queue - Use mpsc for work queues
• async-broadcast-pubsub - Use broadcast for pub/sub patterns
• async-watch-latest - Use watch for latest-value sharing
• async-oneshot-response - Use oneshot for request/response
• async-joinset-structured - Use JoinSet for dynamic task groups
• async-clone-before-await - Clone data before await, release locks

6. Compiler Optimization (HIGH)

• opt-inline-small - Use #[inline] for small hot functions
• opt-inline-always-rare - Use #[inline(always)] sparingly
• opt-inline-never-cold - Use #[inline(never)] for cold paths
• opt-cold-unlikely - Use #[cold] for error/unlikely paths
• opt-likely-hint - Use likely()/unlikely() for branch hints
• opt-lto-release - Enable LTO in release builds
• opt-codegen-units - Use codegen-units = 1 for max optimization
• opt-pgo-profile - Use PGO for production builds
• opt-target-cpu - Set target-cpu=native for local builds
• opt-bounds-check - Use iterators to avoid bounds checks
• opt-simd-portable - Use portable SIMD for data-parallel ops
• opt-cache-friendly - Design cache-friendly data layouts (SoA)

7. Naming Conventions (MEDIUM)

• name-types-camel - Use UpperCamelCase for types, traits, enums
• name-variants-camel - Use UpperCamelCase for enum variants
• name-funcs-snake - Use snake_case for functions, methods, modules
• name-consts-screaming - Use SCREAMING_SNAKE_CASE for constants/statics
• name-lifetime-short - Use short lowercase lifetimes: 'a, 'de, 'src
• name-type-param-single - Use single uppercase for type params: T, E, K, V
• name-as-free - as_ prefix: free reference conversion
• name-to-expensive - to_ prefix: expensive conversion
• name-into-ownership - into_ prefix: ownership transfer
• name-no-get-prefix - No get_ prefix for simple getters
• name-is-has-bool - Use is_, has_, can_ for boolean methods
• name-iter-convention - Use iter/iter_mut/into_iter for iterators
• name-iter-method - Name iterator methods consistently
• name-iter-type-match - Iterator type names match method
• name-acronym-word - Treat acronyms as words: Uuid not UUID
• name-crate-no-rs - Crate names: no -rs suffix

8. Type Safety (MEDIUM)

• type-newtype-ids - Wrap IDs in newtypes: UserId(u64)
• type-newtype-validated - Newtypes for validated data: Email, Url
• type-enum-states - Use enums for mutually exclusive states
• type-option-nullable - Use Option<T> for nullable values
• type-result-fallible - Use Result<T, E> for fallible operations
• type-phantom-marker - Use PhantomData<T> for type-level markers
• type-never-diverge - Use ! type for functions that never return
• type-generic-bounds - Add trait bounds only where needed
• type-no-stringly - Avoid stringly-typed APIs, use enums/newtypes
• type-repr-transparent - Use #[repr(transparent)] for FFI newtypes

9. Testing (MEDIUM)

• test-cfg-test-module - Use #[cfg(test)] mod tests { }
• test-use-super - Use use super::*; in test modules
• test-integration-dir - Put integration tests in tests/ directory
• test-descriptive-names - Use descriptive test names
• test-arrange-act-assert - Structure tests as arrange/act/assert
• test-proptest-properties - Use proptest for property-based testing
• test-mockall-mocking - Use mockall for trait mocking
• test-mock-traits - Use traits for dependencies to enable mocking
• test-fixture-raii - Use RAII pattern (Drop) for test cleanup
• test-tokio-async - Use #[tokio::test] for async tests
• test-should-panic - Use #[should_panic] for panic tests
• test-criterion-bench - Use criterion for benchmarking
• test-doctest-examples - Keep doc examples as executable tests

10. Documentation (MEDIUM)

• doc-all-public - Document all public items with ///
• doc-module-inner - Use //! for module-level documentation
• doc-examples-section - Include # Examples with runnable code
• doc-errors-section - Include # Errors for fallible functions
• doc-panics-section - Include # Panics for panicking functions
• doc-safety-section - Include # Safety for unsafe functions
• doc-question-mark - Use ? in examples, not .unwrap()
• doc-hidden-setup - Use # prefix to hide example setup code
• doc-intra-links - Use intra-doc links: [Vec]
• doc-link-types - Link related types and functions in docs
• doc-cargo-metadata - Fill Cargo.toml metadata

11. Performance Patterns (MEDIUM)

• perf-iter-over-index - Prefer iterators over manual indexing
• perf-iter-lazy - Keep iterators lazy, collect() only when needed
• perf-collect-once - Don't collect() intermediate iterators
• perf-entry-api - Use entry() API for map insert-or-update
• perf-drain-reuse - Use drain() to reuse allocations
• perf-extend-batch - Use extend() for batch insertions
• perf-chain-avoid - Avoid chain() in hot loops
• perf-collect-into - Use collect_into() for reusing containers
• perf-black-box-bench - Use black_box() in benchmarks
• perf-release-profile - Optimize release profile settings
• perf-profile-first - Profile before optimizing

12. Project Structure (LOW)

• proj-lib-main-split - Keep main.rs minimal, logic in lib.rs
• proj-mod-by-feature - Organize modules by feature, not type
• proj-flat-small - Keep small projects flat
• proj-mod-rs-dir - Use mod.rs for multi-file modules
• proj-pub-crate-internal - Use pub(crate) for internal APIs
• proj-pub-super-parent - Use pub(super) for parent-only visibility
• proj-pub-use-reexport - Use pub use for clean public API
• proj-prelude-module - Create prelude module for common imports
• proj-bin-dir - Put multiple binaries in src/bin/
• proj-workspace-large - Use workspaces for large projects
• proj-workspace-deps - Use workspace dependency inheritance

13. Clippy & Linting (LOW)

• lint-deny-correctness - #![deny(clippy::correctness)]
• lint-warn-suspicious - #![warn(clippy::suspicious)]
• lint-warn-style - #![warn(clippy::style)]
• lint-warn-complexity - #![warn(clippy::complexity)]
• lint-warn-perf - #![warn(clippy::perf)]
• lint-pedantic-selective - Enable clippy::pedantic selectively
• lint-missing-docs - #![warn(missing_docs)]
• lint-unsafe-doc - #![warn(clippy::undocumented_unsafe_blocks)]
• lint-cargo-metadata - #![warn(clippy::cargo)] for published crates
• lint-rustfmt-check - Run cargo fmt --check in CI
• lint-workspace-lints - Configure lints at workspace level

14. Anti-patterns (REFERENCE)

• anti-unwrap-abuse - Don't use .unwrap() in production code
• anti-expect-lazy - Don't use .expect() for recoverable errors
• anti-clone-excessive - Don't clone when borrowing works
• anti-lock-across-await - Don't hold locks across .await
• anti-string-for-str - Don't accept &String when &str works
• anti-vec-for-slice - Don't accept &Vec<T> when &[T] works
• anti-index-over-iter - Don't use indexing when iterators work
• anti-panic-expected - Don't panic on expected/recoverable errors
• anti-empty-catch - Don't use empty if let Err(_) = ... blocks
• anti-over-abstraction - Don't over-abstract with excessive generics
• anti-premature-optimize - Don't optimize before profiling
• anti-type-erasure - Don't use Box<dyn Trait> when impl Trait works
• anti-format-hot-path - Don't use format!() in hot paths
• anti-collect-intermediate - Don't collect() intermediate iterators
• anti-stringly-typed - Don't use strings for structured data

Recommended Cargo.toml Settings

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true

[profile.bench]
inherits = "release"
debug = true
strip = false

[profile.dev]
opt-level = 0
debug = true

[profile.dev.package."*"]
opt-level = 3  # Optimize dependencies in dev

How to Use

This skill provides rule identifiers for quick reference. When generating or reviewing Rust code:

1. Check relevant category based on task type
2. Apply rules with matching prefix
3. Prioritize CRITICAL > HIGH > MEDIUM > LOW
4. Read rule files in rules/ for detailed examples

Rule Application by Task

Sources

This skill synthesizes best practices from:
- Rust API Guidelines
- Rust Performance Book
- Rust Design Patterns
- Production codebases: ripgrep, tokio, serde, polars, axum, deno
- Clippy lint documentation
- Community conventions (2024-2025)