docs: improve README and expand sources & attribution

README.md

@@ -1,9 +1,18 @@
 # Rust Skills
 
+![rules](https://img.shields.io/badge/rules-218-blue)
+![categories](https://img.shields.io/badge/categories-18-blue)
+![Rust](https://img.shields.io/badge/Rust-1.96%20%2F%202024%20edition-orange)
+![license](https://img.shields.io/badge/license-MIT-green)
+
 218 Rust rules your AI coding agent can use to write better code. Current for Rust 1.96 (2024 edition).
 
 Works with Claude Code, Cursor, Windsurf, Copilot, Codex, Aider, Zed, Amp, Cline, and pretty much any other agent that supports skills.
 
+## Why
+
+Out of the box, coding agents write *average* Rust — they clone to dodge the borrow checker, `.unwrap()` everything, and reach for `Box<dyn Trait>` when `impl Trait` would do. These rules encode what expert Rust actually looks like: idiomatic, fast, and safe. Each rule is small and focused, so the agent pulls in only what's relevant to the code in front of it.
+
 ## Install
 
 ```bash
@@ -28,8 +37,33 @@ After installing, just ask your agent:
 /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.
 
+## See it in action
+
+Ask the agent to review a function like this:
+
+```rust
+// before
+fn first_word(s: &String) -> String {
+    s.clone().split_whitespace().next().unwrap().to_string()
+}
+```
+
+With these rules loaded, it knows to take `&str` instead of `&String`, drop the
+needless `clone()` and allocation, and return an `Option` instead of panicking:
+
+```rust
+// after — applies own-slice-over-vec, own-borrow-over-clone, anti-unwrap-abuse
+fn first_word(s: &str) -> Option<&str> {
+    s.split_whitespace().next()
+}
+```
+
 ## What's in here
 
 218 rules split into 18 categories:
@@ -57,9 +91,19 @@ The agent loads the relevant rules and applies them to your code.
 
 Each rule has:
 - Why it matters
-- Bad code example
-- Good code example
-- Links to official docs when relevant
+- A bad code example
+- A good code example
+- Links to related rules and sources
+
+## How it works
+
+The design is built for low token cost and easy auditing:
+
+- **[`SKILL.md`](./SKILL.md)** is a lightweight index — every rule listed as a one-line summary, grouped by category, with a link to its file. The agent reads this first.
+- **[`rules/`](./rules)** holds one Markdown file per rule (`<prefix>-<name>.md`). The agent opens only the handful relevant to your code instead of loading all 218 — progressive disclosure keeps context small.
+- **Prefixes** (`own-`, `err-`, `unsafe-`, `async-`, …) map directly to categories, so an agent reviewing async code can pull just `async-`, `conc-`, and `own-` rules.
+
+`CLAUDE.md` and `AGENTS.md` are symlinks to `SKILL.md`, so the same content works across agent conventions.
 
 ## Manual install
 
@@ -183,17 +227,67 @@ curl -o AGENTS.md https://raw.githubusercontent.com/leonardomso/rust-skills/mast
 
 See [SKILL.md](./SKILL.md) for the full list with links to each rule file.
 
-## Where these rules come from
+## Sources & attribution
 
+These rules are an independent synthesis of official Rust guidance, well-known books, and patterns drawn from widely-used open-source crates. They are not affiliated with or endorsed by the Rust project or any crate author. The text and code examples are original summaries — no substantial content is copied from the sources below.
+
+**Official Rust documentation**
+- [The Rust Reference](https://doc.rust-lang.org/reference/)
 - [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
-- [Rust Performance Book](https://nnethercote.github.io/perf-book/)
-- [Rust Design Patterns](https://rust-unofficial.github.io/patterns/)
-- Real code from ripgrep, tokio, serde, polars, axum
-- Clippy docs
+- [The Rustonomicon](https://doc.rust-lang.org/nomicon/) (unsafe code)
+- [Rust 2024 Edition Guide](https://doc.rust-lang.org/edition-guide/rust-2024/)
+- [The Cargo Book](https://doc.rust-lang.org/cargo/)
+- [Standard library docs](https://doc.rust-lang.org/std/) and [release notes](https://doc.rust-lang.org/releases.html)
+
+**Books & guides**
+- [The Rust Performance Book](https://nnethercote.github.io/perf-book/) — Nicholas Nethercote
+- [Rust Design Patterns](https://rust-unofficial.github.io/patterns/) — rust-unofficial
+- [Rust Atomics and Locks](https://marabos.nl/atomics/) — Mara Bos
+- [Effective Rust](https://effective-rust.com/) — David Drysdale
+
+**Tooling**
+- [Clippy lint documentation](https://rust-lang.github.io/rust-clippy/)
+- [Miri](https://github.com/rust-lang/miri)
+
+**Real-world codebases studied for idioms**
+- ripgrep, tokio, serde, clap, polars, axum, cargo, hyper, bevy, rayon, and dtolnay's crates (thiserror, anyhow, syn)
+
+This project is MIT-licensed. Referenced upstream materials remain under their own licenses — the official Rust documentation and API Guidelines are dual [MIT](https://github.com/rust-lang/rust/blob/master/LICENSE-MIT) / [Apache-2.0](https://github.com/rust-lang/rust/blob/master/LICENSE-APACHE).
 
 ## Contributing
 
-PRs welcome. Just follow the format of existing rules.
+PRs welcome. To add or change a rule:
+
+1. Create `rules/<prefix>-<name>.md` using a `kebab-case` id with an existing category prefix (`own-`, `err-`, `mem-`, …).
+2. Follow the format of existing rules: a `>` one-line summary, then `## Why It Matters`, `## Bad`, `## Good`, and `## See Also` (with links that resolve).
+3. Make sure code examples compile on current stable Rust.
+4. Add the rule to the index in `SKILL.md` (Quick Reference list + the category count) so it stays in sync.
+
+````markdown
+# prefix-rule-name
+
+> One-line imperative summary.
+
+## Why It Matters
+
+Two to four sentences.
+
+## Bad
+
+```rust
+// the anti-pattern
+```
+
+## Good
+
+```rust
+// the recommended pattern
+```
+
+## See Also
+
+- [other-rule](other-rule.md) - why it's related
+````
 
 ## License
 

SKILL.md

@@ -386,14 +386,29 @@ This skill provides rule identifiers for quick reference. When generating or rev
 
 ---
 
-## Sources
+## Sources & Attribution
 
-This skill synthesizes best practices from:
+This skill is an independent synthesis of official Rust guidance, well-known books, and patterns from widely-used crates. It is not affiliated with or endorsed by the Rust project or any crate author; the text and code examples are original.
+
+**Official Rust documentation**
+- [The Rust Reference](https://doc.rust-lang.org/reference/)
 - [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
-- [Rust Performance Book](https://nnethercote.github.io/perf-book/)
-- [Rust Design Patterns](https://rust-unofficial.github.io/patterns/)
-- [The Rustonomicon](https://doc.rust-lang.org/nomicon/)
+- [The Rustonomicon](https://doc.rust-lang.org/nomicon/) (unsafe code)
 - [Rust 2024 Edition Guide](https://doc.rust-lang.org/edition-guide/rust-2024/)
-- Production codebases: ripgrep, tokio, serde, polars, axum, cargo
-- Clippy lint documentation
-- Community conventions (2024-2026)
+- [The Cargo Book](https://doc.rust-lang.org/cargo/)
+- [Standard library docs](https://doc.rust-lang.org/std/) and [release notes](https://doc.rust-lang.org/releases.html)
+
+**Books & guides**
+- [The Rust Performance Book](https://nnethercote.github.io/perf-book/) — Nicholas Nethercote
+- [Rust Design Patterns](https://rust-unofficial.github.io/patterns/) — rust-unofficial
+- [Rust Atomics and Locks](https://marabos.nl/atomics/) — Mara Bos
+- [Effective Rust](https://effective-rust.com/) — David Drysdale
+
+**Tooling**
+- [Clippy lint documentation](https://rust-lang.github.io/rust-clippy/)
+- [Miri](https://github.com/rust-lang/miri)
+
+**Real-world codebases studied for idioms**
+- ripgrep, tokio, serde, clap, polars, axum, cargo, hyper, bevy, rayon, and dtolnay's crates (thiserror, anyhow, syn)
+
+This project is MIT-licensed. Referenced upstream materials remain under their own licenses (the official Rust docs and API Guidelines are dual MIT / Apache-2.0).