Non-negotiable rules:
- Read
references/stack.md first.
- Read the repository's
AGENTS.md, CLAUDE.md, and closest module map when present. They define
the real route families, localization, design/theme, auth, transport, and test contracts.
- Read the application
package.json, resolved lockfile, and the installed version-matched Next.js
docs under that package's node_modules/next/dist/docs/ before applying version-specific guidance.
- Follow the installed version unless the user explicitly requests an upgrade. Never upgrade,
downgrade, or switch release channels during unrelated work.
- Then load only the references needed for the actual task.
- Keep user-visible text translated and all backend traffic in the project's shared API transport.
- 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:
That establishes the locked decisions for runtime, config, and project-wide Next.js patterns.
For a new application, version recommendation, or framework upgrade, also read:
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 |
| New application, version choice, Next.js 15 to 16 upgrade |
references/upgrading.md |
| 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 |
| Polling, pagination, autosave, stale async responses |
references/client-async-state.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 |
| Agent-ready public pages, trust anchors, 404s, llms.txt |
references/agent-readiness.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 backend fetches or ORM calls
- RSC/server calls use the project's server domain modules; approved interactive clients use its
browser domain modules; both converge on the shared transport
- 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
- authentication and authorization come from the verified backend session, never browser-controlled
role or workspace headers
Success criteria: The change fits the project’s App Router architecture instead of generic framework defaults.
Step 3: Verify the affected surface
Run the repository's own scripts at the level that can prove the behavior:
- lint,
next typegen, typecheck, and focused unit/component tests
- a built production Next.js server for HTTP status, headers, raw HTML, negotiation, redirects, and
browser behavior
- the canonical integrated Compose stack when Laravel session, CSRF, queues, billing, downloads,
webhooks, or another backend boundary is involved
Direct handler invocation cannot prove production HTTP behavior. A frontend run with Laravel mocked
is not a full-stack test.
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 replace or relocate the project's authentication/session authority during unrelated work.
- Do not add or remove theme support contrary to the project's locked design contract.
- Do not apply Next.js 16-only APIs to an older project unless the task includes the upgrade.
- Do not downgrade a project that already declares or resolves Next.js 16.3.x.
- Do not recommend
next@canary or another prerelease unless the user explicitly opts into that
release channel.
- Do not add
disable-model-invocation; this is a normal domain skill.
For a public-page task, also load agent-readiness.md, page-checklist.md, seo.md,
machine-readable.md, and testing-e2e.md. Do not call it complete until the applicable raw-HTML, canonical identity,
structured-data, trust-page, HTML/Markdown 404, and live HTTP checks pass. Report external search
engine and brand-discoverability work separately from code completion.
When To Load References
references/stack.md
Always.
references/upgrading.md
New applications, version choices, and framework upgrades.
then only the task-relevant files under references/
Output Contract
Report:
- the declared and resolved Next.js version and which installed documentation was consulted
- which Next.js references were loaded
- the repository architecture or project profile followed
- the change made
- the verification run at each applicable test level
- remaining deployment, live-endpoint, integration, or external-discoverability work
1---
2name: nextjs
3description: |
4 Build or review a Next.js App Router surface against the project's installed framework version
5 and established architecture. Covers pages, layouts, async request APIs, server and browser API
6 clients, authentication, client concurrency, Route Handlers, metadata, i18n, accessibility,
7 machine-readable content, and layered testing. Use when a task touches Next.js and must preserve
8 project-specific decisions such as the resolved framework version, backend session protocol,
9 canonical domain, and locked visual theme.
10allowed-tools:
11 - Bash
12 - Read
13 - Write
14 - Edit
15 - Grep
16metadata:
17 source: https://skillmd.com/skills/ulpi-io/nextjs
18 version: "3.0.0"
19 argument-hint: "[Next.js page, component, route, or caching task]"
20---
21
22<EXTREMELY-IMPORTANT>
23This skill is a routing shell over the Next.js reference set, not the full framework manual.
24
25Non-negotiable rules:
261. Read `references/stack.md` first.
272. Read the repository's `AGENTS.md`, `CLAUDE.md`, and closest module map when present. They define
28 the real route families, localization, design/theme, auth, transport, and test contracts.
293. Read the application `package.json`, resolved lockfile, and the installed version-matched Next.js
30 docs under that package's `node_modules/next/dist/docs/` before applying version-specific guidance.
314. Follow the installed version unless the user explicitly requests an upgrade. Never upgrade,
32 downgrade, or switch release channels during unrelated work.
335. Then load only the references needed for the actual task.
346. Keep user-visible text translated and all backend traffic in the project's shared API transport.
357. Keep the heavy Next.js guidance in `references/`, not inline here.
36</EXTREMELY-IMPORTANT>
37
38# nextjs
39
40## Inputs
41
42- `$request`: The Next.js page, component, routing, caching, or testing task
43
44## Goal
45
46Route Next.js work through the project's App Router conventions so implementation follows the established patterns for data access, metadata, localization, and rendering boundaries.
47
48## Step 0: Read the stack contract
49
50Always start with:
51
52- `references/stack.md`
53
54That establishes the locked decisions for runtime, config, and project-wide Next.js patterns.
55
56For a new application, version recommendation, or framework upgrade, also read:
57
58- `references/upgrading.md`
59
60**Success criteria**: The project’s Next.js architecture assumptions are explicit before editing.
61
62## Step 1: Load only the relevant references
63
64Use the routing table to pick reference files that match the task. Do not bulk-load the full reference tree.
65
66| Task | Read |
67|------|------|
68| New application, version choice, Next.js 15 to 16 upgrade | `references/upgrading.md` |
69| Folder layout, file conventions, project structure | `references/folder-structure.md` |
70| Route groups, dynamic routes, parallel/intercepting routes | `references/routing.md` |
71| Creating or editing a page or layout | `references/page-checklist.md` |
72| Component structure, client/server boundaries | `references/component-anatomy.md` |
73| Data fetching, API client, fetch wrappers | `references/api-client-pattern.md` |
74| Polling, pagination, autosave, stale async responses | `references/client-async-state.md` |
75| Server actions, mutations, revalidation | `references/server-actions.md` |
76| Caching, ISR, on-demand revalidation | `references/caching-strategy.md` |
77| Translations, locale routing, message files | `references/i18n-conventions.md` |
78| Error boundaries, error.tsx, not-found.tsx | `references/error-handling.md` |
79| Structured logging, log levels | `references/logging.md` |
80| Analytics, event tracking, consent | `references/tracking.md` |
81| Authentication, middleware, session | `references/auth.md` |
82| Security headers, CSP, CSRF, rate limiting | `references/security.md` |
83| SEO, metadata, Open Graph, sitemap | `references/seo.md` |
84| Agent-ready public pages, trust anchors, 404s, llms.txt | `references/agent-readiness.md` |
85| Accessibility, ARIA, keyboard navigation | `references/accessibility.md` |
86| Unit tests, component tests | `references/testing-unit.md` |
87| E2E tests, Playwright | `references/testing-e2e.md` |
88| Machine-readable output, JSON-LD, structured data | `references/machine-readable.md` |
89
90Multiple tasks? Read multiple files. The references are self-contained.
91
92**Success criteria**: The active context only contains the task-relevant Next.js conventions.
93
94## Step 2: Implement with the core Next.js guardrails
95
96Keep these rules active:
97
98- async request-bound APIs are awaited
99- data access uses the project API client, not ad hoc backend fetches or ORM calls
100- RSC/server calls use the project's server domain modules; approved interactive clients use its
101 browser domain modules; both converge on the shared transport
102- visible strings go through the localization layer
103- pages and layouts stay server-first unless a leaf component truly needs client mode
104- metadata and SEO requirements stay attached to page work
105- authentication and authorization come from the verified backend session, never browser-controlled
106 role or workspace headers
107
108**Success criteria**: The change fits the project’s App Router architecture instead of generic framework defaults.
109
110## Step 3: Verify the affected surface
111
112Run the repository's own scripts at the level that can prove the behavior:
113
114- lint, `next typegen`, typecheck, and focused unit/component tests
115- a built production Next.js server for HTTP status, headers, raw HTML, negotiation, redirects, and
116 browser behavior
117- the canonical integrated Compose stack when Laravel session, CSRF, queues, billing, downloads,
118 webhooks, or another backend boundary is involved
119
120Direct handler invocation cannot prove production HTTP behavior. A frontend run with Laravel mocked
121is not a full-stack test.
122
123**Success criteria**: The changed Next.js surface still behaves correctly.
124
125## Guardrails
126
127- Do not inline the whole Next.js handbook in `SKILL.md`.
128- Do not skip `references/stack.md`.
129- Do not hardcode user-facing strings when i18n is required.
130- Do not bypass the project’s API-client and caching conventions.
131- Do not replace or relocate the project's authentication/session authority during unrelated work.
132- Do not add or remove theme support contrary to the project's locked design contract.
133- Do not apply Next.js 16-only APIs to an older project unless the task includes the upgrade.
134- Do not downgrade a project that already declares or resolves Next.js 16.3.x.
135- Do not recommend `next@canary` or another prerelease unless the user explicitly opts into that
136 release channel.
137- Do not add `disable-model-invocation`; this is a normal domain skill.
138
139For a public-page task, also load `agent-readiness.md`, `page-checklist.md`, `seo.md`,
140`machine-readable.md`, and `testing-e2e.md`. Do not call it complete until the applicable raw-HTML, canonical identity,
141structured-data, trust-page, HTML/Markdown 404, and live HTTP checks pass. Report external search
142engine and brand-discoverability work separately from code completion.
143
144## When To Load References
145
146- `references/stack.md`
147 Always.
148
149- `references/upgrading.md`
150 New applications, version choices, and framework upgrades.
151
152- then only the task-relevant files under `references/`
153
154## Output Contract
155
156Report:
157
1581. the declared and resolved Next.js version and which installed documentation was consulted
1592. which Next.js references were loaded
1603. the repository architecture or project profile followed
1614. the change made
1625. the verification run at each applicable test level
1636. remaining deployment, live-endpoint, integration, or external-discoverability work