BeautifulRust v1.3.0 发布：新增 rust-port 技能，支持将多语言代码移植为 Rust

Official release notes (https://github.com/morganlinton/BeautifulRust/releases/tag/v1.3.0) BeautifulRust now ports existing code to Rust, and the repo is ready for contributors. **New: the `rust-port` skill** Ask your agent to port a module ("port parser.c to Rust", "rewrite this Python service in Rust") and it: - reads the original and its tests, and ports the tests first, so the port is proven against the original's own behavior - designs a Rust API instead of transliterating: `NULL` and `None` become `Option`, error codes and exceptions become an error enum, out-parameters become return values, flag ints and magic strings become typed values, and dict insertion order becomes an ordered collection instead of a `HashMap` that would silently reorder output - keeps the port proportionate: it uses Rust's standard library rather than reimplementing the source language's string and number handling, and documents exotic differences instead of coding around them - verifies with `cargo test` and clippy, and writes a `PORTING.md` mapping the old API and tests to the new ones, with every deliberate difference listed It covers C, C++, Python, Go, JavaScript, and TypeScript. **How it tested** Ported a C config parser and a Python task scheduler, each with its original test suite, with and without the skill: | | With skill | Without | |---|---|---| | Checks passed | 22 of 22 | 19 of 22 | | Python port size vs. original | 3.1x | 5.8x | | Reimplemented Python's string and number semantics | No | Yes | Without the skill, the model already ports correctly: every port built, passed its tests, and was clippy-clean, and both C ports matched the original byte for byte on 20 tricky inputs. The skill's contribution is restraint. Without it, the Python port hand-copied `splitlines`, `strip`, `int()`, and `repr()` and grew a dozen extra public methods. One run per configuration. **New: contributor guidelines** [`CONTRIBUTING.md`](https://github.com/morganlinton/BeautifulRust/blob/main/CONTRIBUTING.md) centers on one rule: every rule needs a published source. There are issue templates for proposing a rule and for reporting a review false positive, which become new eval cases. Full details are in the [changelog](https://github.com/morganlinton/BeautifulRust/blob/main/CHANGELOG.md). Update a Claude Code install with `claude plugin update beautiful-rust`; for other agents, re-run your install command. Repository README (current repository documentation, not release changes) # Beautiful Rust Three standard [Agent Skills](https://agentskills.io) and a lints config that teach coding agents to write, review, port, and enforce idiomatic Rust: - **`rust-best-practices`** loads whenever an agent writes or changes Rust, and steers it toward idiomatic, robust, maintainable code. - **`rust-review`** reviews existing Rust code, a file, a crate, or a diff, and writes a prioritized report where every finding cites the rule it breaks and shows the fix. - **`rust-port`** ports C, C++, Python, Go, or JavaScript to idiomatic Rust with the same behavior, porting the original tests first so you can prove the two match. - **`lints/`** is a drop-in clippy configuration that enforces the machine-checkable rules in CI. They work with Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, and any other agent that reads the Agent Skills format. Every code example in the skills compiles on stable Rust, and every lint in the config was checked against current clippy. The guidance is distilled from five sources, with a condensed digest of each bundled in the skill so the agent can consult the original reasoning when it needs to: - [Google Rust Style Guide](https://google.github.io/styleguide/rustguide.html) - [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) (official rust-lang checklist) - [Effective Rust](https://www.lurklurk.org/effective-rust/) by David Drysdale - [Rust Design Patterns](https://rust-unofficial.github.io/patterns/) (idioms, patterns, anti-patterns) - [Microsoft Pragmatic Rust Guidelines](https://microsoft.github.io/rust-guidelines/) Where the sources disagree, the skill picks a side and says why. ## What it changes Asked for a small semver-parsing library, an agent without the skill produced working code with public fields, no `# Errors` docs, and `unwrap()` in its doc examples. With the skill, the same agent kept the fields private, documented failure modes, and wrote doc examples users can copy safely. Condensed from those two runs: ```rust // Without the skill /// A semantic version. The fields are public for convenience. pub struct Version { pub major: u64, pub minor: u64, pub patch: u64, pub pre: Vec, pub build: Vec, } impl Version { /// Parses a version string. /// /// ``` /// let v = Version::parse("1.2.3").unwrap(); /// ``` pub fn parse(s: &str) -> Result { /* ... */ } } ``` ```rust // With the skill /// A semantic version. Equality, hashing, and ordering ignore build metadata. pub struct Version { major: u64, minor: u64, patch: u64, pre: Vec, build: Vec, } impl Version { /// Parses a version string according to SemVer 2.0.0. /// /// # Errors /// /// Returns [`ParseVersionError`] if the string is empty, a numeric part has a /// leading zero or overflows `u64`, or an identifier contains invalid characters. /// /// ``` /// # use semver_lite::Version; /// # fn main() -> Result { /// let v = Version::parse("1.2.3-beta.1")?; /// assert_eq!(v.major(), 1); /// # Ok(()) /// # } /// ``` pub fn parse(s: &str) -> Result { /* ... */ } /// Returns the major version number. pub fn major(&self) -> u64 { self.major } } ``` Across three test tasks (a library, a CLI, and refactoring a messy module), the skill passed 29 of 30 checks against 24 of 30 without it. See [Testing the skills](#testing-the-skills). ## Install Each skill is a folder under `skills/`: `rust-best-practices/`, `rust-review/`, and `rust-port/`. Every option below puts those folders where your agent looks for skills. Install all three; the review and port skills lean on the best-practices skill for style. ### Any agent, one command The [`skills`](https://github.com/vercel-labs/skills) installer supports most agents (Node 22.20 or later): ```bash npx skills add morganlinton/BeautifulRust ``` Add `-g` to install for your user instead of the current project, or `-a ` to pick an agent, such as `-a codex` or `-a cursor`. ### Claude Code Install it as a plugin so updates arrive with one command: ```bash claude plugin install beautiful-rust --marketplace morganlinton/BeautifulRust ``` Inside a session, the same thing is: ``` /plugin marketplace add morganlinton/BeautifulRust /plugin install beautiful-rust@beautiful-rust ``` This installs all three skills. They appear as `/beautiful-rust:rust-best-practices`, `/beautiful-rust:rust-review`, and `/beautiful-rust:rust-port`, though you rarely need to call them, since they trigger on their own. To try it for one session without installing, clone the repo and run `claude --plugin-dir ./BeautifulRust`. ### GitHub Copilot With GitHub CLI 2.90 or later: ```bash gh skill install morganlinton/BeautifulRust rust-best-practices gh skill install morganlinton/BeautifulRust rust-review gh skill install morganlinton/BeautifulRust rust-port ``` This installs into the current project by default. Add `--scope user` to install for your user, or `--agent ` to install for a different agent. ### Gemini CLI ```bash gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-best-practices gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-review gemini skills install https://github.com/morganlinton/BeautifulRust --path skills/rust-port ``` ### OpenAI Codex, Cursor, or anything else: copy the folder Clone the repo and copy the three skill folders into your agent's skills directory. Most agents now read the shared `.agents/skills/` location: ```bash git clone https://github.com/morganlinton/BeautifulRust mkdir -p ~/.agents/skills cp -R BeautifulRust/skills/rust-* ~/.agents/skills/ ``` | Agent | User directory | Project directory | |---|---|---| | Claude Code | `~/.claude/skills/` | `.claude/skills/` | | OpenAI Codex | `~/.agents/skills/` | `.agents/skills/` | | GitHub Copilot | `~/.copilot/skills/` or `~/.agents/skills/` | `.github/skills/` or `.agents/skills/` | | Cursor | `~/.cursor/skills/` or `~/.agents/skills/` | `.cursor/skills/` or `.agents/skills/` | | Gemini CLI | `~/.gemini/skills/` or `~/.agents/skills/` | `.gemini/skills/` or `.agents/skills/` | Claude Code does not read `.agents/skills/`, so use its own directory or the plugin. Restart the agent if the skill doesn't show up right away. ### claude.ai claude.ai takes one zip per skill, with the skill folder as the zip root: ```bash cd skills zip -r ../rust-best-practices.zip rust-best-practices -x '*.DS_Store' -x '*/evals/*' zip -r ../rust-review.zip rust-review -x '*.DS_Store' -x '*/evals/*' zip -r ../rust-port.zip rust-port -x '*.DS_Store' -x '*/evals/*' ``` Upload each under **Customize > Skills**. Code execution must be enabled first. ## Reviewing existing code Ask your agent to review a file, crate, or diff, for example "review src/parser.rs" or "what would you change in this PR". The `rust-review` skill runs `cargo fmt`, `clippy`, and the tests when a toolchain is available, then writes a report with three tiers: must fix, should fix, and consider. Every finding gives a `file:line` location, the rule it breaks with its source (an API Guidelines code such as `C-GETTER`, an Effective Rust item, a Microsoft guideline, or a clippy lint), and the smallest code change that fixes it. Each report ends with what the code already does well. [`examples/review-inventory.md`](examples/review-inventory.md) is a real review the skill produced for the deliberately messy module in the eval cases. ## Porting code to Rust Ask your agent to port a module, for example "port parser.c to Rust" or "rewrite this Python service in Rust". The `rust-port` skill reads the original and its tests, ports the tests first, designs a Rust API instead of transliterating the original, and verifies with `cargo test` and `clippy`. It maps each language's habits to their Rust equivalents: `NULL` and `None` to `Option`, error codes and exceptions to an error enum, out-parameters to return values, flag ints and magic strings to typed enums and options, and dict insertion order to an ordered collection instead of a `HashMap` that would silently reorder output. Each port comes with a `PORTING.md` that maps the old API and tests to the new ones and lists every deliberate difference. ## Enforcing the rules with clippy The skills teach the rules; the lints keep them from slipping back in. Copy [`lints/clippy.toml`](lints/clippy.toml) next to your `Cargo.toml` and paste the `[lints]` block from [`lints/lints.toml`](lints/lints.toml) into it, then run: ```bash cargo clippy --all-targets --all-features -- -D warnings ``` It flags `unwrap()` outside tests, `unsafe` blocks without a `// SAFETY:` comment, `#[allow]` without a reason, any `bool` function parameter, silent lossy `as` casts, missing `# Errors` and `# Panics` docs, and leftover `dbg!` and `todo!`. Lints marked `[lib]` in the file are for libraries, and applications can drop them. ## What the writing skill covers `skills/rust-best-practices/SKILL.md` is about 500 lines, organized so an agent can scan it while coding: 1. Mindset: Rust-shaped code, invalid states unrepresentable, application vs library 2. Pre-handback checklist: fmt, clippy with `-D warnings`, test, doc; lint policy 3. Ownership and borrowing: what to do instead of cloning for the borrow checker 4. Types and API design: naming, newtypes, common traits, builders, visibility, generics vs `dyn` 5. Errors and panics: `Option` vs `Result` vs panic, library vs application error types 6. Everyday idioms: iterators, combinators, `format!`, imports, drop guards 7. Concurrency and async: `Send` assertions, lock discipline, `async fn`, yield points 8. Unsafe and FFI: when it's allowed, `SAFETY:` comments, soundness, bindgen 9. Crates, modules, dependencies: workspace layout, features, semver 10. Documentation and comments 11. Tests 12. Performance, in order 13. Final checklist `skills/rust-best-practices/references/` holds one digest per source for deeper lookups. ## Layout ``` BeautifulRust/ ├── .claude-plugin/ │ ├── plugin.json plugin manifest │ └── marketplace.json lets this repo act as its own marketplace ├── skills/ │ ├── rust-best-practices/ writing skill │ │ ├── SKILL.md │ │ ├── references/ one digest per source │ │ └── evals/ │ ├── rust-review/ review skill │ │ ├── SKILL.md │ │ └── evals/ │ └── rust-port/ porting skill │ ├── SKILL.md │ └── evals/ a C module and a Python module to port ├── lints/ │ ├── lints.toml [lints] block for Cargo.toml │ └── clippy.toml clippy thresholds ├── examples/ │ └── review-inventory.md a real review report ├── CHANGELOG.md ├── CONTRIBUTING.md └── README.md ``` ## Testing the skills `skills/rust-best-practices/evals/` holds three test cases in the layout `claude plugin eval` reads: a library API design task, an application CLI task, and a refactor-this-module task with an input file. Each case has the prompt, a description of a good result, and one assertion per file under `graders/`. Run them with and without the skill from the skill directory: ```bash claude plugin eval . --allow-tools Write,Edit,Bash --scaffold ``` `skills/rust-review/evals/` holds a review case for the same messy module, and `skills/rust-port/evals/` holds a C module and a Python module to port, each with its original test suite. Run them the same way from each skill's directory. These are real model runs and are billed. In the last comparison the writing skill passed 29 of 30 assertions against 24 of 30 without it, at roughly a third more tokens per task. The review skill passed 11 of 12 against 7 of 12, and the porting skill 22 of 22 against 19 of 22. ## Updating Edit the skill, bump `version` in `.claude-plugin/plugin.json`, commit, and push. Claude Code plugin users pick up the new version with: ```bash claude plugin update beautiful-rust ``` Anyone who copied the folder or used an installer re-runs the install command. Record each release in [CHANGELOG.md](CHANGELOG.md). Validate before pushing: ```bash claude plugin validate . ``` ## Contributing Issues and pull requests are welcome. Every rule needs a published source; see [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose a rule, report a review false positive, or add an eval case. ## Sources and attribution The guidance in this skill is a synthesis. The five digests in `skills/rust-best-practices/references/` are paraphrased summaries written for this project; they restate each source's advice in condensed form and link back to the original. Read the originals for the full reasoning. | Source | Author | License | |---|---|---| | [Google Rust Style Guide](https://google.github.io/styleguide/rustguide.html) | Google | CC BY 3.0 | | [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) | The Rust Project | MIT or Apache-2.0 | | [Effective Rust](https://www.lurklurk.org/effective-rust/) | David Drysdale, published by O'Reilly | CC BY-NC-ND 4.0 (online edition) | | [Rust Design Patterns](https://rust-unofficial.github.io/patterns/) | rust-unofficial contributors | MPL-2.0 | | [Pragmatic Rust Guidelines](https://microsoft.github.io/rust-guidelines/) | Microsoft | MIT | The skill text, the digests, the banner, and the generator script in this repository are MIT licensed (see [LICENSE](LICENSE)). The crab is a crab, not the Rust mascot. ## License MIT. See [LICENSE](LICENSE).