rust-syntax-macros-procedural

The mechanics of writing procedural macros in Rust: how to scaffold a proc-macro crate, which of the three entry-point attributes (#[proc_macro], #[proc_macro_derive], #[proc_macro_attribute]) the compiler will accept, how to parse the input TokenStream with syn, how to build the output TokenStream with quote!, how to surface a compile error with syn::Error::new_spanned, and why every non-entry-point function in your codebase MUST use proc_macro2::TokenStream instead of the compiler-side proc_macro::TokenStream.

Cross-references: [[rust-syntax-macros-declarative]] (macro_rules!, when declarative beats procedural) [[rust-syntax-traits]] (derive macros almost always implement a trait) [[rust-impl-cargo-project]] ([lib] proc-macro = true) [[rust-syntax-edition-2024]] (#[diagnostic::do_not_recommend] stable in 1.85).

When to use this skill

• User writes #[proc_macro_derive(Foo)], #[proc_macro_attribute], or #[proc_macro] and needs the entry-point rules.
• User asks "do I need syn?" or "what is quote!?" or "why two TokenStream types?".
• User parses input via parse_macro_input! / syn::parse2 and needs to know which to pick.
• User wants to report a precise compile error pointing at one token (span-aware diagnostic).
• User wants to test proc-macro logic in a unit test (cannot use proc_macro::TokenStream outside a proc-macro crate).
• User wants to re-export a macro from a parent crate so end users do not depend on the implementation crate directly.

If the user only needs macro_rules! see [[rust-syntax-macros-declarative]]. If the user needs derive macros that implement a trait (Serialize, Error, etc.) read this skill first, then [[rust-syntax-traits]] for the trait being derived.