Three standard Agent Skills and a lints config that teach coding agents to write, review, port, and enforce idiomatic Rust:
rust-best-practicesloads whenever an agent writes or changes Rust, and steers it toward idiomatic, robust, maintainable code.rust-reviewreviews existing Rust code, a file, a crate, or a diff, and writes a prioritized report where every finding cites the rule it breaks and shows the fix.rust-portports C, C++, Python, Go, or JavaScript to idiomatic Rust with the same behavior, porting the original tests first so you can prove the two match.lints/is a drop-in clippy configuration that enforces the machine-checkable rules in CI.
They work with Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, and any other agent that reads the Agent Skills format. Every code example in the skills compiles on stable Rust, and every lint in the config was checked against current clippy.
The guidance is distilled from five sources, with a condensed digest of each bundled in the skill so the agent can consult the original reasoning when it needs to:
- Google Rust Style Guide
- Rust API Guidelines (official rust-lang checklist)
- Effective Rust by David Drysdale
- Rust Design Patterns (idioms, patterns, anti-patterns)
- Microsoft Pragmatic Rust Guidelines
Where the sources disagree, the skill picks a side and says why.
Asked for a small semver-parsing library, an agent without the skill produced working
code with public fields, no # Errors docs, and unwrap() in its doc examples. With the
skill, the same agent kept the fields private, documented failure modes, and wrote doc
examples users can copy safely. Condensed from those two runs:
// Without the skill
/// A semantic version. The fields are public for convenience.
pub struct Version {
pub major: u64,
pub minor: u64,
pub patch: u64,
pub pre: Vec<Identifier>,
pub build: Vec<String>,
}
impl Version {
/// Parses a version string.
///
/// ```
/// let v = Version::parse("1.2.3").unwrap();
/// ```
pub fn parse(s: &str) -> Result<Version, ParseError> { /* ... */ }
}// With the skill
/// A semantic version. Equality, hashing, and ordering ignore build metadata.
pub struct Version {
major: u64,
minor: u64,
patch: u64,
pre: Vec<Identifier>,
build: Vec<String>,
}
impl Version {
/// Parses a version string according to SemVer 2.0.0.
///
/// # Errors
///
/// Returns [`ParseVersionError`] if the string is empty, a numeric part has a
/// leading zero or overflows `u64`, or an identifier contains invalid characters.
///
/// ```
/// # use semver_lite::Version;
/// # fn main() -> Result<(), semver_lite::ParseVersionError> {
/// let v = Version::parse("1.2.3-beta.1")?;
/// assert_eq!(v.major(), 1);
/// # Ok(())
/// # }
/// ```
pub fn parse(s: &str) -> Result<Self, ParseVersionError> { /* ... */ }
/// Returns the major version number.
pub fn major(&self) -> u64 { self.major }
}Across three test tasks (a library, a CLI, and refactoring a messy module), the skill passed 29 of 30 checks against 24 of 30 without it. See Testing the skills.
Each skill is a folder under skills/: rust-best-practices/, rust-review/, and
rust-port/. Every option below puts those folders where your agent looks for skills.
Install all three; the review and port skills lean on the best-practices skill for style.
The skills installer supports most agents
(Node 22.20 or later):
npx skills add morganlinton/BeautifulRustAdd -g to install for your user instead of the current project, or -a <agent> to pick
an agent, such as -a codex or -a cursor.
Install it as a plugin so updates arrive with one command:
claude plugin install beautiful-rust --marketplace morganlinton/BeautifulRustInside a session, the same thing is:
/plugin marketplace add morganlinton/BeautifulRust
/plugin install beautiful-rust@beautiful-rust
This installs all three skills. They appear as /beautiful-rust:rust-best-practices,
/beautiful-rust:rust-review, and /beautiful-rust:rust-port, though you rarely need to
call them, since they trigger on their own. To try it for one session without installing, clone the repo
and run claude --plugin-dir ./BeautifulRust.
Install it as a plugin:
codex plugin marketplace add morganlinton/BeautifulRust
codex plugin add beautiful-rust@beautiful-rustThis installs all three skills as beautiful-rust:rust-best-practices,
beautiful-rust:rust-review, and beautiful-rust:rust-port. The same package works in
the ChatGPT desktop app.
With GitHub CLI 2.90 or later:
gh skill install morganlinton/BeautifulRust rust-best-practices
gh skill install morganlinton/BeautifulRust rust-review
gh skill install morganlinton/BeautifulRust rust-portThis installs into the current project by default. Add --scope user to install for your
user, or --agent <name> to install for a different agent.
gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-best-practices
gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-review
gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-portClone the repo and copy the three skill folders into your agent's skills directory.
Most agents now read the shared .agents/skills/ location:
git clone https://github.com/morganlinton/BeautifulRust
mkdir -p ~/.agents/skills
cp -R BeautifulRust/skills/rust-* ~/.agents/skills/| Agent | User directory | Project directory |
|---|---|---|
| Claude Code | ~/.claude/skills/ |
.claude/skills/ |
| OpenAI Codex | ~/.agents/skills/ |
.agents/skills/ |
| GitHub Copilot | ~/.copilot/skills/ or ~/.agents/skills/ |
.github/skills/ or .agents/skills/ |
| Cursor | ~/.cursor/skills/ or ~/.agents/skills/ |
.cursor/skills/ or .agents/skills/ |
| Gemini CLI | ~/.gemini/skills/ or ~/.agents/skills/ |
.gemini/skills/ or .agents/skills/ |
Claude Code does not read .agents/skills/, so use its own directory or the plugin.
Restart the agent if the skill doesn't show up right away.
claude.ai takes one zip per skill, with the skill folder as the zip root:
cd skills
zip -r ../rust-best-practices.zip rust-best-practices -x '*.DS_Store' -x '*/evals/*'
zip -r ../rust-review.zip rust-review -x '*.DS_Store' -x '*/evals/*'
zip -r ../rust-port.zip rust-port -x '*.DS_Store' -x '*/evals/*'Upload each under Customize > Skills. Code execution must be enabled first.
Ask your agent to review a file, crate, or diff, for example "review src/parser.rs" or
"what would you change in this PR". The rust-review skill runs cargo fmt, clippy, and
the tests when a toolchain is available, then writes a report with three tiers: must fix,
should fix, and consider. Every finding gives a file:line location, the rule it breaks
with its source (an API Guidelines code such as C-GETTER, an Effective Rust item, a
Microsoft guideline, or a clippy lint), and the smallest code change that fixes it. Each
report ends with what the code already does well.
examples/review-inventory.md is a real review the skill
produced for the deliberately messy module in the eval cases.
Ask your agent to port a module, for example "port parser.c to Rust" or "rewrite this
Python service in Rust". The rust-port skill reads the original and its tests, ports the
tests first, designs a Rust API instead of transliterating the original, and verifies with
cargo test and clippy. It maps each language's habits to their Rust equivalents:
NULL and None to Option, error codes and exceptions to an error enum, out-parameters
to return values, flag ints and magic strings to typed enums and options, and dict
insertion order to an ordered collection instead of a HashMap that would silently
reorder output. Each port comes with a PORTING.md that maps the old API and tests to the
new ones and lists every deliberate difference.
Bevy calls your systems and builds their arguments, so some general Rust advice is wrong
for them. Taken at face value, the skills would tell an agent to change Res<Time> to a
reference, replace use bevy::prelude::* with explicit imports, and split a system to
quiet clippy. When a crate depends on bevy or bevy_ecs, both the writing and review
skills now read references/bevy.md
first. It covers Bevy 0.20 and does two things:
- It names the conventions to leave alone: system parameters taken by value, the Bevy prelude, public fields on plain-data components, and complex query types.
- It lists the ECS bugs that compile cleanly. Two queries that can both mutate the
same component panic with error B0001 on the first frame. A system can read the world
before another system's
Commandshave applied. Systems that depend on each other may have no order between them. A.single().unwrap()crashes the game once the player dies.
Every behavior in the reference was checked with a test against bevy 0.20.0. Two eval cases cover it: a review of a combat plugin with two of those bugs planted, and a feature added to the fixed plugin, which checks that the agent keeps Bevy's conventions.
The skills teach the rules; the lints keep them from slipping back in. Copy
lints/clippy.toml next to your Cargo.toml and paste the [lints]
block from lints/lints.toml into it, then run:
cargo clippy --all-targets --all-features -- -D warningsIt flags unwrap() outside tests, unsafe blocks without a // SAFETY: comment, #[allow]
without a reason, any bool function parameter, silent lossy as casts, missing # Errors
and # Panics docs, assert! without a message, exported enums that aren't
#[non_exhaustive], and leftover dbg! and todo!. Lints marked [lib] in the file are
for libraries, and applications can drop them. Bevy crates need four extra allows,
listed in the Bevy reference,
because the table otherwise flags every idiomatic system signature.
Every lint in the table is proven to fire. lints/check/ is a small crate
with one deliberate violation per lint, and this script runs clippy on it from the repo
root:
bash scripts/check-lints.shIt fails if a lint stops firing, if something unexpected fires, or if the check crate's
copy of the table drifts from lints/lints.toml. allow_attributes and
allow_attributes_without_reason need rust-version = "1.81" or later, because clippy
switches them off for crates that can't use #[expect].
skills/rust-best-practices/SKILL.md is about 500 lines, organized so an agent can scan
it while coding:
- Mindset: Rust-shaped code, invalid states unrepresentable, application vs library
- Pre-handback checklist: fmt, clippy with
-D warnings, test, doc; lint policy - Ownership and borrowing: what to do instead of cloning for the borrow checker
- Types and API design: naming, newtypes, common traits, builders, visibility, generics vs
dyn - Errors and panics:
OptionvsResultvs panic, library vs application error types - Everyday idioms: iterators, combinators,
format!, imports, drop guards - Concurrency and async:
Sendassertions, lock discipline,async fn, yield points - Unsafe and FFI: when it's allowed,
SAFETY:comments, soundness, bindgen - Crates, modules, dependencies: workspace layout, features, semver
- Documentation and comments
- Tests
- Performance, in order
- Final checklist
skills/rust-best-practices/references/ holds one digest per source for deeper lookups.
BeautifulRust/
├── .claude-plugin/
│ ├── plugin.json Claude Code plugin manifest
│ └── marketplace.json lets this repo act as its own marketplace
├── .agents/plugins/
│ └── marketplace.json the same, for Codex
├── plugin.json Codex and ChatGPT plugin manifest
├── assets/icon.png plugin icon for Codex and ChatGPT
├── skills/
│ ├── rust-best-practices/ writing skill
│ │ ├── SKILL.md
│ │ ├── references/ one digest per source, plus bevy.md
│ │ └── evals/
│ ├── rust-review/ review skill
│ │ ├── SKILL.md
│ │ └── evals/
│ └── rust-port/ porting skill
│ ├── SKILL.md
│ └── evals/ a C module and a Python module to port
├── lints/
│ ├── lints.toml [lints] block for Cargo.toml
│ ├── clippy.toml clippy thresholds
│ └── check/ one deliberate violation per lint
├── scripts/
│ ├── check-skill.py validates skills, evals, and manifests
│ ├── check-lints.sh proves every lint in the table fires
│ ├── check-examples.py compiles every Rust example in the docs
│ ├── examples.json context that lets fragment examples compile
│ ├── package-openai-plugin.py builds the ChatGPT / Codex directory ZIP
│ └── build-mcp-data.py builds the MCP server's search index and lint catalog
├── mcp/ MCP server (Vercel Function) at mcp.beautifulrust.dev
├── benchmarks/
│ └── cross-agent-2026-10/ Claude Code vs Codex, with and without the skills
├── examples/
│ └── review-inventory.md a real review report
├── CHANGELOG.md
├── CONTRIBUTING.md
├── PRIVACY.md
└── README.md
skills/rust-best-practices/evals/ holds four test cases in the layout claude plugin eval
reads: a library API design task, an application CLI task, and a refactor-this-module task
with an input file. Each case has the prompt, a description of a good result, and one
assertion per file under graders/. Run them with and without the skill from the skill
directory:
claude plugin eval . --allow-tools Write,Edit,Bash --scaffoldskills/rust-review/evals/ holds a review case for the same messy module and one for a
Bevy plugin with two ECS bugs planted, and skills/rust-port/evals/ holds a C module and
a Python module to port, each with its original test suite. The writing skill also has a
Bevy case that adds a feature to a working plugin. Run them the same way from each
skill's directory.
These are real model runs and are billed.
Across agents. The October 2026 benchmark ran all eight cases on Claude Code and OpenAI's Codex CLI, with and without the skills, and graded the results blind:
| No skills | Skills | |
|---|---|---|
| Claude Code (Opus 5.5) | 72/85 (85%) | 80/85 (94%) |
| Codex CLI (default model) | 53/85 (62%) | 76/85 (89%) |
The skills helped Codex more than Claude, and helped reviews most. They hurt in one case: Claude did worse on the Bevy feature task with them. The benchmark page has the details, the method, and the caveats. Notably, it was one run per configuration, graded by a Claude model.
Edit the skill, bump version in both .claude-plugin/plugin.json and plugin.json
(the checker fails if they differ), commit, and push. Claude Code plugin users pick up the
new version with:
claude plugin update beautiful-rustCodex users refresh the marketplace with:
codex plugin marketplace upgrade beautiful-rustAnyone who copied the folder or used an installer re-runs the install command. Record each release in CHANGELOG.md.
Validate before pushing. python3 scripts/check-skill.py checks skill
frontmatter, links, eval cases, and plugin manifests. Pass --json for
machine-readable output. python3 scripts/check-examples.py compiles every Rust
block in the skills, reference digests, README, and examples with cargo check.
python3 scripts/check-skill.py
python3 scripts/check-examples.py
claude plugin validate .To publish a release to the ChatGPT / Codex Plugins Directory, update release_notes in
plugin.json, then build the upload:
python3 scripts/package-openai-plugin.pyThis writes dist/beautiful-rust-<version>.zip with the manifest, the skills and their
references, the icon, the license, and the privacy policy, but not the eval cases. Upload
it at platform.openai.com/plugins from a verified
developer account, as described in OpenAI's
submission guide.
Issues and pull requests are welcome. Every rule needs a published source; see CONTRIBUTING.md for how to propose a rule, report a review false positive, or add an eval case.
The guidance in this skill is a synthesis. The five digests in
skills/rust-best-practices/references/ are paraphrased summaries written for this
project; they restate each source's advice in condensed form and link back to the
original. Read the originals for the full reasoning.
| Source | Author | License |
|---|---|---|
| Google Rust Style Guide | CC BY 3.0 | |
| Rust API Guidelines | The Rust Project | MIT or Apache-2.0 |
| Effective Rust | David Drysdale, published by O'Reilly | CC BY-NC-ND 4.0 (online edition) |
| Rust Design Patterns | rust-unofficial contributors | MPL-2.0 |
| Pragmatic Rust Guidelines | Microsoft | MIT |
The skill text, the digests, the banner, and the generator script in this repository are MIT licensed (see LICENSE). The crab is a crab, not the Rust mascot.
MIT. See LICENSE.