build-agent
Scaffold and grow AI-agent applications. This skill is stack-agnostic: it
helps you choose a framework, then builds the agent loop, tools, API surface,
UI, observability, and deployment to match the user's real requirements.
Operating principle: verify before you build
Agent frameworks move fast. Never rely on memory for framework APIs. Before
writing framework code, pull live docs in this order:
- Context7 MCP (if available) —
resolve-library-id → query-docs.
- Official
llms.txt / llms-full.txt / .md via WebFetch — see
references/frameworks/* for the canonical URLs.
- The installed package itself — read
node_modules/<pkg> or the Python
package source; the user's pinned version is the source of truth.
The references/ tree here is a thin glossary + link index, deliberately
kept small so it does not go stale. It tells you what exists and where the real
docs are — not the full API. Treat any code snippet in references as
illustrative, then confirm against live docs.
If the host agent already has Context7, WebSearch, zread, or a relevant skill —
use it. Don't reinvent retrieval.
Step 1 — Determine the entry mode
Decide which of these you're in, then jump to the matching workflow:
| Situation |
Mode |
Workflow |
| Empty/near-empty repo, or user says "from scratch" |
Interview |
workflows/from-scratch.md |
| Existing project with code |
Detect |
workflows/from-existing.md |
| User explicitly asks to (re)interview |
Interview |
workflows/from-scratch.md |
Quick check: list the repo, look for package.json / pyproject.toml /
wrangler.jsonc / go.mod. Nothing meaningful → Interview. Something there →
Detect the techstack first, confirm it with the user, then only ask what the
code can't answer.
Step 2 — Interview deeply (when in Interview mode)
Use the host's ask-user tool. Don't ask one shallow question — gather as much
as possible across these dimensions. Follow workflows/from-scratch.md for the
full question bank. Cover at minimum:
- Purpose / use case — what should the agent do? (RAG assistant, coding
agent, workflow automation, customer support, research, multi-agent system…)
- Language — TypeScript / Python / Go / other.
- Framework — see the chooser below; recommend, don't impose.
- Architecture — single agent, supervisor/multi-agent, graph/state machine,
human-in-the-loop, durable/long-running, streaming vs batch.
- Model + provider — Claude / GPT / Gemini / open models; direct or via a
gateway (OpenRouter / AnyRouter / AI gateway).
- Tools / integrations — what external actions (search, code exec, DB, MCP
servers, APIs) the agent needs.
- UI/UX — chat UI, dashboard, headless API only, CLI, embedded widget.
- Persistence / memory — conversation state, vector store, checkpointing.
- Observability — tracing, evals, cost/latency tracking (see
references/concepts/tracking-observability.md).
- Deploy target — Docker, VM, k3s/Kubernetes, a cloud (AWS/GCP/Azure),
Cloudflare Workers, Vercel, serverless.
Restate the assembled requirements back to the user before scaffolding.
Step 3 — Choose the framework
Match the dominant requirement to a framework. Full notes in
references/frameworks/.
| If the user wants… |
Lean toward |
Lang |
| Stateful graphs, supervisor/multi-agent, human-in-loop, checkpointing |
LangGraph |
Py / TS |
| Opinionated "deep" planning agent (subagents, file tools, todo) on top of LangGraph |
DeepAgents |
Py / TS |
| Web app with streaming chat, tool calls, generative UI; Next.js/React |
Vercel AI SDK |
TS |
| Edge-native, durable, stateful agents that scale to zero |
Cloudflare Agents SDK (Durable Objects) |
TS |
| Provider-agnostic, type-safe streaming/tools/structured output in any TS app |
TanStack AI |
TS |
| Google-ecosystem, Gemini-first, code-first multi-agent with eval tooling |
Google ADK |
Py / Java |
| Build on the same harness Claude Code uses; subagents, MCP, hooks, permissions |
Claude Agent SDK |
Py / TS |
Mixed needs are common (e.g. LangGraph backend + AI SDK frontend, or Claude
Agent SDK behind a Cloudflare Worker). Compose; don't force one box.
Step 4 — Scaffold
Build the minimum that runs, then layer on. Match the chosen framework's
conventions exactly — pull its quickstart from live docs first.
Typical layers (build only what the requirements call for):
- Agent core — the loop / graph / state. Confirm the current API shape.
- Tools — define and wire tool calls. See
references/concepts/tool-calling.md.
- Model access — direct provider or gateway. See
references/concepts/ai-gateways.md for OpenRouter / AnyRouter / AI gateway.
- API surface — HTTP/streaming endpoints, or MCP server, per deploy target.
- UI/UX — chat or dashboard. For React, prefer the framework's own UI
primitives (AI SDK UI / AI Elements, Assistant UI, TanStack). For design
quality, defer to the host's frontend-design skill if present.
- Persistence & memory — checkpointer / store / vector DB.
- Observability — tracing + evals + cost tracking from day one.
- Deploy — Dockerfile / wrangler / k8s manifests / cloud config for the
chosen target.
After each layer: make it run, verify, then continue. Fail loud if a step is
skipped.
Step 5 — Agent-engineering concepts
These cut across frameworks — read the matching reference when relevant:
- Building skills for agents →
references/concepts/skills.md
- Tool calling (schemas, validation, parallel calls, MCP) →
references/concepts/tool-calling.md
- Tracking / observability (traces, evals, cost) →
references/concepts/tracking-observability.md
- AI gateways (OpenRouter, AnyRouter, AI gateway, BYOK) →
references/concepts/ai-gateways.md
- Model-specific prompting →
references/engineering/{claude,gemini,gpt}.md
Guardrails
- Don't pick a framework silently — recommend with a one-line why, let the user
decide.
- Don't embed stale API code — verify against live docs first.
- Build the smallest thing that runs before expanding.
- Keep secrets out of the repo; use env vars / the platform's secret store.
- Match the existing codebase's conventions when in Detect mode.
1---2name: build-agent3description: Build an AI-agent application end-to-end — from an empty repo or an existing codebase. Use when the user wants to "build an agent", "scaffold an agent app", "add an agent API", "build an agent UI/chat", "pick an agent framework", or set up tool calling, tracing, or an AI gateway. Interviews the user when requirements are unclear; detects the stack when a project already exists. Knows LangGraph, DeepAgents, Vercel AI SDK, Cloudflare Agents SDK, TanStack AI, Google ADK, and the Claude Agent SDK. Always verifies against live official docs (Context7 / llms.txt / WebFetch) before writing code.4---56# build-agent78Scaffold and grow AI-agent applications. This skill is **stack-agnostic**: it9helps you choose a framework, then builds the agent loop, tools, API surface,10UI, observability, and deployment to match the user's real requirements.1112## Operating principle: verify before you build1314Agent frameworks move fast. **Never rely on memory for framework APIs.** Before15writing framework code, pull live docs in this order:16171. **Context7 MCP** (if available) — `resolve-library-id` → `query-docs`.182. **Official `llms.txt` / `llms-full.txt` / `.md`** via WebFetch — see19 `references/frameworks/*` for the canonical URLs.203. **The installed package itself** — read `node_modules/<pkg>` or the Python21 package source; the user's pinned version is the source of truth.2223The `references/` tree here is a **thin glossary + link index**, deliberately24kept small so it does not go stale. It tells you *what exists and where the real25docs are* — not the full API. Treat any code snippet in references as26illustrative, then confirm against live docs.2728If the host agent already has Context7, WebSearch, zread, or a relevant skill —29use it. Don't reinvent retrieval.3031## Step 1 — Determine the entry mode3233Decide which of these you're in, then jump to the matching workflow:3435| Situation | Mode | Workflow |36|-----------|------|----------|37| Empty/near-empty repo, or user says "from scratch" | **Interview** | `workflows/from-scratch.md` |38| Existing project with code | **Detect** | `workflows/from-existing.md` |39| User explicitly asks to (re)interview | **Interview** | `workflows/from-scratch.md` |4041Quick check: list the repo, look for `package.json` / `pyproject.toml` /42`wrangler.jsonc` / `go.mod`. Nothing meaningful → Interview. Something there →43Detect the techstack first, confirm it with the user, then only ask what the44code can't answer.4546## Step 2 — Interview deeply (when in Interview mode)4748Use the host's **ask-user** tool. Don't ask one shallow question — gather as much49as possible across these dimensions. Follow `workflows/from-scratch.md` for the50full question bank. Cover at minimum:5152- **Purpose / use case** — what should the agent *do*? (RAG assistant, coding53 agent, workflow automation, customer support, research, multi-agent system…)54- **Language** — TypeScript / Python / Go / other.55- **Framework** — see the chooser below; recommend, don't impose.56- **Architecture** — single agent, supervisor/multi-agent, graph/state machine,57 human-in-the-loop, durable/long-running, streaming vs batch.58- **Model + provider** — Claude / GPT / Gemini / open models; direct or via a59 gateway (OpenRouter / AnyRouter / AI gateway).60- **Tools / integrations** — what external actions (search, code exec, DB, MCP61 servers, APIs) the agent needs.62- **UI/UX** — chat UI, dashboard, headless API only, CLI, embedded widget.63- **Persistence / memory** — conversation state, vector store, checkpointing.64- **Observability** — tracing, evals, cost/latency tracking (see65 `references/concepts/tracking-observability.md`).66- **Deploy target** — Docker, VM, k3s/Kubernetes, a cloud (AWS/GCP/Azure),67 Cloudflare Workers, Vercel, serverless.6869Restate the assembled requirements back to the user before scaffolding.7071## Step 3 — Choose the framework7273Match the dominant requirement to a framework. Full notes in74`references/frameworks/`.7576| If the user wants… | Lean toward | Lang |77|--------------------|-------------|------|78| Stateful graphs, supervisor/multi-agent, human-in-loop, checkpointing | **LangGraph** | Py / TS |79| Opinionated "deep" planning agent (subagents, file tools, todo) on top of LangGraph | **DeepAgents** | Py / TS |80| Web app with streaming chat, tool calls, generative UI; Next.js/React | **Vercel AI SDK** | TS |81| Edge-native, durable, stateful agents that scale to zero | **Cloudflare Agents SDK** (Durable Objects) | TS |82| Provider-agnostic, type-safe streaming/tools/structured output in any TS app | **TanStack AI** | TS |83| Google-ecosystem, Gemini-first, code-first multi-agent with eval tooling | **Google ADK** | Py / Java |84| Build on the same harness Claude Code uses; subagents, MCP, hooks, permissions | **Claude Agent SDK** | Py / TS |8586Mixed needs are common (e.g. LangGraph backend + AI SDK frontend, or Claude87Agent SDK behind a Cloudflare Worker). Compose; don't force one box.8889## Step 4 — Scaffold9091Build the minimum that runs, then layer on. Match the chosen framework's92conventions exactly — pull its quickstart from live docs first.9394Typical layers (build only what the requirements call for):95961. **Agent core** — the loop / graph / state. Confirm the current API shape.972. **Tools** — define and wire tool calls. See `references/concepts/tool-calling.md`.983. **Model access** — direct provider or gateway. See99 `references/concepts/ai-gateways.md` for OpenRouter / AnyRouter / AI gateway.1004. **API surface** — HTTP/streaming endpoints, or MCP server, per deploy target.1015. **UI/UX** — chat or dashboard. For React, prefer the framework's own UI102 primitives (AI SDK UI / AI Elements, Assistant UI, TanStack). For design103 quality, defer to the host's frontend-design skill if present.1046. **Persistence & memory** — checkpointer / store / vector DB.1057. **Observability** — tracing + evals + cost tracking from day one.1068. **Deploy** — Dockerfile / wrangler / k8s manifests / cloud config for the107 chosen target.108109After each layer: make it run, verify, then continue. Fail loud if a step is110skipped.111112## Step 5 — Agent-engineering concepts113114These cut across frameworks — read the matching reference when relevant:115116- **Building skills for agents** → `references/concepts/skills.md`117- **Tool calling** (schemas, validation, parallel calls, MCP) → `references/concepts/tool-calling.md`118- **Tracking / observability** (traces, evals, cost) → `references/concepts/tracking-observability.md`119- **AI gateways** (OpenRouter, AnyRouter, AI gateway, BYOK) → `references/concepts/ai-gateways.md`120- **Model-specific prompting** → `references/engineering/{claude,gemini,gpt}.md`121122## Guardrails123124- Don't pick a framework silently — recommend with a one-line why, let the user125 decide.126- Don't embed stale API code — verify against live docs first.127- Build the smallest thing that runs before expanding.128- Keep secrets out of the repo; use env vars / the platform's secret store.129- Match the existing codebase's conventions when in Detect mode.
terrylica