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 (references/, templates/). It does not depend on any other skill being installed.

Goal given by the user (may be empty): $ARGUMENTS

How to start

1. Step 0 always comes first: preflight + credential. Read references/auth.md 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 Credencial question (A ant login, recommended · B API key · C Pro/Max token), write .env, and verify. Skip the question only if a verified .env already exists in the target folder (credenciales prints the mode).
2. Goal given above, or a free-form idea ("quiero un agente que me ordene las facturas") → read references/ideas.md, 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 arquetipos.md for: the rules (4-bis), tools (5), skill (6), guardrail (8–9: disallowed_tools + a PreToolUse hook written for that guardrail), max_turns/max_budget_usd, cwd (./workspace) and sample data. The archetype only decides query() 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 templates/hooks.* (solo_en_entregas / soloEnEntregas 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. Read, Glob, Grep, Write and a custom tool). ideas.md 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 workspace/datos/ (10–20 rows or a page; include the edge cases the agent must catch) and make the test prompt exercise them.
3. Empty → after step 0, start at step 1 with no preamble.

Decision table — is this the right skill?

Hard rules

These are not suggestions. Breaking one breaks the wizard.

1. One AskUserQuestion call per step. One question per call. Never two questions in the same call — preview only renders on single-answer questions.
2. Never multiSelect: true. It kills the previews.
3. Every option carries a preview, copied from references/previews.md. No exceptions, including the sub-questions.
4. The recommended option goes first, with (Recomendado) appended to its label ((Recommended) if the user writes in English).
5. header ≤ 12 characters. The headers below already comply.
6. 2–4 options per question. The UI adds "Other" by itself — never write your own.
7. 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?
8. Language follows the user. SKILL.md 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.
9. 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.
10. 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.
11. Secrets. A pasted key or token goes only into .env, after .gitignore lists .env. Never echo it, never put it in a command line, a log, the README or decisiones.md.
12. 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). auth.md has both.

Skipping steps

Step 2 (objetivo) sets defaults for steps 3–9 — the table is in references/arquetipos.md. 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 default + allowed_tools.
• 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 references/previews.md, 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.

Three conditional sub-questions

Each is a separate AskUserQuestion call with its own previews. Ask only when the condition holds.

If the user brought an idea, the first Reglas 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 <limites> and <como_trabajas> 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.

Generation

Once the nine answers are in, create <nombre-del-agente>/ 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 templates/. Do not write the code from memory: start from the template and substitute.

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 # paso N: … 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 cwd: with cwd="./workspace", the skill goes in workspace/.claude/skills/<n>/. That is where the SDK looks.
• credenciales runs before the first query(), and the README tells the user how to switch mode (edit AGENTE_AUTH in .env).
• max_turns and max_budget_usd are always set. Defaults: max_turns=25, max_budget_usd=0.15. No generated agent ships without both.
• The stream reader prints text, tool calls as 🔧 nombre(argumento), tool errors, and the final result 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 agente.ipynb, the cell body is the same code with four changes: drop import asyncio, drop async def main() and asyncio.run(main()), put the async for at the top level of the cell, and replace AQUI = Path(__file__).resolve().parent with AQUI = Path.cwd() (a cell has no __file__; the notebook lives in the agent folder and Jupyter starts there). Call preparar_credenciales() in the first cell. await, never asyncio.run — a kernel already has a running event loop. Do not add nest_asyncio; it is not needed.

Test run — the wizard is not done until the agent runs

1. .env exists and step 0 verified it. If not, go back to step 0 — do not ask the user to export anything; credenciales.py/.ts reads .env itself.
2. Install inside the generated directory: uv sync (Python) or npm install (TypeScript). Same command on Mac and Windows.
3. Run once with the test prompt: uv run agente.py or npx tsx agente.ts. The first line must be [auth] … naming the mode you set up; if it names another, stop and fix .env.
4. Show the user the result line: turns and cost. Path A or B: tell them it was charged to the credits' organization; path C: to their plan.
5. If a skill was created, the run must show 🔧 Skill(<name>). If it does not, fix the description (see skill-creator.md) and run again.
6. If it fails, fix it before saying done. references/errores.md (and the DIAGNOSTICAR table in auth.md 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:

1. The loop, drawn with the nine decisions already in it (the shape is in the generated README).
2. The three commands to run it again.
3. One line: what it cost.

Then stop. The README and decisiones.md carry everything else, and decisiones.md names the research file for each decision so the user can go deeper on their own.