{"id":"a9311d15-b2ee-4526-b7f4-e12c237d9b08","shortId":"xWuwkv","kind":"skill","title":"rust","tagline":"Auto-activate for .rs files, Cargo.toml, Cargo.lock. Produces Rust code with workspace architecture, async patterns, FFI bindings (PyO3/napi-rs), and error handling. Use when: writing Rust code, designing cross-platform systems, building Python extensions with PyO3/maturin, build","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-04-24T07:03:19.682Z","embedding":null,"createdAt":"2026-04-23T13:04:01.315Z","updatedAt":"2026-04-24T07:03:19.682Z","lastSeenAt":"2026-04-24T07:03:19.682Z","tsv":"'/book/':990 '/cofin/flow/blob/main/templates/styleguides/general.md)':1018 '/cofin/flow/blob/main/templates/styleguides/languages/rust.md)':1022 '/releases/':993 '0':222,242,700,709 '0.5':980 '1':349 '2':88,357,377,622 '2.0':917 '2021':86 '3':403 '4':433 '5':462 'abi':369,958,963 'abi/ffi':78 'abstract':68,928 'access':588 'across':282,295,313,509,548,582,607 'activ':4 'add':393,572 'allow':102,114,117 'anyhow':526 'api':141,658 'apperror':218,252 'arc':146,278,486,505,635,739,753,763 'architectur':15,872 'argument':113 'async':16,65,150,253,418,453,490,632,672,778,819,882,890,893,949 'auto':3 'auto-activ':2 'automat':391 'await':296,849,854 'await.map':795 'base':751,759,766 'base_path.into':768 'baselin':1000 'benchmark':82,427,975,981 'binari':171,260 'binaries/scripts':528 'bind':19,71,76,174,180,188,364,400,434,439,566,900,943 'blog.rust-lang.org':992 'blog.rust-lang.org/releases/':991 'bound':341 'build':34,39,611 'busi':407 'byte':776,813 'c':77,368,957,962,972 'cargo':125,128,424,465,469,473,652 'cargo.lock':9 'cargo.toml':8,96,158 'case':1033 'cbindgen':967 'cdylib':175 'central':536,874 'cfg':105,106 'cfgs':100 'check':104,471 'check-cfg':103 'checkpoint':613 'ci':608,982 'class':345,905 'clippi':129,466,653 'clone':316 'code':12,28,83,491,617,633,862 'comment':144,661 'compil':500,605 'complex':116 'concurr':883 'condit':930 'config':93,320,540,912 'connect':716 'consist':604 'consum':973 'context':151 'convers':392,395,631,920 'copi':910,970 'core':162,182,362,404,411,436,550,565,570,641 'cover':62 'crate':47,118,161,183,189,200,270,274,365,383,401,412,440,534,549,551,567,642,744 'crates/core/src/error.rs':679 'crates/core/src/store.rs':735 'creat':352,845 'criterion':431,979 'cross':31,52,953 'cross-platform':30,51,952 'crossbeam':895 'd':130,467,654 'data':448,578,825,853 'debug':214,317,684 'defin':380 'deliv':615 'dep':167,555,875,937 'depend':187,194,373,416,537,568,646 'deriv':213,315,518,683,918 'design':29 'detail':859,1036 'develop':479,985 'dir':846 'disabl':109 'display':521 'distribut':956 'doc':143,660 'doc.rust-lang.org':989 'doc.rust-lang.org/book/':988 'document':139,868 'duplic':545,1010 'e':797,811 'e.kind':799 'edg':1032 'edit':85 'elaps':719,723 'enabl':579 'ensur':603 'enum':217,385,687 'err':796 'error':22,79,205,212,215,219,221,227,228,230,239,378,384,515,519,625,669,676,682,685,689,697,699,705,706,708,714,715,745,913,924 'errorkind':802 'essenti':255 'exampl':667,863 'extens':36,60 'fail':498 'featur':268,878 'ffi':18,166,186,415,554,573,645,959 'file':7 'flag':879 'flexibl':600 'fmt':126,470 'fn':337,757,779,820 'focus':1026 'follow':867 'format':124,788,830 'found':241,692 'free':889 'frozen':309,310,445,575,904 'fs':742,792,844,850 'full':276 'function':673 'futex/ulock/waitonaddress':938 'futur':449 'general':1014 'generic':1005 'get':322,327,780 'gil':108,888 'gil-fre':887 'github.com':1017,1021 'github.com/cofin/flow/blob/main/templates/styleguides/general.md)':1016 'github.com/cofin/flow/blob/main/templates/styleguides/languages/rust.md)':1020 'guardrail':484 'guid':860 'handl':23,80,206,263,677,914 'hierarchi':881 'high':55 'high-perform':54 'hold':292 'hot':428 'http':168 'i/o-bound':420 'immut':311,447,577 'impl':524,754,761,926 'index':857 'inherit':119 'init':339 'instrument':138,594 'integr':977,1035 'io':220,223,226,698,701,704,801,810 'json':713 'keep':556,1023 'key':693,695,773,782,791,806,817,823,833 'key.to':807 'language/framework':1006 'layout':64,351 'let':786,828,835 'level':91,101,597 'libc':562,651 'librari':265,514 'lint':92,120,121,127,539 'local':610 'lock':294,589 'log':135,592 'logic':164,361,405,408 'lot':300,897 'm':340 'm.add':344 'macro':460,907,948 'main':258 'mani':112 'match':798 'matrix':983 'maturin':478,899,911,984 'maturin.rs':996 'max':329 'messag':233,237 'modul':880,902,931,945 'ms':720,721,724 'multi':46,533 'multi-cr':45,532 'mutex':289,301 'name':324,334 'napi':73,178,456,459,559,649,940,947 'napi-r':72,177,455,558,648,939 'napi.rs':997 'nativ':335 'need':275 'network':170 'never':284,544 'new':758,841 'node':176,367 'node/bun':75,942 'notfound':243,694,803,805 'npm':955 'object':690,771,816 'objectstor':750,755 'offici':986 'ok':346,855 'os':933 'otherwis':297 'ownership':508 'parent':837,843,848 'park':299,896 'pars':229,234 'pass':261,656 'path':232,235,429,752,760,767,787,790,794,829,832,839,840,842,852 'pattern':17,43,207,303,886,966 'per':269,382,587,932 'per-access':586 'per-crat':381 'perform':42,56 'pin':192,370,547,601,666 'platform':32,53,67,922,927,954 'platform-specif':921 'pointer':965 'polyglot':59 'prefer':145,485 'prelud':307 'present':664 'principl':1015 'produc':10 'profil':543,877 'project':157,535 'proper':675 'provid':517 'pub':216,245,318,323,328,336,686,726,748,756,777,818 'public':140,657 'pure':163,360 'pure-log':359 'put':821 'py':107,172,366,451 'pyclass':308,444,574 'pyerr':394,398,919 'pymodul':332,338,342 'pyo3':173,302,306,321,326,333,442,477,557,647,892,898 'pyo3.rs':995 'pyo3/maturin':38,69 'pyo3/napi-rs':20 'pyresult':343 'python':35,70,482,583 'quick':152 'raw':964 'rc':148,285,488,492,637 'read':769,793 'reduc':1009 'refer':153,201,856,864,870,987 'references/async.md':884 'references/c_abi.md':960 'references/errors.md':915 'references/napi.md':944 'references/platform.md':929 'references/pyo3.md':901 'references/testing.md':976 'references/workspace.md':873 'registr':903 'releas':542,876 'reserv':525 'resolv':87,356,621 'result':247,249,250,728,730,731,746,784,827 'retri':330 'return':774 'root':95,160,197 'rs':6,74,179,457,560,650,941 'rule':1007 'run':464,481 'runtim':66,169,262,894 'rust':1,11,27,40,48,209,304,616,678,734,1019 'rust-toolchain.toml':181,602,662 'safe':312,580 'select':266 'self':764,765,781,822 'self.base':789,831 'send':495 'separ':358 'serd':710,712 'serial':707 'server':273 'setup':155,946 'share':193,280,372,507,581,639,998,1002 'signatur':906 'skill':1013,1025 'skill-rust' 'source-cofin' 'span':596 'specif':923,936,1030 'stabl':961 'state':281,640 'std':225,248,703,729,737,800,838 'step':348,376,402,432,461 'storageerror':688,733,747,804,809 'str':783,824 'string':236,238,244,325,696,808 'struct':319,749 'structur':137,593 'style':84 'styleguid':999,1003 'subscrib':599 'surfac':61 'sync':288,738 'system':33,41,57 'target':50,935 'target-specif':934 'task':283,503,510,668,950 'test':422,425,474,483,974,978 'text':156 'thiserror':208,211,387,512,628,681,916 'thread':314,584 'timeout':717,722 'tokio':254,257,267,287,502,741,885 'tokio.rs':994 'toml':97 'tool':1029 'tool-specif':1028 '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':133,590 'true':123,204 'tsfn':951 'type':115,246,379,516,626,670,727 'types/functions':437 'u32':331 'u64':725 'u8':826 'unexpect':99 'use':24,132,210,256,277,286,298,305,388,417,443,458,504,511,620,627,634,680,736,740,743,1001 'valid':463,612 'vec':785 'verifi':618 'version':538,546,606 'warn':131,468,655 'without':585 'work':421 'workflow':347,1031 'workspac':14,49,63,90,122,154,159,196,203,350,354,475,530,619,871 'workspace-level':89 'workspace.dependencies':199,375,624 'workspace.lints.clippy':110 'workspace.lints.rust':98 'wrap':190,435 'write':26,406,812,851 'zero':185,553,909,969 'zero-copi':908,968","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-04-24T07:03:19.682Z"}],"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-19T23:22:27Z","description":"Context-Driven Development toolkit for AI agents — spec-first planning, TDD workflow, and Beads integration.","skill_md_sha":"6182ea5685b10aef08d61886834dc8a49f713e85","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":"Auto-activate for .rs files, Cargo.toml, Cargo.lock. Produces Rust code with workspace architecture, async patterns, FFI bindings (PyO3/napi-rs), and error handling. Use when: writing Rust code, designing cross-platform systems, building Python extensions with PyO3/maturin, building Node/Bun extensions with napi-rs, exposing C ABI, or optimizing performance-critical paths. Not for C/C++ (see cpp) or languages that compile to WASM without Rust."},"skills_sh_url":"https://skills.sh/cofin/flow/rust"},"updatedAt":"2026-04-24T07:03:19.682Z"}}