playbooks

home / skills / pplmx / husky-rs / rust-expert

rust-expert skill

/.agent/skills/rust-expert

This skill helps you write idiomatic, safe Rust by enforcing formatting, error handling, and testing practices across projects.

npx playbooks add skill pplmx/husky-rs --skill rust-expert

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.9 KB
---
name: Rust Expert
description: Expert guidelines for writing idiomatic, safe, and performant Rust code.
---

# Rust Expert Checklist

As a Rust Expert, you must adhere to the following guidelines when writing or refactoring code:

## Code Quality & Style

- **Formatting**: Always strictly follow `cargo fmt`. No custom deviations unless explicitly configured.
- **Clippy**: Code must be free of `clippy` warnings. Use `#[allow(...)]` sparingly and always with a comment explaining why.
- **Idiomatic Rust**:
    - Prefer `Option` and `Result` combinators (`map`, `and_then`, `unwrap_or_else`) over explicit `match` statements for simple transformations.
    - Use the Typestate pattern where applicable to enforce valid state at compile time.
    - Use `impl Trait` in return types to reduce boilerplate when possible.
- **Async**: Be mindful of `Send` bounds in async code. Use `tokio` primitives when working with the `tokio` runtime.

## Error Handling

- Use `thiserror` for library error types to create meaningful, strongly-typed errors.
- Use `anyhow` for application-level error handling (CLI binaries, scripts).
- Avoid `unwrap()` and `expect()` in production code. Propagate errors using `?` or handle them gracefully.
    - Exception: `unwrap()` is acceptable in tests or when rigorous invariants guarantee safety (document this with `// SAFETY:`).

## Testing

- **Unit Tests**: Place unit tests in a `tests` module within the same file (`#[cfg(test)] mod tests { ... }`).
- **Integration Tests**: Place integration tests in the `tests/` directory.
- **Property Testing**: Consider using `proptest` for complex logic.
- **Snapshot Testing**: Use `insta` for snapshot testing complex output if appropriate.

## Documentation

- **Doc Comments**: Public APIs must have `///` documentation comments.
- **Examples**: Include code examples in documentation where possible.
- **Readme**: Update `README.md` if the public API changes significantly.

Overview

This skill provides expert guidelines for writing idiomatic, safe, and performant Rust code. It codifies formatting, linting, error handling, testing, and documentation practices tailored for libraries and applications. Use it to enforce consistent, maintainable Rust across projects and hooks.

How this skill works

The skill inspects code patterns and development workflow points to recommend Rust best practices: cargo fmt compliance, clippy-clean code, idiomatic use of Option/Result combinators, and appropriate async boundaries. It also enforces error-handling choices (thiserror vs anyhow), testing placement and strategies, and public API documentation expectations. Apply the guidelines during code review, refactoring, or pre-commit hooks to catch deviations early.

When to use it

  • When creating or refactoring library or binary Rust code to improve safety and readability.
  • When adding async code that must respect Send bounds and runtime conventions.
  • During code reviews to ensure consistent formatting and zero Clippy warnings.
  • When establishing project-level standards for testing and documentation.
  • When writing public APIs that require clear doc comments and examples.

Best practices

  • Always run cargo fmt and fix formatting issues; no custom deviations without config.
  • Keep Clippy warning-free; only use #[allow(...)] with a comment explaining why.
  • Prefer combinators (map, and_then, unwrap_or_else) and impl Trait to reduce boilerplate.
  • Use thiserror for library errors and anyhow for application-level error handling.
  • Avoid unwrap()/expect() in production; use ? or document SAFETY: exceptions in tests or invariant code.
  • Place unit tests in a tests module, integration tests in tests/, and consider proptest/insta when appropriate.

Example use cases

  • Add a new async API in a library and ensure futures are Send when used with tokio runtime.
  • Refactor match-heavy transformations into concise Option/Result combinators for readability.
  • Design a typestate-based builder to prevent invalid states at compile time.
  • Migrate a crate to thiserror for structured error types and update CLI binary to use anyhow.
  • Integrate cargo fmt and clippy into pre-commit hooks to block style and lint regressions.

FAQ

When is unwrap() acceptable?

Only in tests or when a rigorous invariant guarantees safety; annotate with // SAFETY: and explain the rationale.

Should I always use anyhow for errors?

Use anyhow for application-level code and binaries for ergonomic handling; prefer thiserror for library crates that expose typed errors.