morganlinton/BeautifulRust

Beautiful Rust is a set of tools that teach AI coding agents to write, review, and port Rust code the idiomatic way. It comes in two parts: three skills (instructions agents read while working) and a lints config (rules that catch violations automatically in CI).

The three skills

1. rust-best-practices — Activates whenever an agent writes or changes Rust code. It steers the agent toward idiomatic, robust, maintainable code. This is the core skill; the other two build on it.

2. rust-review — Reviews existing Rust code (a single file, a whole crate, or a diff) and produces a prioritized report. Every finding includes a file:line location, the rule it breaks (with its source, like an API Guidelines code or a clippy lint), and the smallest code change that fixes it. Findings are tiered: must fix, should fix, consider. The report also ends with what the code already does well.

3. rust-port — Ports C, C++, Python, Go, or JavaScript to idiomatic Rust with the same behavior. It ports the original tests first so you can prove the two versions match. It designs a Rust API rather than transliterating the original, and maps each language's habits to Rust equivalents — e.g., NULL/None become Option, error codes become an error enum, out-parameters become return values, flag ints become typed enums. Each port includes a PORTING.md documenting every deliberate difference.

The lints config

lints/ is a drop-in clippy configuration. You copy clippy.toml next to your Cargo.toml, paste the [lints] block from lints.toml, and run cargo clippy. It flags things like unwrap() outside tests, unsafe blocks without a // SAFETY: comment, #[allow] without a reason, bool function parameters, silent lossy as casts, missing # Errors and # Panics docs, and leftover dbg!/todo!. Every lint is proven to fire — a small test crate contains one deliberate violation per lint, and a script fails if any lint stops working.

What it changes in practice

The README shows a concrete before/after. Asked to build a small semver-parsing library, an agent without the skill produced a struct with public fields, no # Errors documentation, and unwrap() in doc examples. With the skill, the same agent kept fields private, documented failure modes explicitly, and wrote doc examples users can safely copy-paste.

Where the guidance comes from

The skills distill five published sources, with a condensed digest of each bundled in the skill so the agent can consult the original reasoning:

• Google Rust Style Guide
• Rust API Guidelines (official rust-lang checklist)
• Effective Rust by David Drysdale
• Rust Design Patterns (rust-unofficial)
• Microsoft Pragmatic Rust Guidelines

Where sources disagree, the skill picks a side and says why.

Compatibility and installation

Works with Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, and any agent that reads the Agent Skills format. Installation varies by agent — one-command installers, plugin installs, or simply copying the skill folders into the agent's skills directory. A table lists the correct directory for each agent.

How well it works

The skills were tested with real model runs (which cost money to run). Results:

• Writing skill: 29 of 30 checks passed with the skill, vs 24 of 30 without — at roughly a third more tokens per task.
• Review skill: 11 of 12 passed vs 7 of 12.
• Porting skill: 22 of 22 passed vs 19 of 22.

Maintenance and contribution

Updates are versioned via plugin.json; Claude Code users get them with one command. A validation script checks skill formatting, links, and eval cases before pushing. Contributions are welcome — every rule must cite a published source, and the README links to a contributing guide.

License

The skill text, digests, banner, and generator script are MIT licensed. The five source digests are paraphrased summaries that link back to their originals, each under its own license (CC BY 3.0, MIT/Apache-2.0, CC BY-NC-ND 4.0, MPL-2.0, MIT).