{"id":"a9311d15-b2ee-4526-b7f4-e12c237d9b08","shortId":"xWuwkv","kind":"skill","title":"rust","tagline":"Use when editing Rust files, .rs, Cargo.toml, Cargo.lock, workspaces, async code, error handling, PyO3, maturin, napi-rs, C ABI, platform support, tests, or performance-critical Rust paths.","description":"# Rust (Systems & Performance)\n\nPatterns for multi-crate Rust workspaces targeting cross-platform, high-performance systems with polyglot extension surfaces. Covers workspace layout, async runtimes, platform abstraction, PyO3/maturin Python bindings, napi-rs Node/Bun bindings, C ABI/FFI, error handling, and benchmarking.\n\n## Code Style\n\n- Edition 2021, resolver 2.\n- Workspace-level lint config in root `Cargo.toml`:\n\n```toml\n[workspace.lints.rust]\nunexpected_cfgs = { level = \"allow\", check-cfg = ['cfg(Py_GIL_DISABLED)'] }\n\n[workspace.lints.clippy]\ntoo_many_arguments = \"allow\"\ntype_complexity = \"allow\"\n```\n\n- Crates inherit lints: `[lints] workspace = true`.\n- Format: `cargo fmt`. Lint: `cargo clippy -- -D warnings`.\n- Use `tracing` (not `log`) for structured instrumentation.\n- Document public APIs with `///` doc comments.\n- Prefer `Arc<T>` over `Rc<T>` in async contexts.\n\n## Quick Reference\n\n### Workspace Setup\n\n```text\nproject/\n├── Cargo.toml              # [workspace] root\n├── crates/\n│   ├── core/               # Pure logic, no FFI deps\n│   ├── http/               # Runtime + networking (binary)\n│   ├── py/                 # PyO3 bindings (cdylib)\n│   └── node/               # napi-rs bindings\n└── rust-toolchain.toml\n```\n\nCore crate has zero FFI dependencies. Binding crates wrap it. Pin shared dependencies in workspace root with `[workspace.dependencies]`; crates reference with `{ workspace = true }`.\n\n### Error Handling Pattern (thiserror)\n\n```rust\nuse thiserror::Error;\n\n#[derive(Debug, Error)]\npub enum AppError {\n    #[error(\"IO error: {0}\")]\n    Io(#[from] std::io::Error),\n    #[error(\"parse error in {path}: {message}\")]\n    Parse { path: String, message: String },\n    #[error(\"not found: {0}\")]\n    NotFound(String),\n}\n\npub type Result<T> = std::result::Result<T, AppError>;\n```\n\n### Async Tokio Essentials\n\n- Use `#[tokio::main]` for binaries; pass runtime handle to libraries.\n- Select tokio features per crate -- only the server crate needs `\"full\"`.\n- Use `Arc<T>` for shared state across tasks, never `Rc<T>`.\n- Use `tokio::sync::Mutex` only when holding the lock across `.await`; otherwise use `parking_lot::Mutex`.\n\n### PyO3 Pattern\n\n```rust\nuse pyo3::prelude::*;\n\n#[pyclass(frozen)]  // frozen = immutable, safe across threads\n#[derive(Clone, Debug)]\npub struct Config {\n    #[pyo3(get)]\n    pub name: String,\n    #[pyo3(get)]\n    pub max_retries: u32,\n}\n\n#[pymodule]\n#[pyo3(name = \"_native\")]\npub fn pymodule_init(m: &Bound<'_, PyModule>) -> PyResult<()> {\n    m.add_class::<Config>()?;\n    Ok(())\n}\n```\n\n<workflow>\n\n## Workflow\n\n### Step 1: Workspace Layout\n\nCreate a workspace with `resolver = \"2\"`. Separate pure-logic core from binding crates (py, node, c_abi). Pin all shared dependencies in `[workspace.dependencies]`.\n\n### Step 2: Error Types\n\nDefine per-crate error enums with `thiserror`. Use `#[from]` for automatic conversion. Add `PyErr` conversion (`From<AppError> for PyErr`) in binding crates.\n\n### Step 3: Core Logic\n\nWrite business logic in the core crate with no FFI dependencies. Use `async` for I/O-bound work. Test with `cargo test` and benchmark hot paths with `criterion`.\n\n### Step 4: Bindings\n\nWrap core types/functions in binding crates. For PyO3: use `#[pyclass(frozen)]` for immutable data, `future_into_py` for async. For napi-rs: use `#[napi]` macros.\n\n### Step 5: Validate\n\nRun `cargo clippy -- -D warnings`, `cargo fmt --check`, and `cargo test --workspace`. For PyO3: `maturin develop` and run Python tests.\n\n</workflow>\n\n<guardrails>\n\n## Guardrails\n\n- **Prefer `Arc` over `Rc` in async code** -- `Rc` is not `Send` and will fail to compile in tokio tasks. Use `Arc<T>` for shared ownership across tasks.\n- **Use `thiserror` for library error types** -- provides `#[derive(Error)]` with `Display` and `From` impls. Reserve `anyhow` for binaries/scripts only.\n- **Workspace for multi-crate projects** -- centralize dependency versions, lint config, and release profiles. Never duplicate version pins across crates.\n- **Core crate has zero FFI deps** -- keep PyO3, napi-rs, and libc out of core. Binding crates depend on core and add FFI.\n- **`#[pyclass(frozen)]` for immutable data** -- enables safe sharing across Python threads without per-access locking.\n- **`tracing` over `log`** -- structured instrumentation with spans, levels, and subscriber flexibility.\n- **Pin `rust-toolchain.toml`** -- ensures consistent compiler version across CI and local builds.\n\n</guardrails>\n\n<validation>\n\n### Validation Checkpoint\n\nBefore delivering Rust code, verify:\n\n- [ ] Workspace uses `resolver = \"2\"` and `[workspace.dependencies]`\n- [ ] Error types use `thiserror` with `#[from]` conversions\n- [ ] Async code uses `Arc<T>` (not `Rc<T>`) for shared state\n- [ ] Core crate has no FFI dependencies (PyO3, napi-rs, libc)\n- [ ] `cargo clippy -- -D warnings` passes\n- [ ] Public APIs have `///` doc comments\n- [ ] `rust-toolchain.toml` is present and pinned\n\n</validation>\n\n<example>\n\n## Example\n\n**Task:** Error type and async function with proper error handling.\n\n```rust\n// crates/core/src/error.rs\nuse thiserror::Error;\n\n#[derive(Debug, Error)]\npub enum StorageError {\n    #[error(\"object not found: {key}\")]\n    NotFound { key: String },\n    #[error(\"IO error: {0}\")]\n    Io(#[from] std::io::Error),\n    #[error(\"serialization error: {0}\")]\n    Serde(#[from] serde_json::Error),\n    #[error(\"connection timeout after {elapsed_ms}ms\")]\n    Timeout { elapsed_ms: u64 },\n}\n\npub type Result<T> = std::result::Result<T, StorageError>;\n```\n\n```rust\n// crates/core/src/store.rs\nuse std::sync::Arc;\nuse tokio::fs;\nuse crate::error::{Result, StorageError};\n\npub struct ObjectStore {\n    base_path: Arc<str>,\n}\n\nimpl ObjectStore {\n    pub fn new(base_path: impl Into<Arc<str>>) -> Self {\n        Self { base_path: base_path.into() }\n    }\n\n    /// Read an object by key, returning its bytes.\n    pub async fn get(&self, key: &str) -> Result<Vec<u8>> {\n        let path = format!(\"{}/{}\", self.base_path, key);\n        fs::read(&path).await.map_err(|e| match e.kind() {\n            std::io::ErrorKind::NotFound => StorageError::NotFound {\n                key: key.to_string(),\n            },\n            _ => StorageError::Io(e),\n        })\n    }\n\n    /// Write bytes to an object key.\n    pub async fn put(&self, key: &str, data: &[u8]) -> Result<()> {\n        let path = format!(\"{}/{}\", self.base_path, key);\n        if let Some(parent) = std::path::Path::new(&path).parent() {\n            fs::create_dir_all(parent).await?;\n        }\n        fs::write(&path, data).await?;\n        Ok(())\n    }\n}\n```\n\n</example>\n\n---\n\n## References Index\n\nFor detailed guides and code examples, refer to the following documents in `references/`:\n\n- **[Workspace Architecture](references/workspace.md)** -- Centralized deps, release profiles, feature flags, module hierarchy.\n- **[Async & Concurrency](references/async.md)** -- Tokio patterns, GIL-free async with pyo3_async_runtimes, crossbeam, parking_lot.\n- **[PyO3 & Maturin Bindings](references/pyo3.md)** -- Module registration, frozen classes, signature macros, zero-copy, maturin config.\n- **[Error Handling](references/errors.md)** -- thiserror 2.0 derive, PyErr conversion, platform-specific errors, From impls.\n- **[Platform Abstraction](references/platform.md)** -- Conditional modules per OS, target-specific deps, futex/ulock/WaitOnAddress.\n- **[napi-rs Node/Bun Bindings](references/napi.md)** -- Module setup, #[napi] macros, async tasks, TSFN, cross-platform npm distribution.\n- **[C ABI & FFI](references/c_abi.md)** -- Stable C ABI, raw pointer patterns, cbindgen, zero-copy for C consumers.\n- **[Testing & Benchmarking](references/testing.md)** -- Integration tests, criterion 0.5 benchmarks, CI matrix, maturin develop.\n\n---\n\n## Official References\n\n- <https://doc.rust-lang.org/book/>\n- <https://blog.rust-lang.org/releases/>\n- <https://tokio.rs/>\n- <https://pyo3.rs/>\n- <https://maturin.rs/>\n- <https://napi.rs/>\n\n## Shared Styleguide Baseline\n\n- Use shared styleguides for generic language/framework rules to reduce duplication in this skill.\n- [General Principles](https://github.com/cofin/flow/blob/main/templates/styleguides/general.md)\n- [Rust](https://github.com/cofin/flow/blob/main/templates/styleguides/languages/rust.md)\n- Keep this skill focused on tool-specific workflows, edge cases, and integration details.","tags":["rust","flow","cofin","agent-skills","ai-agents","beads","claude-code","codex","cursor","developer-tools","gemini-cli","opencode"],"capabilities":["skill","source-cofin","skill-rust","topic-agent-skills","topic-ai-agents","topic-beads","topic-claude-code","topic-codex","topic-cursor","topic-developer-tools","topic-gemini-cli","topic-opencode","topic-plugin","topic-slash-commands","topic-spec-driven-development"],"categories":["flow"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/cofin/flow/rust","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add cofin/flow","source_repo":"https://github.com/cofin/flow","install_from":"skills.sh"}},"qualityScore":"0.455","qualityRationale":"deterministic score 0.46 from registry signals: · indexed on github topic:agent-skills · 11 github stars · SKILL.md body (8,339 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:07:39.159Z","embedding":null,"createdAt":"2026-04-23T13:04:01.315Z","updatedAt":"2026-05-18T19:07:39.159Z","lastSeenAt":"2026-05-18T19:07:39.159Z","tsv":"'/book/':981 '/cofin/flow/blob/main/templates/styleguides/general.md)':1009 '/cofin/flow/blob/main/templates/styleguides/languages/rust.md)':1013 '/releases/':984 '0':213,233,691,700 '0.5':971 '1':340 '2':79,348,368,613 '2.0':908 '2021':77 '3':394 '4':424 '5':453 'abi':21,360,949,954 'abi/ffi':69 'abstract':59,919 'access':579 'across':273,286,304,500,539,573,598 'add':384,563 'allow':93,105,108 'anyhow':517 'api':132,649 'apperror':209,243 'arc':137,269,477,496,626,730,744,754 'architectur':863 'argument':104 'async':11,56,141,244,409,444,481,623,663,769,810,873,881,884,940 'automat':382 'await':287,840,845 'await.map':786 'base':742,750,757 'base_path.into':759 'baselin':991 'benchmark':73,418,966,972 'binari':162,251 'binaries/scripts':519 'bind':62,67,165,171,179,355,391,425,430,557,891,934 'blog.rust-lang.org':983 'blog.rust-lang.org/releases/':982 'bound':332 'build':602 'busi':398 'byte':767,804 'c':20,68,359,948,953,963 'cargo':116,119,415,456,460,464,643 'cargo.lock':9 'cargo.toml':8,87,149 'case':1024 'cbindgen':958 'cdylib':166 'central':527,865 'cfg':96,97 'cfgs':91 'check':95,462 'check-cfg':94 'checkpoint':604 'ci':599,973 'class':336,896 'clippi':120,457,644 'clone':307 'code':12,74,482,608,624,853 'comment':135,652 'compil':491,596 'complex':107 'concurr':874 'condit':921 'config':84,311,531,903 'connect':707 'consist':595 'consum':964 'context':142 'convers':383,386,622,911 'copi':901,961 'core':153,173,353,395,402,427,541,556,561,632 'cover':53 'crate':38,109,152,174,180,191,261,265,356,374,392,403,431,525,540,542,558,633,735 'crates/core/src/error.rs':670 'crates/core/src/store.rs':726 'creat':343,836 'criterion':422,970 'critic':28 'cross':43,944 'cross-platform':42,943 'crossbeam':886 'd':121,458,645 'data':439,569,816,844 'debug':205,308,675 'defin':371 'deliv':606 'dep':158,546,866,928 'depend':178,185,364,407,528,559,637 'deriv':204,306,509,674,909 'detail':850,1027 'develop':470,976 'dir':837 'disabl':100 'display':512 'distribut':947 'doc':134,651 'doc.rust-lang.org':980 'doc.rust-lang.org/book/':979 'document':130,859 'duplic':536,1001 'e':788,802 'e.kind':790 'edg':1023 'edit':4,76 'elaps':710,714 'enabl':570 'ensur':594 'enum':208,376,678 'err':787 'error':13,70,196,203,206,210,212,218,219,221,230,369,375,506,510,616,660,667,673,676,680,688,690,696,697,699,705,706,736,904,915 'errorkind':793 'essenti':246 'exampl':658,854 'extens':51 'fail':489 'featur':259,869 'ffi':157,177,406,545,564,636,950 'file':6 'flag':870 'flexibl':591 'fmt':117,461 'fn':328,748,770,811 'focus':1017 'follow':858 'format':115,779,821 'found':232,683 'free':880 'frozen':300,301,436,566,895 'fs':733,783,835,841 'full':267 'function':664 'futex/ulock/waitonaddress':929 'futur':440 'general':1005 'generic':996 'get':313,318,771 'gil':99,879 'gil-fre':878 'github.com':1008,1012 'github.com/cofin/flow/blob/main/templates/styleguides/general.md)':1007 'github.com/cofin/flow/blob/main/templates/styleguides/languages/rust.md)':1011 'guardrail':475 'guid':851 'handl':14,71,197,254,668,905 'hierarchi':872 'high':46 'high-perform':45 'hold':283 'hot':419 'http':159 'i/o-bound':411 'immut':302,438,568 'impl':515,745,752,917 'index':848 'inherit':110 'init':330 'instrument':129,585 'integr':968,1026 'io':211,214,217,689,692,695,792,801 'json':704 'keep':547,1014 'key':684,686,764,773,782,797,808,814,824 'key.to':798 'language/framework':997 'layout':55,342 'let':777,819,826 'level':82,92,588 'libc':553,642 'librari':256,505 'lint':83,111,112,118,530 'local':601 'lock':285,580 'log':126,583 'logic':155,352,396,399 'lot':291,888 'm':331 'm.add':335 'macro':451,898,939 'main':249 'mani':103 'match':789 'matrix':974 'maturin':16,469,890,902,975 'maturin.rs':987 'max':320 'messag':224,228 'modul':871,893,922,936 'ms':711,712,715 'multi':37,524 'multi-cr':36,523 'mutex':280,292 'name':315,325 'napi':18,64,169,447,450,550,640,931,938 'napi-r':17,63,168,446,549,639,930 'napi.rs':988 'nativ':326 'need':266 'network':161 'never':275,535 'new':749,832 'node':167,358 'node/bun':66,933 'notfound':234,685,794,796 'npm':946 'object':681,762,807 'objectstor':741,746 'offici':977 'ok':337,846 'os':924 'otherwis':288 'ownership':499 'parent':828,834,839 'park':290,887 'pars':220,225 'pass':252,647 'path':30,223,226,420,743,751,758,778,781,785,820,823,830,831,833,843 'pattern':34,198,294,877,957 'per':260,373,578,923 'per-access':577 'per-crat':372 'perform':27,33,47 'performance-crit':26 'pin':183,361,538,592,657 'platform':22,44,58,913,918,945 'platform-specif':912 'pointer':956 'polyglot':50 'prefer':136,476 'prelud':298 'present':655 'principl':1006 'profil':534,868 'project':148,526 'proper':666 'provid':508 'pub':207,236,309,314,319,327,677,717,739,747,768,809 'public':131,648 'pure':154,351 'pure-log':350 'put':812 'py':98,163,357,442 'pyclass':299,435,565 'pyerr':385,389,910 'pymodul':323,329,333 'pyo3':15,164,293,297,312,317,324,433,468,548,638,883,889 'pyo3.rs':986 'pyo3/maturin':60 'pyresult':334 'python':61,473,574 'quick':143 'raw':955 'rc':139,276,479,483,628 'read':760,784 'reduc':1000 'refer':144,192,847,855,861,978 'references/async.md':875 'references/c_abi.md':951 'references/errors.md':906 'references/napi.md':935 'references/platform.md':920 'references/pyo3.md':892 'references/testing.md':967 'references/workspace.md':864 'registr':894 'releas':533,867 'reserv':516 'resolv':78,347,612 'result':238,240,241,719,721,722,737,775,818 'retri':321 'return':765 'root':86,151,188 'rs':7,19,65,170,448,551,641,932 'rule':998 'run':455,472 'runtim':57,160,253,885 'rust':1,5,29,31,39,200,295,607,669,725,1010 'rust-toolchain.toml':172,593,653 'safe':303,571 'select':257 'self':755,756,772,813 'self.base':780,822 'send':486 'separ':349 'serd':701,703 'serial':698 'server':264 'setup':146,937 'share':184,271,363,498,572,630,989,993 'signatur':897 'skill':1004,1016 'skill-rust' 'source-cofin' 'span':587 'specif':914,927,1021 'stabl':952 'state':272,631 'std':216,239,694,720,728,791,829 'step':339,367,393,423,452 'storageerror':679,724,738,795,800 'str':774,815 'string':227,229,235,316,687,799 'struct':310,740 'structur':128,584 'style':75 'styleguid':990,994 'subscrib':590 'support':23 'surfac':52 'sync':279,729 'system':32,48 'target':41,926 'target-specif':925 'task':274,494,501,659,941 'test':24,413,416,465,474,965,969 'text':147 'thiserror':199,202,378,503,619,672,907 'thread':305,575 'timeout':708,713 'tokio':245,248,258,278,493,732,876 'tokio.rs':985 'toml':88 'tool':1020 'tool-specif':1019 'topic-agent-skills' 'topic-ai-agents' 'topic-beads' 'topic-claude-code' 'topic-codex' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'topic-opencode' 'topic-plugin' 'topic-slash-commands' 'topic-spec-driven-development' 'trace':124,581 'true':114,195 'tsfn':942 'type':106,237,370,507,617,661,718 'types/functions':428 'u32':322 'u64':716 'u8':817 'unexpect':90 'use':2,123,201,247,268,277,289,296,379,408,434,449,495,502,611,618,625,671,727,731,734,992 'valid':454,603 'vec':776 'verifi':609 'version':529,537,597 'warn':122,459,646 'without':576 'work':412 'workflow':338,1022 'workspac':10,40,54,81,113,145,150,187,194,341,345,466,521,610,862 'workspace-level':80 'workspace.dependencies':190,366,615 'workspace.lints.clippy':101 'workspace.lints.rust':89 'wrap':181,426 'write':397,803,842 'zero':176,544,900,960 'zero-copi':899,959","prices":[{"id":"1b5c4284-fd3e-4a88-81bb-cc04e5ce79e0","listingId":"a9311d15-b2ee-4526-b7f4-e12c237d9b08","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"cofin","category":"flow","install_from":"skills.sh"},"createdAt":"2026-04-23T13:04:01.315Z"}],"sources":[{"listingId":"a9311d15-b2ee-4526-b7f4-e12c237d9b08","source":"github","sourceId":"cofin/flow/rust","sourceUrl":"https://github.com/cofin/flow/tree/main/skills/rust","isPrimary":false,"firstSeenAt":"2026-04-23T13:04:01.315Z","lastSeenAt":"2026-05-18T19:07:39.159Z"}],"details":{"listingId":"a9311d15-b2ee-4526-b7f4-e12c237d9b08","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"cofin","slug":"rust","github":{"repo":"cofin/flow","stars":11,"topics":["agent-skills","ai-agents","beads","claude-code","codex","context-driven-development","cursor","developer-tools","gemini-cli","opencode","plugin","slash-commands","spec-driven-development","subagents","tdd","workflow"],"license":"apache-2.0","html_url":"https://github.com/cofin/flow","pushed_at":"2026-04-27T19:07:26Z","description":"Context-Driven Development toolkit for AI agents — spec-first planning, TDD workflow, and Beads integration.","skill_md_sha":"52ca25e6d2aab59d8f91f1aec2349f77fc6b6d22","skill_md_path":"skills/rust/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/cofin/flow/tree/main/skills/rust"},"layout":"multi","source":"github","category":"flow","frontmatter":{"name":"rust","description":"Use when editing Rust files, .rs, Cargo.toml, Cargo.lock, workspaces, async code, error handling, PyO3, maturin, napi-rs, C ABI, platform support, tests, or performance-critical Rust paths."},"skills_sh_url":"https://skills.sh/cofin/flow/rust"},"updatedAt":"2026-05-18T19:07:39.159Z"}}