Rust Stable

Rust Stable Language Semantics

Use this skill for language semantics: ownership, borrowing, lifetimes, traits, generics, pattern matching, error propagation, and Edition differences. First verify the project's actual toolchain and Minimum Supported Rust Version (MSRV).

For standard-library API selection (which collection, which smart pointer, which string type, which I/O trait), use rust-stdlib. For concrete pattern examples ("how do I write X"), use rust-by-example.

Prerequisites Before Starting

1. Run rustc --version --verbose and cargo --version.
2. Inspect the rust-version field in rust-toolchain.toml, rust-toolchain, and Cargo.toml.
3. Distinguish between three versions: local toolchain, project MSRV, and current official stable release.
4. When encountering version-sensitive APIs, consult Current Stable Baseline and rely on official release notes and API documentation as the final authority.
5. If a project is locked to an old version, strictly adhere only to syntaxes and APIs that are already stabilized for that specific version.

Current Offline Baseline: Rust 1.97.1 (released July 16, 2026). This is a dated repository baseline and does not update automatically.

Capability Boundaries

Suitable For Handling

• Ownership, borrowing, lifetimes, and move semantics.
• struct, enum, pattern matching, traits, generics, and associated types.
• Option, Result error propagation, and custom errors (the language mechanism).
• Closures (Fn/FnMut/FnOnce), attribute syntax, format strings (the language mechanism).
• Modules, visibility modifiers, pub/pub(crate)/pub(super).
• Edition differences (language-level — unsafe extern, RPIT capture, match ergonomics).
• Common compilation errors, borrowing check failures, and stable migration judgments.

Hand Off to Specialized Skills

Do not replace the complete workflow of domain-specific skills with this skill.

Workflow

1. Determine Version Boundaries — Record toolchain version, edition, MSRV, and target platform(s).
2. Narrow Problem Scope — Determine whether the issue belongs to ownership/type system/standard library/compiler errors or a specialized domain.
3. Read Minimal Resources — Open only references directly relevant to the problem; do not load entire documentation sets at once.
4. Implement Minimum Correct Solution — Prioritize stable standard library usage, clear ownership semantics, and explicit error propagation.
5. Run Quality Gate Checks — Execute cargo fmt --check, cargo check (with all targets/features), and relevant tests.
6. Handle Version Differences — If an API is not supported by MSRV, choose the old compatible API or implement a compatibility shim; otherwise explicitly raise the MSRV.
7. Transfer to Specialized Skills — Load corresponding skills for async, unsafe macros, Web, embedded domains after entering those areas.

Design Rules

• Prefer &T / &mut T; clone only when ownership transfer is required or independent lifetimes are needed.
• Use types to express invariants; prefer enums/newtypes over boolean parameters and unconstrained strings.
• Library code should return structured errors; application boundaries may add context before deciding how to display them.
• Prefer iterators and standard collections, but do not sacrifice readability for chain-of-call syntax.
• Do not use unsafe as a bypass for borrowing checks first prove that safe abstractions cannot express the requirement.
• Do not default third-party crate imports; compare against stable std, MSRV, maintenance cost, and supply chain risk.
• Never claim an API is stabilized in a specific version unless official release notes or an API page marked with since confirm it.

Validation Gateways

Run validation gates from lowest to highest risk:

cargo fmt --all --check
cargo check --all-targets --all-features
cargo test --all-targets --all-features
cargo clippy --all-targets --all-features -- -D warnings

If the project does not support --all-features or contains platform-specific targets, record reasons and use a defined feature/target matrix. For unsafe code, add cargo miri test; for MSRV issues, repeat cargo check and tests on the declared minimum toolchain.

Required Documentation to Read On-Demand

Version & Language Semantics

• Current Stable Baseline: Latest version, compatibility notes, update steps.
• Ownership & Lifetimes: Borrowing design, return values and lifetime judgment rules.
• Traits & Generics: Bounds, associated types, trait objects, API trade-offs.
• Patterns & Idiomatic Style: Builder patterns, newtypes, RAII, typestate management.
• Style Guide: Naming conventions, module organization, documentation style, and API design principles.

Cross-references (load the right skill instead)

• "Which std collection / smart pointer / string type?" → rust-stdlib (its references/ covers collections, smart-pointers, string-types, iterators, I/O, interior-mutability, combinators, std-concurrency, process-and-fs, std-module-index)
• "How do I write X?" → rust-by-example (its references/ covers conversions, flow-control, closures, modules, generics-traits, error-handling, attributes, unsafe, procedural-macros-overview, inline-asm, migrating-from-other-languages)
• API design → rust-api-design; Cargo manifest → rust-cargo-build; dependency governance → rust-dependencies

Reproducible Examples

• Quick Start Workflows
• Ownership Patterns (examples/ownership-patterns.md)
• Collection Patterns (examples/collections-patterns.md)
• Trait Design Patterns (examples/trait-design-patterns.md)
• Error Handling Patterns (examples/error-handling-patterns.md)
• examples/golden-basic/: Minimal golden examples compiled by repository CI.

Common Pitfalls to Avoid

1. Confusing "current stable" with project MSRV.
2. Running only cargo check, omitting tests, examples, benchmarks, or feature combinations.
3. Blindly using clone, wrapping in Arc<Mutex<_>>, or invoking unsafe solely to avoid borrowing errors.
4. Holding synchronous locks across .await calls in async code.
5. Describing versioned historical documentation as continuously updated resources.
6. Copying code snippets without including dependencies, features, error types, and platform constraints.

Official Sources

• Rust Release Notes
• The Rust Programming Language (Book)
• Standard Library Reference
• Reference Manual
• Rust by Example
• Edition Guide

Data Privacy Policy

This skill provides local knowledge, examples, and validation workflows only. It does not collect, store, or transmit user data. Access to official documentation must comply with the user's network access requirements prior to accessing public resources.