rust-coding-skill

Rust Coding Skill

Opinionated Rust rules for the Copilot Rust SDK (rust/). Priority order:

1. Readable code — every line should earn its place
2. Correct code — especially in concurrent/async contexts
3. Performant code — think about allocations, data structures, hot paths

Error handling

The SDK's public error type is crate::Error (rust/src/errors.rs). Add new variants to crate::ErrorKind rather than introducing parallel error enums per module — every public failure mode is part of the API contract and should be expressible in one type.

anyhow is reserved for binaries and example code. Library code never returns anyhow::Result — callers can't pattern-match on anyhow::Error, so it would prevent them from handling specific failures.

In production code, prefer ?, let-else, and if let. Reach for expect("…") when an invariant cannot fail and the message would help debug a future regression. unwrap() belongs in tests only — Clippy enforces this in the SDK via #![cfg_attr(test, allow(clippy::unwrap_used))] in lib.rs.

When you need to log on the way through, prefer .inspect_err(|e| warn!(error = ?e, "context"))? over a match that logs and re-wraps. It reads top-to-bottom and keeps the happy path uncluttered.

Async and concurrency

The default for request-scoped I/O is async fn plus .await — futures inherit cancellation from their parent task and can borrow local references. Reach for tokio::spawn only when you genuinely need background work (an event loop, a long-lived watcher) and track the JoinHandle so you can cancel or join it on shutdown. Fire-and-forget spawns silently swallow panics and outlive the session; don't.

Blocking calls (filesystem, subprocess wait) belong in tokio::task::spawn_blocking, not on the async runtime. The blocking pool is bounded, so for genuinely long-lived workers (think: file watchers that run for the lifetime of a session) prefer std::thread::spawn with a channel back into async land.