Agent skill · software engineering · mohamed-hossam1
nextjs-cache-architecture
Use this skill whenever the user wants to design or implement caching in a Next.js 16+ App Router project — setting up the "use cache" directive, building a cache tag registry, wiring mutations to invalidation utilities, structuring Suspense boundaries for partial prerendering, handling personalized content near cache boundaries, choosing cacheLife profiles, calling cacheTag / updateTag / revalidateTag correctly, migrating from unstable_cache, or debugging stale or incorrectly fresh data. Trigger even when the user only describes their domain (e.g. "I have a posts table") and asks how to cache it properly.
Why this skill is useful
Adds templates and specific implementation details for caching in Next.js 16+ that aren't widely documented.
What it needs
About 6k tokens when loaded. Last updated 2026-05-30. 8 stars on the source repository.
What this skill does
Next.js Cache Architecture Architect caching in a Next.js 16+ App Router project from day one — not just dropping "use cache" where it happens to fit, but structuring the tag registry, revalidation utilities, Suspense boundaries, and mutation wiring so the cache stays correct as the codebase grows. How to use this skill Apply every rule and template below to the user's actual project. Replace placeholders like [Entity] and [collection] with names from their codebase before writing any code. Where to look next Most implementations only need this file. Load a reference when the task calls for it. If the user is... Read ------------------------------------------------------------------------------------------------------- --------------------------------------------- Asking how cache keys are derived, what cacheLife profiles mean, or hitting a "use cache" limitation references/core-concepts.md Caching anything that depends on a logged-in user references/personalized-content.md Reporting stale data, or doing a final review pass references/debugging-and-checklist.md Migrating an existing codebase off unstablecache references/migration-from-unstable-cache.md Drop-in templates in assets/ (rename placeholders to match the user's codebase): assets/tags.ts → lib/cache/tags.ts assets/revalidate.ts → lib/cache/revalidate.ts assets/SuspenseOnSearchParams.tsx → components/SuspenseOnSearchParams.tsx The architecture in one breath A correct cache implementation has three load-bearing pieces. Build all three on day one — adding them later is much harder than getting them right up front. 1. Tag registry (lib/cache/tags.ts) — every tag string lives here. No raw strings anywhere else. 2. Revalidation utilities (lib/cache/revalidate.ts) — every updateTag() lives here. Mutations import from this file. 3. Cache placement on data, not on pages — "use cache" goes on data-fetching functions or cached child components. Page components orchestrate Suspense boundaries; the children fetch. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills mohamed-hossam1/nextjs-cache-architecture--ad47f0