skills.rest
po4yka
po4ykaCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

rust-macros

Diagnose and fix Rust macro_rules and procedural macro errors with syn and quote.

2|1|Updated Aug 19, 2026
Search Tags:#macros#rust#proc-macro#syn#derive macro#macro_rules#cargo expand
One-click install
npx skills add https://github.com/po4yka/rust-skills --skill rust-macros-po4yka
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: rust-macros
Source: https://github.com/po4yka/rust-skills/tree/main/skills/rust-macros
Command: npx skills add https://github.com/po4yka/rust-skills --skill rust-macros-po4yka

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Rust macros fail with diagnostics that point at the invocation instead of the defect, and proc-macro crates impose structural rules (separate crate, no self-invocation, no non-macro exports) that produce cryptic errors. This Skill maps each rustc, cargo, and Clippy message to its root cause and fix for both declarative and procedural macros. ## Core Features & Use Cases - Symptom routing: A triage table maps errors like "cannot find macro in this scope", "recursion limit reached", "proc-macro derive panicked", and "cyclic package dependency" to the exact section that fixes them. - Expansion hygiene and paths: Rules for $crate, ::core, and ::facade absolute paths, macro hygiene boundaries, fragment specifier follow sets, and keeping caller expressions out of unsafe blocks. - Derive crate architecture: Facade/derive crate split, exact version pinning, legal dev-dependency back edges, per-field generic bounds, and syn 2 to syn 3 migration with a renamed-items table. - Use Case: A derive macro compiles in your workspace but fails downstream with E0405 "cannot find trait in module facade". The Skill identifies the missing leading :: on emitted paths and shows the integration test that catches it. ## Quick Start Ask the agent to diagnose why your macro_rules macro fails with "cannot find macro in this scope" or to review a syn-based derive macro before release.

Frequently Asked Questions about rust-macros

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix "cannot find macro in this scope" in Rust?▼

A macro_rules definition must appear before its use in source order, and macros do not cross module boundaries by default. Add pub(crate) use name; after the definition to reach it by path, or use #[macro_use] on the module for crate-wide scope.

How do I write a derive macro with syn and quote?▼

Create a crate with proc-macro = true, depend on syn 3, quote 1, and proc-macro2 1, and keep the #[proc_macro_derive] entry point thin. Parse with syn::parse_macro_input!, put logic in a function returning syn::Result, and map errors with into_compile_error instead of panicking.

Why does my derive macro fail with "cyclic package dependency"?▼

The facade crate already depends on the derive crate, so a normal dependency back from derive to facade closes a cycle that cargo rejects from the manifests alone. Move the back edge to [dev-dependencies], which is legal and lets the derive crate test itself from tests/.

Should I use syn 2 or syn 3 for a proc macro?▼

Run cargo tree --locked -e normal,build -i syn and use the major the tree already builds; when both or neither appear, use syn 3. Syn-2 code fails on syn 3 with E0599 or E0609 on renamed items like Type::BareFn, Signature::unsafety, and Arm::guard.

Why does my macro work in my crate but fail in downstream crates?▼

Emitted paths resolve in the caller's module, so a bare or relative path like facade::Trait gets captured by the caller's local items. Emit absolute paths starting with $crate::, ::core::, or ::facade::, and add an integration test in tests/ that shadows those names.

When should I avoid writing a Rust macro?▼

Prefer a generic function for one body over many types, const fn for build-time constants, build.rs with include! for schema-generated code, and cfg_select! for per-target item selection. Macros cost compile time, a second crate for proc macros, and diagnostics that point at the invocation.

Related Skills

Explore More Software Engineering Skills→
awfixers-stuffawfixers-stuff

cargo-workflows

Manage Cargo workspaces, feature flags, build scripts, caching, testing, and dependency audits for Rust projects.

Official
Intermediate
edgeandnodeedgeandnode

Code Checking

Validate Rust and TypeScript code changes using cargo and Justfile tasks.

Official
Intermediate
avbelavbel
2

power-rust

Applies five prompt patterns that reduce common bugs in LLM-generated Rust code.

Community
Intermediate
lazygopherslazygophers
4

macros

Guide development of Rust declarative, procedural, and derive macros.

Official
Advanced