rust-macro_skill

Overview

This skill is a macro and procedural metaprogramming expert for Rust, covering macro_rules!, derive macros, function-like proc-macros, attribute macros, compile-time validation, and common code-generation patterns. It helps choose between macros and generics, design hygienic expansions, and optimize compile-time cost while keeping generated code testable and readable.

How this skill works

The skill inspects code and design intent to recommend an appropriate macro type and pattern, generates example implementations, and validates common pitfalls (hygiene, error messages, compile-time cost). It explains repetition matchers, shows expansion tooling, and provides templates for declarative macros, derives, function-like and attribute proc-macros. It also outlines verification commands and review checklists.

When to use it

• You need syntax transformation that generics cannot express
• You want to reduce repetitive boilerplate across many types or patterns
• You need to inspect or generate code based on a type’s AST (derive macro)
• You want compile-time validation or embedding of domain-specific languages
• You need to add behavior to functions or items via attributes

Best practices

• Prefer generics for type abstraction before using macros
• Keep macros as small and focused as possible
• Use unique internal identifiers to preserve hygiene and avoid captures
• Document and test expanded output with cargo expand and unit tests
• Avoid heavy proc-macros for trivial tasks to reduce compile-time overhead

Example use cases

• Declarative macro to construct collections with ergonomic syntax (like my_vec!)
• Derive macro to implement a Builder pattern for structs with compile-time checks
• Function-like proc-macro that validates and embeds domain-specific strings (e.g., SQL) at compile time
• Attribute macro to cache expensive function results with OnceLock or memoization
• Generate repetitive boilerplate for FFI bindings or serialization implementations