app-router — Claude Code skill: Next.js App Router conventions
Skill for creating routes, layouts, loading states and error boundaries in Next.js App Router. Teaches the agent file structure conventions and routing patterns.
MIT 153 installs ★ 3,785 updated 2026-10-25
npx skills add davepoon/buildwithclaude --skill app-router -a claude-codeWhat app-router does
The skill explains Next.js App Router file conventions: which files to create (page.tsx, layout.tsx, loading.tsx, error.tsx), how to structure dynamic routes ([slug]), catch-all segments ([...slug]) and route groups ((folder)). It includes examples of page components, nested layouts, accessing route parameters via params, metadata configuration and parallel routes.
It triggers when you ask the agent to create a route, add a page, set up a layout or handle errors. Without it, the agent might default to outdated pages/ patterns instead of app/.
Installation via npx skills add copies the skill file into the platform directory.
What it helps with
- create a Next.js route with correct folder structure
- add a dynamic route with parameters
- set up nested layouts with shared UI
- handle loading states with Suspense
- add error boundaries for route segments
Example prompts for the agent
- Create a
/blog/[slug]route with dynamic parameter - Set up a dashboard layout with sidebar
- Add error handling and loading state for
/products
How to install app-router
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill app-router -a claude-code2Manually: put the files in place
~/.claude/skills/app-router/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/app-router/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill app-router -a codex2Manually: put the files in place
.agents/skills/app-router/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill app-router -a cursor2Manually: put the files in place
.cursor/skills/app-router/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install davepoon/buildwithclaude plugins/nextjs-expert/skills/app-router2Manually: put the files in place
.github/skills/app-router/SKILL.md1Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill app-router -a gemini-cli2Platform CLI
gemini skills install https://github.com/davepoon/buildwithclaude --path plugins/nextjs-expert/skills/app-routerManually: put the files in place
.devin/skills/app-router/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add davepoon/buildwithclaude --skill app-router -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about app-router
How to install app-router in Claude Code?
Run npx skills add davepoon/buildwithclaude --skill app-router -a claude-code, the skill file will appear in ~/.claude/skills/app-router/SKILL.md.
What does app-router skill do?
It teaches the agent to create routes, layouts and error handling following Next.js App Router conventions — use app/ instead of pages/, name files and folders correctly, work with dynamic segments and route groups.
How does app-router differ from the old Next.js router?
App Router uses the app/ directory with file conventions (page.tsx, layout.tsx), supports React Server Components, built-in loading states via Suspense and nested layouts that preserve state across navigation.
Source text
SKILL.md · MIT
---
name: app-router
description: This skill should be used when the user asks to "create a Next.js route", "add a page", "set up layouts", "implement loading states", "add error boundaries", "organize routes", "create dynamic routes", or needs guidance on Next.js App Router file conventions and routing patterns.
version: 1.0.0
---
# Next.js App Router Patterns
## Overview
The App Router is Next.js's file-system based router built on React Server Components. It uses a `app/` directory structure where folders define routes and special files control UI behavior.
## Core File Conventions
### Route Files
Each route segment is defined by a folder. Special files within folders control behavior:
| File | Purpose |
|------|---------|
| `page.tsx` | Unique UI for a route, makes route publicly accessible |
| `layout.tsx` | Shared UI wrapper, preserves state across navigations |
| `loading.tsx` | Loading UI using React Suspense |
| `error.tsx` | Error boundary for route segment |
| `not-found.tsx` | UI for 404 responses |
| `template.tsx` | Like layout but re-renders on navigation |
| `default.tsx` | Fallback for parallel routes |
### Folder Conventions
| Pattern | Purpose | Example |
|---------|---------|---------|
| `folder/` | Route segment | `app/blog/` → `/blog` |
| `[folder]/` | Dynamic segment | `app/blog/[slug]/` → `/blog/:slug` |
| `[...folder]/` | Catch-all segment | `app/docs/[...slug]/` → `/docs/*` |
| `[[...folder]]/` | Optional catch-all | `app/shop/[[...slug]]/` → `/shop` or `/shop/*` |
| `(folder)/` | Route group (no URL) | `app/(marketing)/about/` → `/about` |
| `@folder/` | Named slot (parallel routes) | `app/@modal/login/` |
| `_folder/` | Private folder (excluded) | `app/_components/` |
## Creating Routes
### Basic Route Structure
To create a new route, add a folder with `page.tsx`:
```
app/
├── page.tsx # / (home)
├── about/
│ └── page.tsx # /about
└── blog/
├── page.tsx # /blog
└── [slug]/
└── page.tsx # /blog/:slug
```
### Page Component
A page is a Server Component by default:
```tsx
// app/about/page.tsx
export default function AboutPage() {
return (
<main>
<h1>About Us</h1>
<p>Welcome to our company.</p>
</main>
)
}
```
### Dynamic Routes
Access route parameters via the `params` prop:
```tsx
// app/blog/[slug]/page.tsx
interface PageProps {
params: Promise<{ slug: string }>
}
export default async function BlogPost({ params }: PageProps) {
const { slug } = await params
const post = await getPost(slug)
return <article>{post.content}</article>
}
```
## Layouts
### Root Layout (Required)
Every app needs a root layout with `<html>` and `<body>`:
```tsx
// app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
```
### Nested Layouts
Layouts wrap their children and preserve state:
```tsx
// app/dashboard/layout.tsx
export default function DashboardLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<div className="flex">
<Sidebar />
<main className="flex-1">{children}</main>
</div>
)
}
```
## Loading and Error States
### Loading UI
Create instant loading states with Suspense:
```tsx
// app/dashboard/loading.tsx
export default function Loading() {
return <div className="animate-pulse">Loading...</div>
}
```
### Error Boundaries
Handle errors gracefully:
```tsx
// app/dashboard/error.tsx
'use client'
export default function Error({
error,
reset,
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={reset}>Try again</button>
</div>
)
}
```
## Route Groups
Organize routes without affecting URL structure:
```
app/
├── (marketing)/
│ ├── layout.tsx # Marketing layout
│ ├── about/page.tsx # /about
│ └── contact/page.tsx # /contact
└── (shop)/
├── layout.tsx # Shop layout
└── products/page.tsx # /products
```
## Metadata
### Static Metadata
```tsx
// app/about/page.tsx
import { Metadata } from 'next'
export const metadata: Metadata = {
title: 'About Us',
description: 'Learn more about our company',
}
```
### Dynamic Metadata
```tsx
// app/blog/[slug]/page.tsx
export async function generateMetadata({ params }: PageProps): Promise<Metadata> {
const { slug } = await params
const post = await getPost(slug)
return { title: post.title }
}
```
## Key Patterns
1. **Colocation**: Keep components, tests, and styles near routes
2. **Private folders**: Use `_folder` for non-route files
3. **Route groups**: Use `(folder)` to organize without URL impact
4. **Parallel routes**: Use `@slot` for complex layouts
5. **Intercepting routes**: Use `(.)` patterns for modals
## Resources
For detailed patterns, see:
- `references/routing-conventions.md` - Complete file conventions
- `references/layouts-templates.md` - Layout composition patterns
- `references/loading-error-states.md` - Suspense and error handling
- `examples/dynamic-routes.md` - Dynamic routing examples
- `examples/parallel-routes.md` - Parallel and intercepting routes
© davepoon · MIT · davepoon/buildwithclaude