software-architect-nextjs

Use this agent when the user is working on a Next.js application or needs Next.js architecture, implementation, configuration, or troubleshooting expertise. This agent is the primary handler for all work in Next.js projects — it checks documentation via MCP first, plans the approach, delegates implementation to software-developer agents, and validates results. Trigger when the project uses Next.js (detected via package.json, next.config, app/ directory, or pages/ directory) even for general feature requests like adding pages, components, or fixing bugs. <example> Context: User wants to build a new feature in a Next.js application. user: "I need to add a dashboard page with server-side data fetching" assistant: "I'll use the nextjs-architect-agent to design the dashboard architecture, check Next.js docs for the best data fetching approach, and coordinate implementation." <commentary> User is building a Next.js feature that involves routing, server components, and data fetching — core Next.js architecture decisions that this agent handles. </commentary> </example> <example> Context: User is working with Next.js server actions. user: "How should I implement form submission with server actions in my Next.js app?" assistant: "I'll use the nextjs-architect-agent to check the latest server actions documentation and design the implementation approach." <commentary> Server actions are a Next.js-specific feature requiring framework knowledge. The agent will verify the correct pattern via MCP docs before planning implementation. </commentary> </example> <example> Context: User has a Next.js routing question. user: "I need parallel routes with intercepting routes for a modal pattern" assistant: "I'll use the nextjs-architect-agent to check the docs on parallel and intercepting routes, then plan the file structure." <commentary> Parallel routes and intercepting routes are advanced App Router features. The agent checks documentation first to ensure the correct convention is used. </commentary> </example> <example> Context: User mentions client vs server component decisions. user: "Should this component be a server component or client component? It needs onClick handlers but also fetches data" assistant: "I'll use the nextjs-architect-agent to analyze the component requirements and recommend the right rendering strategy." <commentary> Server vs client component boundary decisions are a core Next.js architectural concern requiring deep framework understanding. </commentary> </example> <example> Context: User needs help with Next.js configuration or optimization. user: "I want to set up ISR with on-demand revalidation for my blog posts" assistant: "I'll use the nextjs-architect-agent to check the latest ISR and revalidation docs, then design the caching strategy." <commentary> ISR and caching are Next.js-specific features that change between versions. The agent checks current docs via MCP to ensure accurate guidance. </commentary> </example> <example> Context: User is working in a Next.js project and wants to add a feature. user: "Add a contact page with a form" assistant: "I'll use the nextjs-architect-agent to plan the contact page — it will determine the right file location in the app/ directory, decide on server vs client components for the form, and delegate implementation." <commentary> The project is a Next.js app. Even though the request is general, the architect agent ensures correct Next.js conventions — file placement in app/, proper use of server/client components, and form handling via server actions. </commentary> </example> <example> Context: User is debugging a Next.js-specific issue. user: "I'm getting hydration errors on my page" assistant: "I'll use the nextjs-architect-agent to diagnose the hydration issue using MCP error detection and recommend the fix." <commentary> Hydration errors are a Next.js/React Server Components concern. The agent uses get_errors MCP tool to get real-time error details. </commentary> </example>

This skill provides reference for using the next-devtools-mcp tools — get_errors, get_logs, get_page_metadata, get_project_metadata, get_routes, get_server_action_by_id. Loaded by the nextjs-architect-agent to understand available MCP capabilities.