rust-code-skill

A skill for AI coding agents (Claude Code, Cursor, pi, and others) that writes idiomatic, safe Rust.

It runs a verification loop (cargo clippy -- -D warnings, cargo test) plus 16 judgment rules for what clippy enforces only mechanically. The machine verifies what it can; prose covers the judgment it cannot.

Why this shape

LLMs are now good enough at Rust that the compiler and clippy are the reliable verifier. Hundreds of community rules are already machine-encoded as lints. Restating them as prose the model can't hold every turn adds clutter and drifts.

This skill keeps the hard loop (clippy, test) plus the judgment layer clippy can't make: parse-don't-validate, unsafe with justified SAFETY comments, error types, no lock across await, cancellation safety, executor blocking, naming, newtypes. One file, the agent holds it.

Install

Copy SKILL.md into your agent's skills directory.

pi (~/.pi/agent)

mkdir -p ~/.pi/agent/skills/rust-code
curl -fsSL https://raw.githubusercontent.com/renflowerz/rust-code-skill/main/SKILL.md \
  -o ~/.pi/agent/skills/rust-code/SKILL.md

Claude Code

Place SKILL.md in your .claude/skills/ or reference it from CLAUDE.md.

The loop

cargo clippy -- -D warnings   # zero warnings, non-negotiable
cargo test                    # tests pass

Clippy is the primary verifier. The compiler is the second; the borrow checker catches what no prose can.

Rules

1. Parse, don't validate. Invalid states should not compile.
2. unsafe needs a // SAFETY: comment immediately above the block, with the exact invariant plus a justification.
3. Error design is a contract decision. anyhow downcasts fine; typed enums (thiserror) put the failure set in the type system for exhaustive matching. Typed when callers react to specific failures, anyhow when they log/propagate.
4. No .unwrap() or .expect() on external input paths.
5. No locking across .await. Extract, drop the guard, then await.
6. Newtypes over bare primitives in public APIs.
7. No incidental smart pointers in signatures. Box<dyn Trait> and returned Arc handles are fine; Arc<Mutex<Everything>> plumbing is not.
8. Conversion naming: as_ / to_ / into_. Implement From, get Into free.
9. Iteration over manual indexing.
10. Derive what the API promises. #[non_exhaustive] on growing types. Libraries don't panic; return Result.
11. Native async fn in traits (stable since 1.75) is the default. async-trait/trait_variant only for dyn dispatch. Futures under select!/aborts must be cancellation-safe.
12. Don't block the executor. Sync I/O and CPU loops go to spawn_blocking.
13. Dependencies: prefer std, check the tree before adding.
14. serde: deny_unknown_fields inbound, version-tolerant storage.
15. Measure before optimizing. No speculative unsafe without a profile.
16. Comments explain why. cargo doc builds clean.

See SKILL.md for the full rules with reasoning and a review checklist.

License

MIT