Routes by task to per-topic references and lifts cross-cutting
principles (edition, errors, tracing) into one place. Prepares for
adding binary and server references without duplicating shared
scaffolding.

Assisted-by: Claude Opus 4.7 (1M context) via Claude Code

diff --git a/ai/skills/rust/SKILL.md b/ai/skills/rust/SKILL.md
new file mode 100644
index 00000000..20e18956
--- /dev/null
+++ b/ai/skills/rust/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: rust
+description: Use when writing, reviewing, scaffolding, releasing, or measuring coverage on Rust code — routes to references for style, project layout, testing, Dockerfile, and release
+---
+
+# Rust
+
+Preferences for writing and shipping Rust. The actual guidance lives
+in references — this file routes by task and lists the cross-cutting
+principles that apply everywhere.
+
+*This is a self-improving skill — see the `self-improving-skills` skill.*
+
+## When to read which reference
+
+| Task | Read |
+|------|------|
+| Writing or reviewing Rust code | `style.md` |
+| Scaffolding a new project | `scaffolding.md` + `binary.md` (CLI) or `server.md` (server) |
+| Setting up a Dockerfile for a server | `dockerfile.md` |
+| Debugging coverage gaps | `coverage.md` |
+| Adding property tests | `property-testing.md` |
+| Adding mutation testing | `mutation-testing.md` |
+| Wiring `<NAME>_VERSION` into a binary | `versioning.md` |
+| Releasing a CLI binary | `binary.md` (release section) |
+| Deploying a server | `server.md` (deploy section) + `dockerfile.md` |
+
+## Cross-cutting principles
+
+These apply to every Rust project regardless of shape.
+
+### Edition
+
+`edition = "2024"` for new projects. Bump existing projects when
+upstream dependencies require it, not preemptively.
+
+### Project structure
+
+Single crate with both library and binary targets. All domain logic
+lives in the library; the binary is a thin shell that parses input,
+calls the library, and renders output. `scaffolding.md` covers the
+layout in detail.
+
+### Errors
+
+Library errors derive `thiserror::Error` *and* `miette::Diagnostic`.
+The diagnostic codes and help text live on the variant itself, so
+errors carry their own labels and source spans through tests, other
+binaries, and HTTP handlers. Binaries return `miette::Result<()>` from
+`main` and call `miette::set_panic_hook()` early.
+
+### Logging
+
+Use `tracing` and `tracing-subscriber` with `EnvFilter`. Never
+`println!` for diagnostic output — `println!` belongs to user-facing
+program output only.
+
+### Filesystem
+
+Use `fs-err` instead of `std::fs`. Bare `std::fs` errors omit the
+path that failed. The Clippy configuration in `style.md` enforces
+this.
+
+### Cargo.lock
+
+Commit `Cargo.lock` for binaries (CLIs and servers both). Builds
+stay reproducible even though dependency versions in `Cargo.toml`
+are unpinned (`"*"`). `cargo update` upgrades to the latest
+compatible release without editing `Cargo.toml`.
+
+### Task runner
+
+Use `just`. The `justfile` template is in `scaffolding.md`.
+
+### CI
+
+GitHub Actions, with every `uses:` pinned to a commit SHA and a
+version comment (`@<sha> # v4`). Never pin to a moving tag.
+
+### Async runtime
+
+`tokio` with `features = ["full"]` for both CLIs and servers.
+Single-threaded runtimes are an opt-in micro-optimization, not a
+default.
diff --git a/ai/skills/rust-coverage/SKILL.md b/ai/skills/rust/coverage.md
similarity index 97%
rename from ai/skills/rust-coverage/SKILL.md
rename to ai/skills/rust/coverage.md
index a43b2fa8..e1e9dba2 100644
--- a/ai/skills/rust-coverage/SKILL.md
+++ b/ai/skills/rust/coverage.md
@@ -1,9 +1,4 @@
----
-name: rust-coverage
-description: Use when measuring code coverage in Rust projects, debugging uncovered lines, generating coverage reports, or setting up LLVM source-based coverage with cargo-llvm-cov or grcov
----
-
-# Rust Source-Based Code Coverage
+# Rust source-based code coverage
 
 LLVM source-based coverage via `cargo-llvm-cov`, which wraps rustc's `-C instrument-coverage` flag.
 
diff --git a/ai/skills/rust-style/SKILL.md b/ai/skills/rust/style.md
similarity index 96%
rename from ai/skills/rust-style/SKILL.md
rename to ai/skills/rust/style.md
index ecdf512e..c48b57fc 100644
--- a/ai/skills/rust-style/SKILL.md
+++ b/ai/skills/rust/style.md
@@ -1,11 +1,8 @@
----
-name: rust-style
-description: Use when writing, reviewing, or restructuring Rust code — covers project layout, module organization, file structure, item ordering, function design, and Clippy automation
-source: https://epage.github.io/dev/rust-style/
----
-
 # Rust style
 
+*Source: <https://epage.github.io/dev/rust-style/>.*
+
+
 Code is technical writing. Apply the inverted pyramid: lead with the most salient details, let readers decide how deep to go. Cross-references (functions, types) are cheap, but reader memory is not — optimize for skimming.
 
 ## Project structure
@@ -30,7 +27,7 @@ src/
   lib.rs
 ```
 
-Automation: no Clippy lint exists for this convention — enforce in code review.
+Automation: `clippy.self_named_module_files = "warn"`
 
 ### Directory roots only re-export (P-DIR-MOD)
 
@@ -283,6 +280,8 @@ The Clippy configuration below enforces this — `std::fs` functions and `std::f
 Collect these in `.clippy.toml` at the crate root:
 
 ```toml
+self-named-module-files = "warn"
+
 disallowed-methods = [
     { path = "std::iter::Iterator::for_each", reason = "prefer `for` for side-effects" },
     { path = "std::iter::Iterator::try_for_each", reason = "prefer `for` for side-effects" },