Instructions
1. Planning & Analysis
Before writing any code:
- Understand the full requirements and constraints
- Review the existing codebase for conventions, utilities, and patterns already in use
- Check for shared/common modules before creating new utilities
- Consider edge cases within reason unless the user specifically asks for more
- For GUI work: identify which platforms are targeted and any platform-specific constraints
2. Design Principles
Rust-Specific:
- Prefer borrowing over cloning; pass
&str not &String, &Path not &PathBuf, &[T] not &Vec<T>
- Use enums, newtypes, and the type system to make illegal states unrepresentable
- Parse raw input into well-typed structures at the boundary, then pass typed data inward
- Leverage
impl Into<T>, AsRef<T>, and other conversion traits for ergonomic public APIs
General:
- YAGNI: Implement only what is required; add complexity as the need arises
- KISS: Favor simplicity and clarity over cleverness
- DRY: Extract shared logic into common modules or helper functions
- Follow the repo's existing conventions over personal preference
3. Error Handling (anyhow required)
Use anyhow as the primary error-handling crate. Do not introduce thiserror, eyre, or other error libraries unless explicitly approved.
- All fallible functions return
anyhow::Result<T>
- Attach context at every level with
.context("message") or .with_context(|| format!(...))
- Propagate errors with
?; never use unwrap() or expect() outside test code
- Use
anyhow::anyhow!("message") or anyhow::bail!("message") for ad-hoc errors
- At the entrypoint: handle errors gracefully — print to
stderr and exit with appropriate code
4. Project Structure
Follow the structure established by the project. For new projects, use idiomatic Rust conventions:
Workspace projects:
- Place crates under a
crates/ directory; list them in root Cargo.toml [workspace.members]
- Shared utilities go in a common crate (e.g.,
crates/common/ or crates/shared/)
- Each crate has a focused responsibility
Single-crate projects:
src/main.rs — thin entrypoint: init, parse args/config, call into app logic, handle exit
src/lib.rs — public API surface; re-exports from submodules
src/models.rs — domain types, config structs, enums
src/app.rs (or domain-named module) — core logic
General guidelines:
- Keep
main.rs thin — it orchestrates; logic lives in library code
- One module per concern; split files when they exceed ~300 lines
- Additional modules are fine when they keep things tidy and well-scoped
#[derive(Debug, Clone)] on config/model structs; add Copy, PartialEq, Eq where appropriate
- Enums for discrete modes/states;
Option<T> for optional fields
5. Cross-Platform GUI Development
When building GUI applications, apply these practices:
Before doing any visual changes, check the ui-guidelines.md at the root of the repo for general guidelines and best
practices for UI/UX development.
Architecture:
- Separate core logic from UI: business logic in a library crate, UI in the binary crate
- Use a message/command pattern to communicate between UI and logic layers
- Keep platform-specific code isolated behind trait abstractions or
#[cfg(target_os)] gates
- Design for the event loop: avoid blocking the main/UI thread
Framework guidance (choose based on project needs):
- iced — Elm-inspired, pure Rust, good for data-driven UIs. Strengths: type-safe message passing, no unsafe, cross-platform. Use
iced::Application or iced::Sandbox traits.
- egui / eframe — immediate-mode, excellent for tools, dashboards, debug UIs. Strengths: very fast iteration, minimal boilerplate, easy embedding. Use
eframe::App trait.
- Tauri — web-tech frontend with Rust backend. Strengths: small binary size, leverage web ecosystem, strong IPC. Use for apps where web UI is preferred.
- Slint — declarative UI with
.slint markup language. Strengths: designer-friendly, embedded-capable, good accessibility.
- gtk4-rs / relm4 — GTK4 bindings. Strengths: mature widget set, strong Linux integration. Use
relm4 for Elm-style architecture on top of GTK4.
- Dioxus — React-like with RSX syntax. Strengths: familiar to web devs, cross-platform (desktop, web, mobile).
Cross-platform considerations:
- Test on all target platforms early and regularly (Windows, macOS, Linux at minimum)
- Use
dirs or directories crate for platform-appropriate config/data/cache paths
- Handle HiDPI/scaling — use logical pixels, not physical pixels
- Respect platform conventions for keyboard shortcuts (Cmd vs Ctrl), file paths, and native look-and-feel
- Use
cfg(target_os) sparingly and only when truly needed; prefer cross-platform abstractions
- For file dialogs, system notifications, and other OS integration, use
rfd, notify-rust, or similar cross-platform crates
State management:
- Treat application state as a single source of truth; UI renders from state
- Use message/event enums to describe state transitions
- Keep state serializable where practical (enables save/restore, undo/redo)
- For complex state, consider a reducer pattern or
Arc<Mutex<State>> for thread-safe sharing
Async and threading in GUI apps:
- Never block the UI thread — offload heavy work to background threads or async tasks
- Use channels (
std::sync::mpsc, crossbeam-channel, tokio::sync::mpsc) to send results back to the UI
- For async runtimes alongside GUI event loops, use the framework's built-in async support or run
tokio on a separate thread
- Debounce expensive operations triggered by rapid UI events (typing, resizing)
6. Code Style
- Use the repo's
rustfmt and clippy configuration; never change them; fix all warnings
snake_case for functions/variables/modules/files; PascalCase for types; UPPER_SNAKE_CASE for constants
- Group imports:
crate::, external crates, std::; no glob imports in production code
- Doc comments (
///) on all public items with # Errors / # Panics sections where applicable
- Comments explain "why", not "what"; no commented-out code
- Functions ~50 lines max; extract helpers when they grow
match over if let chains for multiple variants; guard clauses for early returns
7. Dependencies
- Check the existing
Cargo.toml before adding new dependencies
- Prefer well-maintained, widely used crates (check download counts, recent activity,
unsafe usage)
- Pin major versions; use
cargo update for patch updates
- Feature-gate optional functionality to keep compile times and binary size down
- For cross-platform apps, verify that dependencies support all target platforms
- Dependencies should be always kept up-to-date with the latest stable versions
Commonly useful crates:
- CLI:
clap (derive), indicatif (progress bars)
- Serialization:
serde + serde_json / toml / ron
- Async:
tokio (only when genuinely needed)
- Logging:
tracing or log + env_logger
- File I/O:
tempfile (tests), walkdir (traversal)
- Cross-platform paths:
dirs, directories
8. Performance
- Use
BufReader/BufWriter for file I/O
- Pre-allocate
Vec capacity when size is known; use Cow<'_, str> to avoid unnecessary allocations
- Use
std::sync::LazyLock (or once_cell::sync::Lazy) for expensive one-time inits like compiled regexes
- Profile before optimizing — use
cargo flamegraph, criterion for benchmarks
- For GUI: keep frame budgets in mind (~16ms for 60fps); avoid allocations in hot render paths
9. Testing
- Unit tests:
#[cfg(test)] mod tests at the bottom of each file; use super::*
- File-based tests:
tempfile::tempdir() for temporary directories
- Follow Arrange-Act-Assert; use helper functions to build test fixtures
- Use
assert!(matches!(...)) for enum variant checks
- Test happy paths, error conditions, and meaningful boundary values
- Add tests where it makes sense; don't add them purely for coverage numbers
- For GUI: test logic and state management independently from rendering; use snapshot/golden tests for UI if the framework supports it
10. Forbidden
unsafe code unless explicitly approved by the user
unwrap() / expect() in non-test code
- Error libraries other than
anyhow (no thiserror, eyre, etc.) unless explicitly approved
- Changing
rustfmt or clippy settings without explicit approval
- Blocking the UI/main thread in GUI applications
11. Quality Validation
Run before completion (adjust package name to match the project):
cargo build -p <package-name>
cargo clippy -p <package-name> -- -D warnings
cargo test -p <package-name>
cargo fmt -p <package-name> -- --check
For workspace-wide checks:
cargo build --workspace
cargo clippy --workspace -- -D warnings
cargo test --workspace
cargo fmt --all -- --check
Never run git commit. Summarize changes to the user alongside any problems and caveats.
When to Use This Skill
- Writing new Rust applications, libraries, or tools
- Building cross-platform GUI applications in Rust
- Adding functionality to existing crates
- Refactoring, debugging, or reviewing Rust code
- Any Rust task where production-quality, idiomatic code is expected
1---2name: rust-33description: Write production-quality Rust code following industry best practices and idiomatic patterns. Use for any Rust coding task including applications, libraries, refactoring, debugging, or code review — with particular expertise in cross-platform GUI development.4metadata:5 source: https://skillmd.com/skills/diegosouzapw/rust-36---78## Instructions910### 1. Planning & Analysis1112**Before writing any code:**13- Understand the full requirements and constraints14- Review the existing codebase for conventions, utilities, and patterns already in use15- Check for shared/common modules before creating new utilities16- Consider edge cases within reason unless the user specifically asks for more17- For GUI work: identify which platforms are targeted and any platform-specific constraints1819### 2. Design Principles2021**Rust-Specific:**22- Prefer borrowing over cloning; pass `&str` not `&String`, `&Path` not `&PathBuf`, `&[T]` not `&Vec<T>`23- Use enums, newtypes, and the type system to make illegal states unrepresentable24- Parse raw input into well-typed structures at the boundary, then pass typed data inward25- Leverage `impl Into<T>`, `AsRef<T>`, and other conversion traits for ergonomic public APIs2627**General:**28- **YAGNI**: Implement only what is required; add complexity as the need arises29- **KISS**: Favor simplicity and clarity over cleverness30- **DRY**: Extract shared logic into common modules or helper functions31- Follow the repo's existing conventions over personal preference3233### 3. Error Handling (anyhow required)3435**Use `anyhow` as the primary error-handling crate.** Do not introduce `thiserror`, `eyre`, or other error libraries unless explicitly approved.3637- All fallible functions return `anyhow::Result<T>`38- Attach context at every level with `.context("message")` or `.with_context(|| format!(...))`39- Propagate errors with `?`; never use `unwrap()` or `expect()` outside test code40- Use `anyhow::anyhow!("message")` or `anyhow::bail!("message")` for ad-hoc errors41- At the entrypoint: handle errors gracefully — print to `stderr` and exit with appropriate code4243### 4. Project Structure4445Follow the structure established by the project. For new projects, use idiomatic Rust conventions:4647**Workspace projects:**48- Place crates under a `crates/` directory; list them in root `Cargo.toml` `[workspace.members]`49- Shared utilities go in a common crate (e.g., `crates/common/` or `crates/shared/`)50- Each crate has a focused responsibility5152**Single-crate projects:**53- `src/main.rs` — thin entrypoint: init, parse args/config, call into app logic, handle exit54- `src/lib.rs` — public API surface; re-exports from submodules55- `src/models.rs` — domain types, config structs, enums56- `src/app.rs` (or domain-named module) — core logic5758**General guidelines:**59- Keep `main.rs` thin — it orchestrates; logic lives in library code60- One module per concern; split files when they exceed ~300 lines61- Additional modules are fine when they keep things tidy and well-scoped62- `#[derive(Debug, Clone)]` on config/model structs; add `Copy`, `PartialEq`, `Eq` where appropriate63- Enums for discrete modes/states; `Option<T>` for optional fields6465### 5. Cross-Platform GUI Development6667When building GUI applications, apply these practices:6869Before doing any visual changes, check the `ui-guidelines.md` at the root of the repo for general guidelines and best 70practices for UI/UX development.7172**Architecture:**73- Separate core logic from UI: business logic in a library crate, UI in the binary crate74- Use a message/command pattern to communicate between UI and logic layers75- Keep platform-specific code isolated behind trait abstractions or `#[cfg(target_os)]` gates76- Design for the event loop: avoid blocking the main/UI thread7778**Framework guidance (choose based on project needs):**79- **iced** — Elm-inspired, pure Rust, good for data-driven UIs. Strengths: type-safe message passing, no unsafe, cross-platform. Use `iced::Application` or `iced::Sandbox` traits.80- **egui / eframe** — immediate-mode, excellent for tools, dashboards, debug UIs. Strengths: very fast iteration, minimal boilerplate, easy embedding. Use `eframe::App` trait.81- **Tauri** — web-tech frontend with Rust backend. Strengths: small binary size, leverage web ecosystem, strong IPC. Use for apps where web UI is preferred.82- **Slint** — declarative UI with `.slint` markup language. Strengths: designer-friendly, embedded-capable, good accessibility.83- **gtk4-rs / relm4** — GTK4 bindings. Strengths: mature widget set, strong Linux integration. Use `relm4` for Elm-style architecture on top of GTK4.84- **Dioxus** — React-like with RSX syntax. Strengths: familiar to web devs, cross-platform (desktop, web, mobile).8586**Cross-platform considerations:**87- Test on all target platforms early and regularly (Windows, macOS, Linux at minimum)88- Use `dirs` or `directories` crate for platform-appropriate config/data/cache paths89- Handle HiDPI/scaling — use logical pixels, not physical pixels90- Respect platform conventions for keyboard shortcuts (Cmd vs Ctrl), file paths, and native look-and-feel91- Use `cfg(target_os)` sparingly and only when truly needed; prefer cross-platform abstractions92- For file dialogs, system notifications, and other OS integration, use `rfd`, `notify-rust`, or similar cross-platform crates9394**State management:**95- Treat application state as a single source of truth; UI renders from state96- Use message/event enums to describe state transitions97- Keep state serializable where practical (enables save/restore, undo/redo)98- For complex state, consider a reducer pattern or `Arc<Mutex<State>>` for thread-safe sharing99100**Async and threading in GUI apps:**101- Never block the UI thread — offload heavy work to background threads or async tasks102- Use channels (`std::sync::mpsc`, `crossbeam-channel`, `tokio::sync::mpsc`) to send results back to the UI103- For async runtimes alongside GUI event loops, use the framework's built-in async support or run `tokio` on a separate thread104- Debounce expensive operations triggered by rapid UI events (typing, resizing)105106### 6. Code Style107108- Use the repo's `rustfmt` and `clippy` configuration; never change them; fix all warnings109- `snake_case` for functions/variables/modules/files; `PascalCase` for types; `UPPER_SNAKE_CASE` for constants110- Group imports: `crate::`, external crates, `std::`; no glob imports in production code111- Doc comments (`///`) on all public items with `# Errors` / `# Panics` sections where applicable112- Comments explain "why", not "what"; no commented-out code113- Functions ~50 lines max; extract helpers when they grow114- `match` over `if let` chains for multiple variants; guard clauses for early returns115116### 7. Dependencies117118- Check the existing `Cargo.toml` before adding new dependencies119- Prefer well-maintained, widely used crates (check download counts, recent activity, `unsafe` usage)120- Pin major versions; use `cargo update` for patch updates121- Feature-gate optional functionality to keep compile times and binary size down122- For cross-platform apps, verify that dependencies support all target platforms123- Dependencies should be always kept up-to-date with the latest stable versions124125**Commonly useful crates:**126- CLI: `clap` (derive), `indicatif` (progress bars)127- Serialization: `serde` + `serde_json` / `toml` / `ron`128- Async: `tokio` (only when genuinely needed)129- Logging: `tracing` or `log` + `env_logger`130- File I/O: `tempfile` (tests), `walkdir` (traversal)131- Cross-platform paths: `dirs`, `directories`132133### 8. Performance134135- Use `BufReader`/`BufWriter` for file I/O136- Pre-allocate `Vec` capacity when size is known; use `Cow<'_, str>` to avoid unnecessary allocations137- Use `std::sync::LazyLock` (or `once_cell::sync::Lazy`) for expensive one-time inits like compiled regexes138- Profile before optimizing — use `cargo flamegraph`, `criterion` for benchmarks139- For GUI: keep frame budgets in mind (~16ms for 60fps); avoid allocations in hot render paths140141### 9. Testing142143- Unit tests: `#[cfg(test)] mod tests` at the bottom of each file; `use super::*`144- File-based tests: `tempfile::tempdir()` for temporary directories145- Follow Arrange-Act-Assert; use helper functions to build test fixtures146- Use `assert!(matches!(...))` for enum variant checks147- Test happy paths, error conditions, and meaningful boundary values148- Add tests where it makes sense; don't add them purely for coverage numbers149- For GUI: test logic and state management independently from rendering; use snapshot/golden tests for UI if the framework supports it150151### 10. Forbidden152153- `unsafe` code unless explicitly approved by the user154- `unwrap()` / `expect()` in non-test code155- Error libraries other than `anyhow` (no `thiserror`, `eyre`, etc.) unless explicitly approved156- Changing `rustfmt` or `clippy` settings without explicit approval157- Blocking the UI/main thread in GUI applications158159### 11. Quality Validation160161Run before completion (adjust package name to match the project):162```bash163cargo build -p <package-name>164cargo clippy -p <package-name> -- -D warnings165cargo test -p <package-name>166cargo fmt -p <package-name> -- --check167```168169For workspace-wide checks:170```bash171cargo build --workspace172cargo clippy --workspace -- -D warnings173cargo test --workspace174cargo fmt --all -- --check175```176177Never run git commit. Summarize changes to the user alongside any problems and caveats.178179## When to Use This Skill180181- Writing new Rust applications, libraries, or tools182- Building cross-platform GUI applications in Rust183- Adding functionality to existing crates184- Refactoring, debugging, or reviewing Rust code185- Any Rust task where production-quality, idiomatic code is expected