WordPress plugin: rewrite rules & flush

The single most consistently-mishandled topic in WP plugin code by AI assistants and inexperienced developers. The pattern that "works" — call flush_rewrite_rules() after add_rewrite_rule() — is correct but the WHEN matters more than the WHAT. Calling it once is right; calling it on every page load wrecks performance.

This skill covers when and how to register custom URL rewrites and the discipline around flushing.

When to use this skill

Trigger when ANY of the following is true:

• Adding a custom URL endpoint (/api/v1/..., /dashboard/orders/, /track/<token>/).
• Registering a CPT or taxonomy with a 'rewrite' argument that creates new permalink structures.
• Adding a "REST-but-pretty-URL" pattern that uses WP's rewrite engine instead of register_rest_route.
• Debugging "my new permalink returns 404 even though the post exists".
• Reviewing code where you see flush_rewrite_rules() or add_rewrite_rule() — verify the placement.

Mental model — rewrite_rules is a cached option

WordPress's permalink engine works in two passes: