Awesome-omni-skill rust

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