Non-negotiable rules:

1. Read references/stack.md first.
2. Then load only the references needed for the actual task.
3. Keep user-visible text translated.
4. Keep data access in the project’s API-client pattern.
5. Keep the heavy Next.js guidance in references/, not inline here.

nextjs

Inputs

• $request: The Next.js page, component, routing, caching, or testing task

Goal

Route Next.js work through the project's App Router conventions so implementation follows the established patterns for data access, metadata, localization, and rendering boundaries.

Step 0: Read the stack contract

Always start with:

• references/stack.md

That establishes the locked decisions for runtime, config, and project-wide Next.js patterns.

Success criteria: The project’s Next.js architecture assumptions are explicit before editing.

Step 1: Load only the relevant references

Use the routing table to pick reference files that match the task. Do not bulk-load the full reference tree.

Task	Read
Folder layout, file conventions, project structure	references/folder-structure.md
Route groups, dynamic routes, parallel/intercepting routes	references/routing.md
Creating or editing a page or layout	references/page-checklist.md
Component structure, client/server boundaries	references/component-anatomy.md
Data fetching, API client, fetch wrappers	references/api-client-pattern.md
Server actions, mutations, revalidation	references/server-actions.md
Caching, ISR, on-demand revalidation	references/caching-strategy.md
Translations, locale routing, message files	references/i18n-conventions.md
Error boundaries, error.tsx, not-found.tsx	references/error-handling.md
Structured logging, log levels	references/logging.md
Analytics, event tracking, consent	references/tracking.md
Authentication, middleware, session	references/auth.md
Security headers, CSP, CSRF, rate limiting	references/security.md
SEO, metadata, Open Graph, sitemap	references/seo.md
Accessibility, ARIA, keyboard navigation	references/accessibility.md
Unit tests, component tests	references/testing-unit.md
E2E tests, Playwright	references/testing-e2e.md
Machine-readable output, JSON-LD, structured data	references/machine-readable.md

Multiple tasks? Read multiple files. The references are self-contained.

Success criteria: The active context only contains the task-relevant Next.js conventions.

Step 2: Implement with the core Next.js guardrails

Keep these rules active:

• async request-bound APIs are awaited
• data access uses the project API client, not ad hoc fetches or ORM calls
• visible strings go through the localization layer
• pages and layouts stay server-first unless a leaf component truly needs client mode
• metadata and SEO requirements stay attached to page work

Success criteria: The change fits the project’s App Router architecture instead of generic framework defaults.

Step 3: Verify the affected surface

Use the narrowest relevant verification:

• unit tests
• e2e tests
• linting or type checks
• page or route smoke validation

Success criteria: The changed Next.js surface still behaves correctly.

Guardrails

• Do not inline the whole Next.js handbook in SKILL.md.
• Do not skip references/stack.md.
• Do not hardcode user-facing strings when i18n is required.
• Do not bypass the project’s API-client and caching conventions.
• Do not add disable-model-invocation; this is a normal domain skill.

When To Load References

• references/stack.md Always.

• then only the task-relevant files under references/

Output Contract

Report:

1. which Next.js references were loaded
2. the architecture pattern chosen
3. the change made
4. the verification run