rust-unsafe_skill

Overview

This skill is an expert guide for writing, reviewing, and refactoring unsafe Rust and FFI code. It distills practical patterns, a 47-rule checklist, and tool-based workflows to avoid undefined behavior and unsafe API exposure. The skill emphasizes SAFETY documentation, safe wrappers, and validated pointer usage to keep unsafe code minimal and auditable.

How this skill works

The skill inspects unsafe blocks, FFI boundaries, raw pointer usage, unions, and memory-layout choices against a compact rule set and review checklist. It recommends concrete replacement patterns (NonNull, MaybeUninit, repr(C), safe wrappers), produces SAFETY comments for each unsafe region, and proposes verification commands like Miri and ASAN to validate invariants. It also guides creating private unsafe internals with safe public APIs.

When to use it

• Wrapping C libraries or exposing Rust to foreign ABIs (FFI)
• Implementing low-level data structures (Vec, Arc internals) that require manual memory control
• Fixing UB found by Miri, ASAN, or production crash reports
• Measured performance hotspots where safe abstractions are proven too slow
• During code reviews of unsafe changes or prior-to-merge safety audits

Best practices

• Question the need for unsafe: prefer safe abstractions and redesign over escaping the borrow checker
• Add a SAFETY comment before every unsafe block and a /// # Safety section for public unsafe functions
• Validate raw pointers with NonNull and bounds checks before dereference
• Use MaybeUninit for uninitialized memory; avoid mem::uninitialized/zeroed
• Prefer repr(C) and portable type aliases at FFI boundaries and handle panics across extern calls
• Wrap unsafe internals in safe private helpers and expose a safe public API

Example use cases

• Create a safe Rust wrapper for a C API: validate inputs, build CString, call extern and return Result
• Implement buffer write using NonNull pointer with index bounds validation and SAFETY comment
• Allocate and initialize a Vec of MaybeUninit, then transmute after safe initialization
• Define FFI-compatible structs with #[repr(C)] and document layout invariants for external callers
• Audit a module: run cargo +nightly miri test, address sanitizer, and check checklist items before merge