Embedded agents — Claude Agent SDK

Which skill. Two skills run the same agent directories. This one runs them through the Claude Agent SDK, which starts the Claude Code engine as a subprocess: built-in file and shell tools, Claude Code's own system prompt, its skill and MCP loading, and a long-lived Node host to run on. The embedded-agents-messages-api skill runs them on the Claude API with the Anthropic SDK's tool runner, in the app's own process: only the tools the wrapper gives the agent, no subprocess, any Node host. It is the default for a new product. Use this one when the agent needs what only the engine has, or when the product already runs it.

Read the product's own agent instructions first (its root AGENTS.md or CLAUDE.md), and tell any subagent you spawn for this work to read them too: their rules on secrets, environment variables, validation, callers, tests and release apply to everything here. This skill adds how to run Claude agents inside the app. reference/playbook.md is the full playbook, with the measurement behind every option — read it before changing the wrapper's contract or explaining it in depth.

The model: the app owns the request, the caller, storage and the UI; the agent owns reasoning and tools. An agent is a directory, .claude/agents/<name>/, holding AGENTS.md (its instructions — its only instruction file), and optionally knowledge/, agent-local skills in .claude/skills/, and .mcp.json. One wrapper function, askAgent, runs any of them. No agent name appears in code.

1. First use: install the wrapper

Search the code for askAgent. If it exists, skip to § 2. Otherwise:

1. No app yet? Create the smallest Next.js App Router app in TypeScript (what this skill's files are written for) and nothing the user did not ask for — no database, sign-in or billing for a local prototype.
2. Install what is missing: npm i @anthropic-ai/claude-agent-sdk zod server-only and npm i -D vitest.
3. Copy, changing only import paths: