# rust-skills gives coding agents 265 rules about idiomatic Rust

> rust-skills is a set of 265 Rust review rules in 26 categories, packaged as a skill that agents such as Claude Code, Cursor, Codex and Copilot can load on demand. The design is progressive disclosure, a small index file the agent reads first, then only the rule files relevant to the code in front of it.

**leonardomso/rust-skills** — A collection of 265 rules across 26 categories that AI coding agents can use to write   idiomatic, fast, and safe Rust.

- Repository: https://github.com/leonardomso/rust-skills
- Stars: 622 · Forks: 68
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/leonardomso-rust-skills

## The problem is average Rust, not missing Rust

The framing in the documentation is unusually blunt. Out of the box, coding agents write average Rust: they clone to dodge the borrow checker, they unwrap everything, and they reach for Box<dyn Trait> when impl Trait would do. Those are three specific failure modes, and each one is a habit an agent picks up from the training data rather than a decision a Rust programmer would defend.

That is the problem this repository addresses. It describes itself as 265 Rust rules your AI coding agent can use to write better code, current for Rust 1.96 with the 2024 edition, and says the rules encode what expert Rust actually looks like: idiomatic, fast and safe.

The claim about scale is worth pausing on. A Rust crate written by a competent human already reflects most of these decisions, so the value here is not in teaching an expert something new. The value is in making the agent's output match what you would have written, consistently, every time.

The audience is therefore narrow and clear: a Rust developer who already uses an AI coding agent and wants the agent to stop making the same small, well-known mistakes. The topics on the repository list the tools it targets, including claude-code, codex, copilot and opencode.

The rules are described as small and focused on purpose, so the agent pulls in only what is relevant to the code in front of it. That is a design decision with real consequences, and it is covered below.

## Progressive disclosure: an index first, then only the rules that matter

The architecture is built for low token cost and easy auditing, and it comes down to two pieces.

SKILL.md is a lightweight index where every rule appears as a one-line summary, grouped by category, with a link to its file. The agent reads that first. The rules directory then holds one Markdown file per rule, named with a prefix and a name such as own-slice-over-vec.md, and the agent opens only the handful relevant to the code in front of it instead of loading everything.

The prefixes map directly to categories, with examples given as own-, err-, unsafe- and async-. An agent reviewing async code can therefore pull just the async-, conc- and own- rules, and the naming convention is what makes that possible without a lookup table.

Each rule carries the same four things: why it matters, a bad code example, a good code example, and links to related rules and sources. That structure is what makes the set auditable. A rule that says "avoid unwrap" is an opinion; a rule that shows the bad code, the good code, and links to the source of the guidance is something you can disagree with on the record.

One inconsistency in the documentation is worth flagging so you are not confused by it. The badges, the description and the category table all say 265 rules across 26 categories, but the sentence describing the rules directory says the agent avoids loading all 218. The project also publishes a CHANGELOG.md, so the count appears to have moved at some point and one of the two numbers was not updated.

## Installing it with one npx command, or by hand for each agent

The documented install path is a single command:

```bash
npx add-skill leonardomso/rust-skills
```

The documentation says the CLI figures out which agents you have and installs the skill to the right place, which is the whole point of the add-skill convention: the same repository works across a dozen tools with different directory conventions.

If that does not fit your setup, the manual instructions are given per agent. For Claude Code, globally for all projects:

```bash
git clone https://github.com/leonardomso/rust-skills.git ~/.claude/skills/rust-skills
```

or for one project only, into .claude/skills/rust-skills. For OpenCode it is .opencode/skills/rust-skills, for Cursor it is .cursor/skills/rust-skills, and for OpenAI Codex it is .codex/skills/rust-skills, each with the same git clone command and a different destination directory.

The lighter alternatives exist too. For Cursor you can fetch just the index file as .cursorrules:

```bash
curl -o .cursorrules https://raw.githubusercontent.com/leonardomso/rust-skills/master/SKILL.md
```

For Windsurf you create a rules directory and put the same file there as rust-skills.md:

```bash
mkdir -p .windsurf/rules
curl -o .windsurf/rules/rust-skills.md https://raw.githubusercontent.com/leonardomso/rust-skills/master/SKILL.md
```

For GitHub Copilot the destination is .github/copilot-instructions.md, and for Zed and for the AGENTS.md standard the destination is AGENTS.md. Aider reads the file through its config or on the command line:

```yaml
read: path/to/rust-skills/SKILL.md
```

Note that fetching only SKILL.md gives the index without the rule files, which works only if the agent can still reach the repository. The clone gives it everything.

## The before and after example is the product demo

The demonstration in the documentation is short, and it is the clearest way to judge whether the rules match your taste.

The before version of a function that returns the first word of a string looks like this:

```rust
// before
fn first_word(s: &String) -> String {
    s.clone().split_whitespace().next().unwrap().to_string()
}
```

With the rules loaded, the documentation says the agent knows to take &str instead of &String, drop the needless clone and allocation, and return an Option instead of panicking. The rewritten function takes &str and returns Option<&str>.

That rewrite touches three separate categories at once, which is the point of the prefix scheme. own-slice-over-vec is about taking a slice rather than a vector, own-borrow-over-clone is about borrowing instead of cloning, and anti-unwrap-abuse is about not panicking on a None. The naming in the comment is there so you can see the mapping.

Whether the result is better is a judgement call rather than a settled matter. Returning Option<&str> is a signature change that pushes the error handling to the caller, and some people would rather have a String back. The rules encode one opinionated answer, and the value of the example is that it shows you the shape of that opinion in three lines.

If those three rules are wrong for your crate, the other 262 are worth reading too, and the four-part rule format lets you find the ones you disagree with quickly.

## Where the 26 categories come from, and where they do not fit

The category table is the best available map of the coverage, and reading it shows both the reach and the gaps.

The largest groups are Async with 18 rules, Memory and API Design with 17 each, Naming and Testing and Project Structure with 15 or 16, and Anti-patterns with 15. The smallest are Conversions with 3, Concurrency with 4, and Const and Compile-Time with 4.

The content within each category is specific rather than generic. Ownership and Borrowing covers when to borrow versus clone, Arc and Rc, and lifetimes. Error Handling is described as thiserror for libraries, anyhow for applications, and the ? operator. Unsafe Code covers SAFETY: comments, Miri, MaybeUninit and the 2024 edition unsafe changes. Async covers Tokio patterns, channels, async fn in traits and cancel safety. Concurrency covers rayon, scoped threads, atomic ordering and thread-locals. Optimization covers LTO, inlining, PGO and SIMD. Numeric and Arithmetic covers overflow handling, the as cast versus TryFrom, float comparison and NonZero types.

Two things stand out as opinions rather than facts. The split of thiserror for libraries and anyhow for applications is a real convention in the ecosystem but not a law, and the Testing category names specific tools, Proptest, mockall, criterion, loom and snapshot tests, which means the rules will pull those dependencies into your reasoning. Linting covers Clippy configuration, CI setup and unexpected_cfgs.

The rules that will land hardest are the ones that touch your public API. API Design, Type Safety and Naming are where a review pass can turn into a breaking change proposal if the agent applies them to an existing crate rather than to new code.

## Asking the agent in natural language, not configuring anything

There is no configuration file, no per-project settings and no rule selection UI. After installing, you ask the agent, and the examples in the documentation are slash commands:

```
/rust-skills review this function
```

```
/rust-skills is my error handling idiomatic?
```

```
/rust-skills check for memory issues
```

```
/rust-skills is this unsafe block sound?
```

The agent loads the relevant rules and applies them to your code. The four examples map onto the four things you would realistically want checked: a general review, error handling, memory, and unsafe code soundness.

