turon_skill

Overview

This skill codifies API design and async Rust patterns in the style of Aaron Turon. It emphasizes user-first APIs, making illegal states unrepresentable, and designing async code that reads like sync code. Use it to shape public library interfaces, async systems, and ergonomic builders that are hard to use incorrectly.

How this skill works

I inspect intended usage scenarios first and propose API shapes that make the obvious thing the right thing. I recommend concrete patterns: builders, type-state, extension traits, impl Trait return types, and async parity. I also suggest trait implementations, naming, and error shaping so the API is consistent, discoverable, and compiler-enforced where possible.

When to use it

• Designing public library APIs that must be easy to discover and hard to misuse
• Creating async APIs that should read and behave like sync equivalents
• Defining state machines or protocols where order matters (use type-state)
• Building fluent request/builder patterns or complex constructors
• Refactoring an existing API to follow Rust conventions and reduce surface area

Best practices

• Start by writing the ideal usage examples (the code users should write) before implementation
• Make illegal states unrepresentable with types and prefer compile-time guarantees
• Favor builders for complex construction and type-state for ordered workflows
• Keep async and sync APIs parallel; return impl Future or async fn where appropriate
• Implement standard traits (Debug, Clone, Default) when it improves ergonomics and discovery
• Use clear, conventional Rust names: new, with_, into_, as_, to_, is_

Example use cases

• HTTP client with a RequestBuilder that composes headers and sends either sync or async requests
• Connection/state machine using type-state to enforce connect→authenticate→query order
• Library exposing an async Repository trait with native async methods or async-trait shim
• Extension traits adding ergonomic helpers to third-party types (ResultExt for error context/logging)
• Utility that exposes both blocking and async convenience APIs with clear boundaries