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