rust-implement — Claude Code skill: what it does, how to install
rust-implement enforces a four-pass discipline for Rust development, moving from strict type design to implementation, simplification, and automated linting.
MIT 254 installs ★ 227 updated 2026-08-15
npx skills add pproenca/dot-skills --skill rust-implement -a claude-codeWhat rust-implement does
This skill guides the coding agent through four distinct engineering passes. During the first pass, it drafts only data types and function signatures. Booleans turn into enums, functions with four or more parameters receive dedicated argument structs, and structures intended for serialization rely on BTreeMap instead of HashMap. The implementation pass strictly demands .context() on every ? operator, bans wildcard match arms, and separates errors between anyhow for applications and thiserror for crates.
The simplification pass removes forwarded call-chain arguments and inlines single-use wrappers. Finally, the verification pass executes bash ${SKILL_DIR}/scripts/lint.sh <your-file.rs> and audits against a checklist banning unwrap() outside tests and keeping modules under 500 lines. Automated verification relies on having bash available to execute the bundled lint script.
What it helps with
- design type-safe structs and enums that make invalid states unrepresentable
- enforce mandatory error context on every ? operator using anyhow or thiserror
- prevent async executor stalls by dropping mutex guards before .await
- clean up unused wrappers and unnecessary .clone() calls across modules
Example prompts for the agent
- Implement a background task worker in Rust following rust-implement rules
- Design types and error enums for a new CLI command using thiserror
- Review and simplify src/storage.rs against the verification checklist
How to install rust-implement
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rust-implement -a claude-code2Manually: put the files in place
~/.claude/skills/rust-implement/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/rust-implement/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rust-implement -a codex2Manually: put the files in place
.agents/skills/rust-implement/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rust-implement -a cursor2Manually: put the files in place
.cursor/skills/rust-implement/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/rust-implement2Manually: put the files in place
.github/skills/rust-implement/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rust-implement -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/rust-implementManually: put the files in place
.devin/skills/rust-implement/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill rust-implement -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about rust-implement
How to install rust-implement in Claude Code?
Run npx skills add pproenca/dot-skills --skill rust-implement -a claude-code. Alternatively, place the file directly at ~/.claude/skills/rust-implement/SKILL.md.
What does rust-implement do?
It structures Rust coding into four phases: signatures and types first, function bodies with explicit error contexts second, removal of redundant code third, and verification via a bundled lint script fourth.
When does rust-implement use anyhow versus thiserror?
The skill mandates anyhow::Result with .context() for application code and binaries, while library crates must provide structured error enums implemented with thiserror.
Source text
SKILL.md · MIT
---
name: rust-implement
description: "Write production-grade Rust code using a multi-pass approach. Design types first, then implement, then simplify, then verify with automated lint. Use this skill whenever writing new Rust functions, structs, modules, or features. Triggers on Rust implementation, new Rust code, Rust functions, Rust modules, error handling in Rust, async Rust, or type design in Rust."
---
# Rust Implementation Discipline
Write code in passes. Experts don't produce perfect code in one shot -- they design, implement, review, and simplify. Follow this process for every module you write.
---
## Pass 1: Design Types and Signatures
Before writing any implementation, write ONLY the type definitions and function signatures. No bodies. No logic.
Ask yourself these questions before moving on:
- Can any enum state represent an invalid combination? If yes, restructure so invalid states are unrepresentable.
- Are all parameters self-documenting? Replace `bool` params with enums (Transformation 2).
- Does every struct that will be serialized or compared use `BTreeMap`, not `HashMap` (Transformation 3)?
- Do config structs derive `Default` (Transformation 6)?
- Would a caller confuse the order of String parameters? Use newtypes.
- Does any struct have 2+ `Option<T>` fields where only one combination is valid at a time? Convert to an enum (Transformation 8).
- Does any function take 4+ parameters? Replace with an args struct (Transformation 9).
**Do not proceed to Pass 2 until the types are right. Types are the architecture.**
---
## Pass 2: Implement
Fill in the function bodies. As you write each function, apply these rules:
- Every `?` gets `.context("failed to [verb] [noun]")` -- no exceptions (Transformation 1).
- For library code: use `thiserror` for error enums. For application code: use `anyhow`.
- Use `Cow<str>` when a function sometimes borrows and sometimes allocates (Transformation 7).
- Return named structs, not tuples, from any function with 2+ return values (Transformation 5).
- Exhaustive match arms -- no `_ =>` wildcards (Transformation 4).
### Thread-Through Plumbing
When adding a new field that needs to reach execution sites, trace the full path and explicitly name every intermediate layer before writing code. For each hop, state the module and struct/function that carries the value. If you skip a layer, the field silently disappears at runtime.
### Drop/Teardown Precision
- Drop lock guards before any `.await` -- a held `MutexGuard` across an await blocks the executor.
- Close stdin explicitly in `Drop` impls. Brief wait, then fallback kill.
- Use `kill_on_drop(true)` for child processes that must not outlive their parent.
- Order cleanup deterministically: clear listeners -> drain tasks -> drop resources.
### Defensive Serialization
- `BEGIN IMMEDIATE` not `BEGIN` for SQLite write transactions (prevents `SQLITE_BUSY_SNAPSHOT`).
- Serialize lock acquisition rather than adding retries.
- `ON CONFLICT DO NOTHING` over read-then-write for idempotent inserts.
### Orphan Event Handling
When events arrive for entities that no longer exist (dead agents, closed threads), handle explicitly. Never silently drop -- log a warning and clean up stale state. Panicking on an orphan event is always wrong.
### Ownership Decision Tree
Walk this tree in order when you need shared access to data:
1. **Can you pass a reference?** Use `&T`. Zero cost, zero complexity.
2. **Might it be owned or borrowed?** Use `Cow<'_, str>`. Zero-cost when borrowed.
3. **Multiple owners across sync boundaries?** Use `Arc<T>`. Prefer `Arc::clone(&x)` over `x.clone()`.
4. **Multiple owners AND mutability?** Use `Arc<Mutex<T>>` or `Arc<RwLock<T>>`. Choose `RwLock` when reads vastly outnumber writes.
5. **Fire-and-forget spawn?** Use `move` closure with owned data.
Every `.clone()` is a decision point. Ask: "Is this clone necessary, or can I restructure to borrow?"
### Error Philosophy
| Context | Tool | Why |
|---------|------|-----|
| Application code (main, CLI, tests) | `anyhow::Result` + `.context()` | Rich error chains, no boilerplate |
| Library code (crates consumed by others) | `thiserror` enums | Typed, matchable, callers can branch on variants |
Error enum design: user-facing messages tell the user what to do, not what went wrong internally. `Box<T>` large payloads. Classify every variant explicitly in `is_retryable()` -- no wildcards.
### Async Decisions
**When to `Box::pin`:** When thin async wrappers inline large callee futures into their state machine, causing stack pressure. Wrap the inner call: `Box::pin(self.inner_method(args)).await`.
| Need | Channel | Why |
|------|---------|-----|
| One response back | `oneshot` | Exactly one value, then done |
| Stream of events | `mpsc` | Multiple producers, single consumer |
| Latest value only | `watch` | Receivers always see the most recent value |
| Broadcast to all | `broadcast` | Every receiver gets every message |
Shutdown: use `CancellationToken` for hierarchical shutdown. Never rely on `Drop` for ordered async cleanup. Never hold a `MutexGuard` across an `.await` point.
---
## Pass 3: Simplify
Review your code as if you're trying to REMOVE things, not add them.
Three diagnostic questions:
1. **Is any parameter just forwarded through a call chain?** Remove it, use ambient access.
2. **Is any field or function unused?** Delete it.
3. **Is any abstraction unjustified?** (single-use helper, wrapper that adds nothing) Inline it.
**"Rewrite, don't rewire" principle:** When the bug is in a function's internal logic, rewrite the body with explicit checks. Don't delegate to an existing API that happens to produce the correct result for now -- the explicit version is more auditable and survives upstream changes.
If you added more code than the task strictly requires, something is wrong. Cut it.
---
## Pass 4: Verify
Run the bundled lint script on your code:
```bash
bash ${SKILL_DIR}/scripts/lint.sh <your-file.rs>
```
Fix every ERROR. Review every WARNING. Then do the manual checklist:
```
[ ] Every ? has .context("failed to [verb] [noun]")
[ ] No unwrap() outside #[cfg(test)]
[ ] BTreeMap where output is serialized or compared
[ ] No bool parameters -- use enums
[ ] Match arms exhaustive -- no _ => wildcards
[ ] Config structs derive Default
[ ] No single-use helper functions -- inline if called once
[ ] Module under 500 lines (excluding tests)
[ ] No unnecessary .clone() -- prefer borrowing
[ ] Return structs, not tuples, for multi-value returns
[ ] Cow<str> where allocation is conditional
[ ] serde attrs present: rename_all, default, deny_unknown_fields as needed
[ ] No struct with 2+ Option<T> fields that should be an enum
[ ] No function with 4+ parameters (use args struct)
[ ] Lock guards dropped before any .await
[ ] Events for dead/missing entities handled explicitly
```
**Fix every violation before presenting the code.**
---
## Quick Reference: The 9 Transformations
Each transformation shows the exact delta between first-draft and production-grade.
### 1. `.context()` on Every `?` Operator
BEFORE:
```rust
let content = std::fs::read_to_string(path)?;
let config: Config = toml::from_str(&content)?;
```
AFTER:
```rust
let content = std::fs::read_to_string(path)
.context("failed to read config file")?;
let config: Config = toml::from_str(&content)
.context("failed to parse TOML config")?;
```
Pattern: `"failed to [verb] [noun]"`. The upstream error describes itself -- your job is to name the operation that broke.
### 2. Enums Over Booleans
BEFORE:
```rust
fn create_sandbox(network: bool, writable: bool) -> Sandbox {
```
AFTER:
```rust
fn create_sandbox(network: NetworkMode, access: AccessLevel) -> Sandbox {
```
`foo(true, false)` is meaningless. Replace with enums so callsites read `NetworkMode::Restricted, AccessLevel::ReadOnly`. When you cannot change the API, add `/*param_name*/` comments before opaque literals.
### 3. BTreeMap for Serialized or Compared Data
BEFORE: `HashMap<String, Rule>` -- AFTER: `BTreeMap<String, Rule>`
HashMap iteration order is random -- diffs become noisy, snapshot tests flake. Use BTreeMap whenever data is serialized, compared in tests, or shown to users.
### 4. Exhaustive Match Without Wildcards
BEFORE:
```rust
match decision {
PolicyDecision::Allow => true,
_ => false,
}
```
AFTER:
```rust
match decision {
PolicyDecision::Allow => true,
PolicyDecision::Block { .. } => false,
PolicyDecision::Rewrite { .. } => false,
PolicyDecision::Ask { .. } => false,
}
```
When a new variant is added, the compiler flags every match that needs updating. Wildcards hide this.
### 5. Return Structs Over Tuples
BEFORE: `fn build_command() -> (Vec<String>, Vec<OwnedFd>)` -- caller writes `result.0`
AFTER: `fn build_command() -> CommandOutput` -- caller writes `output.args`, `output.preserved_fds`
Named fields are self-documenting. Define a struct for any function returning 2+ values.
### 6. `Default` Derive on Config Structs
```rust
#[derive(Default)]
pub struct ServerConfig {
pub timeout_secs: u64,
pub max_retries: u32,
pub bind_addr: String,
}
let config = ServerConfig { timeout_secs: 30, ..Default::default() };
```
Derive `Default` so callers override only what matters. For non-zero defaults, implement `Default` manually.
### 7. `Cow<str>` for Conditional Ownership
BEFORE:
```rust
fn normalize_path(input: &str) -> String {
if needs_normalization(input) { input.replace('\\', "/") }
else { input.to_string() } // allocates even when unchanged
}
```
AFTER:
```rust
fn normalize_path(input: &str) -> Cow<'_, str> {
if needs_normalization(input) { Cow::Owned(input.replace('\\', "/")) }
else { Cow::Borrowed(input) } // zero-cost when unchanged
}
```
`Cow<str>` avoids the unconditional allocation when only some paths need to allocate.
### 8. Enum-as-Disjoint-Union
BEFORE:
```rust
struct Permissions {
profile_name: Option<String>, // only for named profiles
sandbox_policy: Option<SandboxPolicy>, // only for legacy
file_paths: Option<Vec<PathBuf>>, // only when sandbox_policy is set
}
```
AFTER:
```rust
enum Permissions {
Named { profile_name: String },
Legacy { sandbox_policy: SandboxPolicy, file_paths: Vec<PathBuf> },
}
```
When a struct has `Option<T>` fields valid only in certain combinations, it permits invalid states at the type level. Convert to an enum where each variant carries only its relevant data. Diagnostic: if you see 2+ `Option<T>` fields with `is_some()`/`is_none()` guards, it should be an enum.
### 9. Struct-for-Long-Parameter-Lists
BEFORE:
```rust
fn spawn_process(
cmd: &str,
args: &[String],
env: &BTreeMap<String, String>,
cwd: &Path,
stdin_policy: StdinPolicy,
sandbox: SandboxPolicy,
timeout: Duration,
) -> Result<Child> {
```
AFTER:
```rust
struct SpawnArgs<'a> {
cmd: &'a str,
args: &'a [String],
env: &'a BTreeMap<String, String>,
cwd: &'a Path,
stdin_policy: StdinPolicy,
sandbox: SandboxPolicy,
timeout: Duration,
}
fn spawn_process(args: &SpawnArgs<'_>) -> Result<Child> {
```
At 4+ parameters, callsites become hard to read and easy to misorder. An args struct names each field at the callsite and makes future parameter additions non-breaking.
© pproenca · MIT · pproenca/dot-skills