I Built a Production-Grade Next.js Caching Skill Because the Docs Let Me Down

The Next.js docs cover caching basics. They don't tell you what to do when your page has dynamic routes, search params, or personalized content.

I ran into this firsthand. I was building a production app and kept asking myself:

• If the page has searchParams, does "use cache" still work?
• Where do I put cookies() if I can't call it inside a cached function?
• How do I invalidate one product without nuking the entire cache?
• Should the page component fetch data or just orchestrate?

The docs had none of this. So I figured it out myself — through trial, error, and a lot of broken builds.

What I built

I turned everything I learned into an agent skill: nextjs-cache-architecture.

It's not a tutorial. It's a set of rules and templates your AI agent loads once and applies to your actual codebase — replacing placeholders with your real entity and collection names.

The skill covers:

• A 5-layer mental model (static shell → cached content → entity pages → personalized content → invalidation)
• A centralized tag registry in lib/cache/tags.ts — raw tag strings never written anywhere else
• A revalidation utility layer in lib/cache/revalidate.ts — updateTag() called from one place only
• SuspenseOnSearchParams — a wrapper that fixes Suspense not re-triggering on client-side navigation when only search params change
• Personalized content pattern — read cookies() outside the cache boundary, pass primitives as props
• The single question that decides whether you need an entity tag factory at all

Why an agent skill and not a blog post

A blog post gives you concepts. A skill gives your AI agent executable rules it can apply to your project right now, in any session, without you re-explaining anything.

Next.js caching is architecture — you need to design it upfront, not retrofit it. This skill enforces that from the first line of code.

Install it

npx skills add mohamed-hossam1/nextjs-cache-architecture

Then invoke it with:

/nextjs-cache-architecture

Works with Claude Code, Cursor, Codex, Gemini CLI, and 50+ other agents.

Feedback welcome — especially if you've hit caching edge cases the skill doesn't cover yet.