rust-craft
Craft production Rust the way the top toolchain teams do. Use when writing, reviewing, or restructuring Rust — workspace layout, Cargo manifests, lints, and profiles; type, trait, and error API design; performance, allocation, and profiling work; async and concurrency; CLI construction; test, snapshot, and benchmark suites; crate selection; release, semver, MSRV, and feature flags.
- License 许可
- MIT
- 所属仓库
- hadronomy/skills
- 最近更新
- 2026-10-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- rust-craft
- description
- Craft production Rust the way the top toolchain teams do. Use when writing, reviewing, or restructuring Rust — workspace layout, Cargo manifests, lints, and profiles; type, trait, and error API design; performance, allocation, and profiling work; async and concurrency; CLI construction; test, snapshot, and benchmark suites; crate selection; release, semver, MSRV, and feature flags.
02 资源文件 12
- 参考文档agents/openai.yaml124 B
- 参考文档references/api-design.md9.9 KB
- 参考文档references/async.md5.8 KB
- 参考文档references/cli.md9.1 KB
- 参考文档references/crates.md7.4 KB
- 参考文档references/errors.md5.5 KB
- 参考文档references/performance.md7.5 KB
- 参考文档references/shipping.md4.8 KB
- 参考文档references/sources.md3.2 KB
- 参考文档references/testing.md5.7 KB
- 参考文档references/workspace.md9.8 KB
- 脚本scripts/inspect_rust_project.sh2.7 KB
03 SKILL.md 正文
Rust Craft
Write Rust that is correct before it is fast, measured before it is called fast, and shaped so that every call path is obvious to the next reader.
The rules here are taken from the codebases that set the bar: oxc,
ruff/ty, uv, mise, rust-analyzer, and the official API guidelines.
Read references/sources.md when you need to check why a
rule exists.
This is a routed skill. Always apply the core contract. Read only the reference layers the task needs.
Core contract
- The checkout is the authority. Before you write a line, read
Cargo.toml,rust-toolchain.toml,clippy.toml,rustfmt.toml,AGENTS.md, and two files next to the one you will change. Repo convention beats every default in this skill. - Encode constraints in types. Keep
panic!,unreachable!,unwrap,expect, andtodo!out of library and binary code. Useif let, let chains,let ... else, and newtypes that cannot hold a bad value. Verbose code that removes a panic is the better trade. - Parse at the edge. Convert untrusted input into a validated type once, at the boundary. Past that point, only the validated type exists.
- Never silence a lint to make the build pass. Refactor instead. If a lint
must go, write
#[expect(lint, reason = "...")]on the smallest possible scope. Do not use#[allow], a workspaceallow, or-Aon the command line. - Every
unsafeblock carries a// SAFETY:comment that names the invariant it depends on. Do not reach forunsafeto gain speed you have not measured. - Imports go at the top of the file. No
useinside a function body. Use a fully qualified path only for a name you write once. - Write full names.
version, notver.requires_python, notrp. - Comments state invariants and reasons. They never narrate the code and never record what the code used to do.
- Measure before you optimize, and again after. A speed claim without a benchmark number is not a claim.
- Run the tests. If you did not run them, the code does not work.
- Keep visibility narrow.
pub(crate)by default. Make an itempubwhen another crate needs it and that is the cleaner design. - Features are additive.
--no-default-featuresmust compile, and turning a feature on must never remove an API.
Route the task
| Task | Read first | Also read when relevant |
|---|---|---|
| Start a project, split crates, tune Cargo manifests, lints, profiles, or build speed | workspace.md | shipping.md |
| Design a type, trait, module interface, or public API | api-design.md | errors.md, the codebase-design skill for depth vocabulary |
| Handle failure, model error types, or render diagnostics | errors.md | api-design.md |
| Make code faster, cut allocations, shrink types, or profile | performance.md | testing.md for benchmark harnesses |
| Write async code, concurrency, or shared state | async.md | performance.md |
| Build or extend a command-line binary | cli.md | errors.md, testing.md |
| Write tests, snapshots, property tests, or benchmarks | testing.md | performance.md |
| Choose a dependency | crates.md | shipping.md |
| Publish, version, set MSRV, or gate a feature | shipping.md | api-design.md |
| Check why a rule here exists | sources.md | The upstream repo itself |
Workflow
1. Orient
Read the manifests and the neighbouring code. Record four things before you plan: the edition and MSRV, the lint configuration, the test command this repo actually uses, and the crate that owns the seam you are about to touch.
Run the inspector:
scripts/inspect_rust_project.sh /path/to/project
Done when you can name the crate you will edit, the command that tests it, and the lints that will judge it.
2. Design before you type
State the interface first: the types that cross the seam, the error type, and
the invariant each new type protects. Prefer making an illegal state
unrepresentable over writing a check. Reach for the codebase-design skill when
the question is where the seam belongs.
Done when every new public item has a named invariant and a reason to exist.
3. Build
Follow the reference layer for the task. Match the surrounding code's idiom, naming, and comment density. Reuse what the workspace already has before you add a dependency or write a helper.
Done when the change compiles with zero warnings and no new suppression.
4. Verify
Run the repo's own commands when it has them — a justfile, mise.toml,
xtask, or Makefile target names the real gate. Otherwise:
cargo fmt --all
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo nextest run --workspace
cargo test --workspace --doc
Review every snapshot the run regenerated. Never hand-edit a snapshot file or an inline snapshot body.
Done when every command above passes, every regenerated snapshot has been read, and you can state which paths you did not exercise.
Report honestly
Say which commands you ran and what they printed. Name every path you could not
verify — a platform you cannot build for, a test you skipped, a benchmark you
did not run. A clean cargo check does not prove behaviour.
04 同仓库更多 Skills
windows-mcp
Driving the Windows desktop on `workstation` through the windows MCP server. Use before any `mcp__windows__` tool, when a desktop call blocks or returns "Desktop busy", when Snapshot or Screenshot come back empty, or when this agent has no desktop tools and the task needs them.
typst-author
Author idiomatic, compilable Typst documents. Use when creating or editing Typst (.typ) files, when a task involves Typst syntax, packages, templates, or bibliographies, or when a Typst build fails and the error needs a fix.
setup-hadronomy
暂无简介
pr-craft
Write pull requests a reviewer can act on. Use when opening, rewriting, or reviewing the body of a pull request — title and description, the problem and approach, call-stack diffs, before-and-after screenshots, verification steps, risks, a review guide, and the tools that produce each part.
effect-craft
Craft Effect TypeScript APIs with the discipline of the Effect and opencode codebases. Use when modeling data with Schema, building services with Context and Layer, naming operations with Effect.fn, exposing modules through barrels, designing hooks or HTTP surfaces, or writing JSDoc with runnable examples — new code, refactors, and API reviews.
docs-craft
Documentation discipline for code comments, API docs, and docs pages. Use when writing or reviewing doc comments, JSDoc or rustdoc, README sections, or framework docs pages — or when comments and docs read as filler and need cutting.