The progressive disclosure design does the work here. Because SKILL.md lists all the rules as one-line summaries grouped by category, the agent can decide which files to open, and it opens only those. That is why the design description emphasises low token cost, and it is the reason a 265 rule set is workable inside an agent context window at all.

The symlink detail completes the portability story. CLAUDE.md and AGENTS.md are symlinks to SKILL.md, so the same content works across agent conventions without duplicating a file, and the repository root listing shows both of those files alongside SKILL.md, plus CONTRIBUTING.md, a checks directory, a rules directory and a .github directory.

Note that the wording of the questions is open-ended, and the agent decides what to load. If you want a specific rule applied, the prefix naming is the lever: ask for the async rules, or point the agent at the file for a rule you disagree with.

## MIT licensed, unversioned, and pinned to a Rust release that will move

The licence is MIT, which is the least complicated case for a repository of prose and examples. The LICENSE file sits at the root next to the README, SKILL.md and AGENTS.md.

On versioning, there is a subtlety. The project publishes no GitHub releases, and the package version comes from a different source: the install is via npx add-skill against the GitHub repository, and the manual instructions clone the repository or curl from the master branch of the raw URL. The default branch is master and the last push was on 2026-06-14.

That means there is no version to pin, and your installed copy tracks whatever master contained when you cloned it. For a set of review rules that is arguably fine, since the content is advisory and the agent reads it fresh each session. It does mean a rule can change under you without a changelog entry, which is a reason to clone rather than curl if you want reproducibility, and a reason to re-read SKILL.md when you notice behaviour shifting.

The CHANGELOG.md at the root suggests changes are recorded, at least sometimes. The rules are described as current for Rust 1.96 with the 2024 edition, which is a snapshot claim rather than a moving target, and it will age. Rust edition changes and standard library additions land regularly, and a rule that says a pattern is unnecessary may become wrong when the language gains a better way.

The checks directory is worth a look before adopting the set wholesale, since it is presumably where the consistency of the rules is checked.

## Conclusion

rust-skills suits a Rust developer who already uses an AI coding agent and keeps hitting the same mediocre output, such as cloned strings to dodge the borrow checker or unwrap calls everywhere, and who wants a reviewable rule set rather than a vague instruction. It is the wrong choice if you want the agent to redesign your crate rather than correct it, since the rules are corrective, and the wrong choice if you will not read the rule files the agent opens. Before adopting it, open SKILL.md and one file under rules/ to see whether the advice matches your own style, since the project is opinionated, and pin the repository to a commit, because the rules are described as current for Rust 1.96 with the 2024 edition and will drift as the toolchain moves.

## FAQ

### How do I install the rust-skills rules for my coding agent?

Run npx add-skill leonardomso/rust-skills, and the CLI detects which agents you have and installs the skill in the right place. For a manual install, clone the repository into the agent's skills directory, for example .claude/skills/rust-skills for Claude Code or .opencode/skills/rust-skills for OpenCode.

### What is the difference between SKILL.md and the rules directory?

SKILL.md is a lightweight index listing every rule as a one-line summary grouped by category with a link to its file, and the agent reads it first. The rules directory holds one Markdown file per rule named with a category prefix such as own- or async-, and the agent opens only the ones relevant to the code in front of it.

### What does each rule in rust-skills contain?

Each rule has why it matters, a bad code example, a good code example, and links to related rules and sources. The rules are split into 26 categories covering areas such as Ownership and Borrowing, Error Handling, Memory, Unsafe Code, Async, API Design, Serde, Testing and Linting.

## Sources

- [Issues](https://github.com/leonardomso/rust-skills/issues)
- [leonardomso/rust-skills on GitHub](https://github.com/leonardomso/rust-skills)
- [License: MIT](https://github.com/leonardomso/rust-skills/blob/master/LICENSE)
- [README](https://github.com/leonardomso/rust-skills/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/leonardomso-rust-skills