agent-sdk-wizard — preflight + 9 illustrated questions → a running agent
The user knows what they want the agent to do. They do not know which of the ~65 SDK options
does it, and often has never created an API key. This skill closes both gaps: step 0 gets the
machine and one credential ready (Mac or Windows), then asking, not explaining: nine
questions, each with a drawing of what changes, then it writes the agent — with a real system
prompt and, when it helps, a real skill — and runs it.
The skill is self-contained: every file it needs is in this folder (
,
). It does not depend on any other skill being installed.
Goal given by the user (may be empty): $ARGUMENTS
How to start
- Step 0 always comes first: preflight + credential. Read and follow
its state machine: detect Mac or Windows, run the preflight checks yourself, give exact
install commands for what is missing, then ask the question (A login,
recommended · B API key · C Pro/Max token), write , and verify. Skip the question only
if a verified already exists in the target folder ( prints the mode).
- Goal given above, or a free-form idea ("quiero un agente que me ordene las facturas") →
read , say in one line which of the eight families it belongs to and
what small first version you propose (its primer agente recomendado, adapted to their
words). Then ask step 2 anyway with the matching archetype first — the idea is a goal, not an
archetype — and use the family's tools, custom tool, skill and guardrail as the recommended
options for steps 5–9.
When an idea maps to a family, the family wins over for: the rules
(4-bis), tools (5), skill (6), guardrail (8–9: + a hook
written for that guardrail), /, () and sample
data. The archetype only decides vs a live session and the shape of the test
prompt. Model: Sonnet 5.5 first for any idea that reads and writes or researches; Haiku 5.5
only for pure lookups. Step 9's first option becomes "El guardián de mi idea": the
family's guardrail, from ( / covers
"escribe solo en entregas/"; adapt it for other paths or for SQL), previewed as a small
diagram like the other step 9 options. Reorder step 2 so the family's archetype goes first.
Combine options when the family needs it (e.g. , , , and
a custom tool). has the family → archetype table.
Sample data: when the family needs files the templates do not ship (an agenda, a bank
statement, a diff, a lesson), write small realistic ones yourself in
(10–20 rows or a page; include the edge cases the agent must catch) and make the test prompt
exercise them.
- Empty → after step 0, start at step 1 with no preamble.
Decision table — is this the right skill?
| The user says | Do |
|---|
| "quiero hacer un agente", "build me an agent", "agente con el SDK" | This wizard. Start at step 1. |
| "explícame el Agent SDK", "¿qué es un hook?" | Answer directly. Point at . No wizard. |
| "arregla mi agente", "¿por qué falla esto?" | Read their code. Use . No wizard. |
| "quiero usar la Messages API / Managed Agents" | Different product. Say so in one line and stop — this wizard only builds Agent SDK agents. |
| "agrégale un hook a mi agente" (agent already exists) | Just that step. Read references/opciones-sdk.md
for the exact code, edit their file. |
Hard rules
These are not suggestions. Breaking one breaks the wizard.
- One call per step. One question per call. Never two questions in the
same call — only renders on single-answer questions.
- Never . It kills the previews.
- Every option carries a , copied from . No exceptions,
including the sub-questions.
- The recommended option goes first, with appended to its label
( if the user writes in English).
- ≤ 12 characters. The headers below already comply.
- 2–4 options per question. The UI adds "Other" by itself — never write your own.
- Do not advance without an answer. After each answer, write one line confirming the
decision, then ask the next question. Example:
Listo: Python. Ahora, ¿qué tiene que lograr?
- Language follows the user. and the references are English; every question,
preview label, comment and generated README comes out in the language the user writes in.
Spanish is the default for this audience.
- Never use the "explain like I am five" framing — not that phrase, not its Spanish
translation, not any variant of it, anywhere the user can see. Explain like you would to a
smart person who has not seen this before: one concrete analogy, one drawing.
- Never invent an API name. Every option maps to exact code in
references/opciones-sdk.md
, verified against TS SDK 0.3.251 / Python SDK 0.2.148 /
Claude Code 2.1.251 and re-run on Python SDK 0.2.176 / TS SDK 0.3.315–0.3.316 (2026-11-07). If it is
not in that file, do not write it.
- Secrets. A pasted key or token goes only into , after lists .
Never echo it, never put it in a command line, a log, the README or .
- Commands for the user's OS. Every command you ask the user to run comes in the form for
their shell (zsh/bash on Mac, PowerShell on Windows). has both.
Skipping steps
Step 2 (objetivo) sets defaults for steps 3–9 — the table is in
.
When the goal makes a step meaningless,
say so in one line and skip it with the default:
- Goal is a single question with no files → skip 6 (skills), 7 (subagentes), 9 (hooks).
- Read-only goal → skip 9 (hooks); step 8 defaults to + .
- The user said "todos los recomendados" / "just use the defaults" → skip every remaining
question, take the recommended option for each, and go straight to generation. Show them the
9 decisions afterwards so nothing is a surprise.
Never skip step 0, step 1, step 2, or step 5.
The nine steps
Full option text, previews and sub-questions live in
, section by
section. Read that file before the first question. For each step below: ask exactly this
question, with exactly these options, in this order.
| # | | | Options (recommended first) | Preview section |
|---|
| 0 | ¿Con qué vas a pagar lo que gaste tu agente? | | Login con ant · API key de la consola · Mi suscripción Pro/Max | § Step 0 (after the preflight, ) |
| 1 | ¿En qué lenguaje quieres tu agente? | | Python · TypeScript | § Step 1 |
| 2 | ¿Qué tiene que lograr tu agente? | | Responder preguntas sobre mis archivos · Cambiar archivos o código · Llamar a mis funciones o APIs · Conversar varias vueltas con memoria | § Step 2 |
| 3 | ¿Qué tan listo lo necesitas (y cuánto quieres pagar)? | | Sonnet 5.5 · Haiku 5.5 · Opus 5.5 · Fable 5.1 | § Step 3 |
| 4 | ¿Qué personalidad y reglas fijas tiene tu agente? | | Mínimo + mis reglas · Preset de Claude Code + mis reglas · Solo el preset · Mío completo desde cero | § Step 4 |
| 5 | ¿Qué puede hacer tu agente en el mundo? | | Solo leer · Leer y escribir archivos · Todo, incluida la terminal · Mis propias funciones | § Step 5 |
| 6 | ¿Tu agente necesita saber un procedimiento tuyo? | | No por ahora · Sí, una skill nueva · Sí, ya tengo skills en este proyecto | § Step 6 |
| 7 | ¿La tarea es tan grande que conviene repartirla? | | No, un solo agente · Sí, un ayudante especializado · Sí, varios en paralelo | § Step 7 |
| 8 | ¿Quién autoriza cada acción del agente? | | Aprueba solo lo que listé · Que edite archivos sin preguntar · Que me pregunte a mí · Sin frenos (solo en sandbox) | § Step 8 |
| 9 | ¿Quieres un vigilante automático, código tuyo, en el ciclo? | | No por ahora · Bloquear comandos peligrosos · Guardar un registro de todo · Verificar el trabajo al final | § Step 9 |
Three conditional sub-questions
Each is a separate
call with its own previews. Ask only when the condition holds.
| After | Condition | | | Options |
|---|
| 3 | model is Opus 5.5 or Fable 5.1 | ¿Cuánto quieres que piense antes de responder? | | Alto () · Muy alto () · Medio () |
| 4 | answer was 4A, 4B or 4D | ¿Qué reglas fijas le pones? | | Analista de datos · Asistente de código · Operador cuidadoso |
| 5 | answer was 5D (own functions) | ¿Además quieres conectar un servidor que ya existe? | | No, solo mis funciones · Sí, un servidor MCP externo |
If the user brought an idea, the first
option is
"Las de mi idea (Recomendado)",
with a preview listing the 3–4 rules you derived from the idea and its family (that is what
goes into
and
of the system prompt); the three presets follow. If
the user picks "Otra", take their free text verbatim as the rules paragraph. Either way the
final prompt is built with
references/system-prompt.md
.
What each step decides
Exact TS and Python code for every answer:
references/opciones-sdk.md
.
| Step | Produces |
|---|
| 1 | + , or + . Also vs / — decided by step 2, not asked. |
| 2 | The test prompt, the , the sample data, and the defaults for steps 3–9 (). |
| 3 | (+ if the sub-question ran). |
| 0 | ( + one credential), , , /. |
| 4 | , built with references/system-prompt.md
and shown to the user before generating; plain string, or the object with . Plus when the result feeds another program. |
| 5 | ; for own functions also the / skeleton, , and . |
| 6 | <cwd>/.claude/skills/<name>/SKILL.md
(+ , when they carry real content), written with references/skill-creator.md
; setting_sources=["project"]
, . |
| 7 | with , plus in , plus the filter in the stream reader. |
| 8 | , / , and the callback if chosen. |
| 9 | with the ready-made function from or . |
Generation
Once the nine answers are in, create
in the user's current directory —
ask for the name in one line if they have not said it; otherwise derive it from the goal
(kebab-case, Spanish, no accents).
Fill the templates in
. Do not write the code from memory: start from the template
and substitute.
| File | From | When |
|---|
| | step 1 = Python |
| | step 1 = TypeScript |
| | step 1 = Python |
| | step 1 = TypeScript |
| / | templates/credenciales.py
/ , copied as is | always |
| written in step 0 () | always; never committed |
| | always |
| | always, before |
| / | / | step 9 ≠ "No por ahora" |
<cwd>/.claude/skills/<n>/SKILL.md
(+ ) | + references/skill-creator.md
| step 6 = "una skill nueva" |
workspace/datos/ventas.csv
| (it is clean: seed errors if the agent audits quality) | goal needs sample data (see ) |
| | always |
| templates/decisiones.md.tmpl
| always |
| derive from | only if the user asked for a notebook |
Non-negotiables in the generated code:
- The whole configuration is one visible block at the top —
opciones = ClaudeAgentOptions(…)
or const opciones: Options = {…}
— and every line carries a comment. That
block is the point: it is the map from the nine answers to the SDK.
- The system prompt follows
references/system-prompt.md
: rol, contexto, objetivo, cómo
trabajas, herramientas, límites, formato de salida — never a one-liner, no left.
- The skill lives under the agent's : with , the skill goes in
workspace/.claude/skills/<n>/
. That is where the SDK looks.
- runs before the first , and the README tells the user how to switch
mode (edit in ).
- and are always set. Defaults: ,
. No generated agent ships without both.
- The stream reader prints text, tool calls as , tool errors, and the final
with turns and cost. It is in the templates; keep it.
- Comments in the user's language.
- No absolute paths from any machine. Everything is relative to the generated directory.
Notebook variant
If the user wants
, the cell body is the same code with four changes: drop
, drop
and
, put the
at the top level of the cell, and replace
AQUI = Path(__file__).resolve().parent
with
(a cell has no
; the notebook lives in the agent folder and
Jupyter starts there). Call
in the first cell.
, never
— a kernel already has a running
event loop. Do not add
; it is not needed.
Test run — the wizard is not done until the agent runs
- exists and step 0 verified it. If not, go back to step 0 — do not ask the user to
anything; / reads itself.
- Install inside the generated directory: (Python) or (TypeScript).
Same command on Mac and Windows.
- Run once with the test prompt: or . The first line must
be naming the mode you set up; if it names another, stop and fix .
- Show the user the line: turns and cost. Path A or B: tell them it was charged to the
credits' organization; path C: to their plan.
- If a skill was created, the run must show . If it does not, fix the
description (see ) and run again.
- If it fails, fix it before saying done. (and the DIAGNOSTICAR
table in for credential messages) maps the exact message to its cause and its fix.
Do not hand back a broken agent with an explanation.
Closing
Do not re-explain the SDK. Show:
- The loop, drawn with the nine decisions already in it (the shape is in the generated README).
- The three commands to run it again.
- One line: what it cost.
Then stop. The README and
carry everything else, and
names the
research file for each decision so the user can go deeper on their own.