Agent-Skills.md

Agent Skills: Production Next.js chatbots

Production-grade Next.js chatbot builder. Covers tool calling with human-in-the-loop (HITL) approval, PostgreSQL session persistence, GDPR consent gating, SQL-first search, per-tool UI rendering, message feedback, and follow-up suggestions. Use when building chat apps, conversational AI interfaces, customer support bots, or any chatbot needing database-backed sessions, tool approval workflows, consent gating, or custom tool output components.

UncategorizedID: laguagu/claude-code-nextjs-skills/nextjs-chatbot

Repository

laguagu/claude-code-nextjs-skills
laguaguLicense: MIT
217

Install this agent skill to your local

pnpm dlx add-skill https://github.com/laguagu/claude-code-nextjs-skills/tree/HEAD/skills/nextjs-chatbot

Skill Files

Browse the full folder contents for nextjs-chatbot.

Download Skill

Loading file tree…

skills/nextjs-chatbot/SKILL.md

Skill Metadata

Name
nextjs-chatbot
Description
"Production Next.js web-chat integration: tool approval, persisted conversations, tool result UI, grounded retrieval, follow-up suggestions and embedded widgets. Use when building or debugging a web chatbot that needs these features. Use ai-app for scaffolding and ai-sdk for general SDK APIs; multi-platform bots use Chat SDK."

Production Next.js chatbots

Use this skill for web-chat integration: persisted conversations, tool approval, tool result UI and an embedded widget. Use ai-app for scaffolding, ai-sdk to resolve the SDK version, and ai-elements for component contracts. For multi-platform messaging, consult Chat SDK.

Keep the project's stack. Choose the model, reasoning setting, storage and client state from the product's quality, latency and privacy requirements. A chatbot does not inherently need PostgreSQL, Zustand, MCP servers or every message action. When a new project has not decided, the defaults are Bun, ai-elements on shadcn/ui, Drizzle + PostgreSQL for server-side history, and a fast model with low or no reasoning effort, because chat latency is the product.

Read the installed node_modules/ai/docs/04-ai-sdk-ui/ for persistence, tool usage, errors and resume streams; use the package's types and src/ when shipped for exact contracts. The linked ai-sdk.dev pages are the online fallback and describe the newest major.

Integration contracts

  • Match ai, @ai-sdk/react and provider versions before writing API calls. Use ai-sdk-7 for v7 and ai-sdk-6 for existing v6 projects; core callback renames do not imply renaming the separate useChat.onFinish.
  • Authenticate conversation access, validate request data and authorize tools on the server. Client history, context, model IDs and consent flags are untrusted; prompts cannot enforce tenant isolation or permissions.
  • Store validated UI messages with stable IDs when the full conversation UI must be restored. Convert model history through the installed SDK's helpers; keep required tool-call/result and provider reasoning relationships intact.
  • Determine what happens on cancellation, disconnect, reload and retries. Consuming a stream after disconnect still depends on the hosting lifetime; durable execution needs a supported durable runtime.
  • Log redacted diagnostics with a correlation ID. Return a safe public error for failed HTTP requests and in-stream failures; an error after headers have been sent cannot change the HTTP status. The UI stream masks ordinary errors by default; provider-executed tool errors can bypass onError, so check the tool error renderer too. A custom onError return value reaches the browser verbatim, and a non-2xx response reaches useChat onError with the raw response body as its message.
  • Verify actual proxy streaming and buffering configuration. SDK UI-message responses already send X-Accel-Buffering: no; streams you build yourself (NDJSON/SSE progress) need it and Cache-Control: no-store, no-transform. The header helps supported nginx setups; it does not guarantee that every host streams without buffering.

Chat surface

Keep the answer, relevant tool results and useful sources readable. Default layout: user messages in a right-aligned bg-muted bubble, assistant messages full width without a background, and the brand carried through to the scrollbar. Add feedback, regenerate, delete or suggestions when the product needs them; avoid a repeated “Answer” heading or an action toolbar on every message by default. Use the icons skill for icon choice and nextjs-shadcn for the surrounding interface.

Follow streamed output while the reader is at the bottom; preserve their place when they scroll away or load earlier history. Use an existing compatible scroll primitive when it fits; shadcn's Message Scroller is one option; anchor on the user's message so the reply streams below it. Render Markdown through the application's renderer (shadcn Typeset by default, see nextjs-shadcn) and verify nested lists, long links and code blocks.

Derive turn completion from useChat status (submitted/streaming) rather than a momentary gap between tools. Stop or isolate the generation before switching conversations. Browser storage must not make the first client render disagree with server-rendered consent or history.

Read for the feature

Exercise a second turn after restoring history, approval and denial, tool failure, cancellation, fast conversation switching and the deployed stream path. Report the behaviors actually checked.