Non-negotiable rules:
- Identify the subsystem before coding. Load only the relevant references.
- Safe Rust by default.
unsafe only when justified — every unsafe block gets a // SAFETY: comment.
- Zero-copy where possible. mmap'd segments,
&str/&[u8] references into pages. Never copy data without reason.
- Error types per crate.
thiserror enums in library crates. Never anyhow in libraries — only in binaries/tests.
- Async with tokio. All I/O is async. CPU-bound work on
spawn_blocking. Never block the tokio runtime.
- Workspace crate structure. One crate per subsystem. Depend downward — never circular.
- Property tests for invariants.
proptest for round-trips, type coercion, binary parsing.
rust
Inputs
$request: The crate, subsystem, bug, feature, or review target
Goal
Route Rust work through the right subsystem conventions so changes follow the workspace’s systems-programming patterns instead of generic Rust defaults.
Step 0: Identify the subsystem
Decide which part of the Rust surface the task touches:
- storage engine
- binary formats
- type system
- Arrow or DataFusion
- wire protocols
- search or vectors
- arena or graph code
- geo indexing
- async or concurrency
- testing
- unsafe or error design
Success criteria: The task is mapped to the right subsystem before references are loaded.
Step 1: Load only the relevant references
Use the routing table to pick the matching files. Do not bulk-load the full reference tree.
| Task / Area |
Read |
| Toolchain, workspace layout, key crates, Cargo conventions |
references/stack.md |
| WAL, mmap, segments, MVCC, compaction, io_uring, backends |
references/storage-engine.md |
| Custom on-disk formats, zero-copy parsing, packed structs |
references/binary-formats.md |
| Database type system, disk/exec types, Arrow interop |
references/type-system.md |
| DataFusion table providers, UDFs, Arrow RecordBatch, planning |
references/datafusion-arrow.md |
| pgwire server, MySQL protocol, dialect mapping, ORM compat |
references/wire-protocols.md |
| tantivy FTS, HNSW vectors, SIMD distance, hybrid search |
references/search-vector.md |
| bumpalo arenas, graph adjacency, traversal algorithms |
references/arena-graph.md |
| R-tree spatial index, geo predicates, WGS84 distance |
references/geo-rtree.md |
| tokio async, io_uring, crossbeam, lock-free structures, MVCC |
references/async-concurrency.md |
| proptest, deterministic testing, integration test patterns |
references/testing.md |
| thiserror hierarchies, unsafe patterns, safety invariants |
references/error-unsafe.md |
Multiple tasks? Read multiple files.
Success criteria: Only the subsystem-relevant Rust guidance is active.
Step 2: Implement with the core Rust guardrails
Keep these rules active:
- safe Rust by default;
unsafe only when justified with // SAFETY:
- error types match crate boundaries (
thiserror in libs, anyhow only in bins/tests)
- async code does not block the runtime; CPU work on
spawn_blocking
- owned vs borrowed data choices are deliberate; prefer
&[u8] over Vec<u8> in signatures
- explicit
use imports — no glob imports except in test modules
#[must_use] on functions returning Result or computed values#[inline] only on small functions in hot loops — never on public APISend + Sync bounds on trait objects crossing async boundaries#[derive(Debug)] on all public types; #[derive(Clone)] only when cheap- feature flags for optional crate deps —
#[cfg(feature = "...")]
- tests match the risk: unit, integration, property, snapshot, or domain-specific verification
Success criteria: The implementation fits the workspace’s systems-level quality bar.
Step 3: Verify the change
Use the narrowest relevant verification loop:
cargo fmtcargo clippy -- -D warnings- focused crate tests
- subsystem-specific tests such as proptest or snapshots when appropriate
Success criteria: The Rust surface is validated the way this workspace expects.
Guardrails
- Do not inline the whole Rust handbook in
SKILL.md.
- Do not skip subsystem identification.
- Do not use
anyhow in library crates unless the project specifically allows it there.
- Do not add
disable-model-invocation; this is a normal domain skill.
- Do not leave unsafe invariants undocumented.
When To Load References
Output Contract
Report:
- which Rust references were loaded
- the subsystem pattern applied
- the change made
- the verification run
1---2name: rust3description: Write and change Rust the way THIS workspace already does it, NOT by generic defaults — a systems-programming reference carrying the real crate boundaries, error model, and conventions for storage engines, binary formats, Arrow/DataFusion, search and vector indexing, async concurrency, testing, and unsafe discipline, so a change lands idiomatic and review-ready instead of merely compiling. Use when a task touches this workspace's Rust crates and should follow its systems-level conventions rather than boilerplate.4---5
6<EXTREMELY-IMPORTANT>
7This skill is the routing shell over the Rust reference set, not the whole systems handbook.
8
9Non-negotiable rules:
101. Identify the subsystem before coding. Load only the relevant references.
112. **Safe Rust by default.** `unsafe` only when justified — every `unsafe` block gets a `// SAFETY:` comment.
123. **Zero-copy where possible.** mmap'd segments, `&str`/`&[u8]` references into pages. Never copy data without reason.
134. **Error types per crate.** `thiserror` enums in library crates. Never `anyhow` in libraries — only in binaries/tests.
145. **Async with tokio.** All I/O is async. CPU-bound work on `spawn_blocking`. Never block the tokio runtime.
156. **Workspace crate structure.** One crate per subsystem. Depend downward — never circular.
167. **Property tests for invariants.** `proptest` for round-trips, type coercion, binary parsing.
17</EXTREMELY-IMPORTANT>
18
19# rust
20
21## Inputs
22
23- `$request`: The crate, subsystem, bug, feature, or review target
24
25## Goal
26
27Route Rust work through the right subsystem conventions so changes follow the workspace’s systems-programming patterns instead of generic Rust defaults.
28
29## Step 0: Identify the subsystem
30
31Decide which part of the Rust surface the task touches:
32
33- storage engine
34- binary formats
35- type system
36- Arrow or DataFusion
37- wire protocols
38- search or vectors
39- arena or graph code
40- geo indexing
41- async or concurrency
42- testing
43- unsafe or error design
44
45**Success criteria**: The task is mapped to the right subsystem before references are loaded.
46
47## Step 1: Load only the relevant references
48
49Use the routing table to pick the matching files. Do not bulk-load the full reference tree.
50
51| Task / Area | Read |
52|---|---|
53| Toolchain, workspace layout, key crates, Cargo conventions | `references/stack.md` |
54| WAL, mmap, segments, MVCC, compaction, io_uring, backends | `references/storage-engine.md` |
55| Custom on-disk formats, zero-copy parsing, packed structs | `references/binary-formats.md` |
56| Database type system, disk/exec types, Arrow interop | `references/type-system.md` |
57| DataFusion table providers, UDFs, Arrow RecordBatch, planning | `references/datafusion-arrow.md` |
58| pgwire server, MySQL protocol, dialect mapping, ORM compat | `references/wire-protocols.md` |
59| tantivy FTS, HNSW vectors, SIMD distance, hybrid search | `references/search-vector.md` |
60| bumpalo arenas, graph adjacency, traversal algorithms | `references/arena-graph.md` |
61| R-tree spatial index, geo predicates, WGS84 distance | `references/geo-rtree.md` |
62| tokio async, io_uring, crossbeam, lock-free structures, MVCC | `references/async-concurrency.md` |
63| proptest, deterministic testing, integration test patterns | `references/testing.md` |
64| thiserror hierarchies, unsafe patterns, safety invariants | `references/error-unsafe.md` |
65
66Multiple tasks? Read multiple files.
67
68**Success criteria**: Only the subsystem-relevant Rust guidance is active.
69
70## Step 2: Implement with the core Rust guardrails
71
72Keep these rules active:
73
74- safe Rust by default; `unsafe` only when justified with `// SAFETY:`
75- error types match crate boundaries (`thiserror` in libs, `anyhow` only in bins/tests)
76- async code does not block the runtime; CPU work on `spawn_blocking`
77- owned vs borrowed data choices are deliberate; prefer `&[u8]` over `Vec<u8>` in signatures
78- explicit `use` imports — no glob imports except in test modules
79- `#[must_use]` on functions returning `Result` or computed values
80- `#[inline]` only on small functions in hot loops — never on public API
81- `Send + Sync` bounds on trait objects crossing async boundaries
82- `#[derive(Debug)]` on all public types; `#[derive(Clone)]` only when cheap
83- feature flags for optional crate deps — `#[cfg(feature = "...")]`
84- tests match the risk: unit, integration, property, snapshot, or domain-specific verification
85
86**Success criteria**: The implementation fits the workspace’s systems-level quality bar.
87
88## Step 3: Verify the change
89
90Use the narrowest relevant verification loop:
91
92- `cargo fmt`
93- `cargo clippy -- -D warnings`
94- focused crate tests
95- subsystem-specific tests such as proptest or snapshots when appropriate
96
97**Success criteria**: The Rust surface is validated the way this workspace expects.
98
99## Guardrails
100
101- Do not inline the whole Rust handbook in `SKILL.md`.
102- Do not skip subsystem identification.
103- Do not use `anyhow` in library crates unless the project specifically allows it there.
104- Do not add `disable-model-invocation`; this is a normal domain skill.
105- Do not leave unsafe invariants undocumented.
106
107## When To Load References
108
109- `references/stack.md`
110 Use for workspace/toolchain context.
111
112- then only the task-relevant subsystem files under `references/`
113
114## Output Contract
115
116Report:
117
1181. which Rust references were loaded
1192. the subsystem pattern applied
1203. the change made
1214. the verification run
ulpi-io