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

Mohamed Hossam — Mon, 11 May 2026 19:14:54 +0000

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.

Forem: Mohamed Hossam

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

What I built

Why an agent skill and not a blog post

Install it