AI Agent Builder

Turn an agent idea or existing system into the simplest implementation that can complete real tasks reliably, safely, and measurably.

Use English for discussion and deliverables. If the user primarily requests Chinese output, prefer $ai-agent-builder-cn. This Skill is a self-contained knowledge package; do not assume the source book repository is available at runtime.

Working Boundaries

• Preserve the user's stated scope, stack, providers, and authorization boundaries.
• Do not assume an agent is necessary. Prefer, in order: ordinary code, one model call, a deterministic workflow, one autonomous agent, then multiple agents. Move right only when the task genuinely needs additional adaptability.
• Model an agent as LLM + context + tools, interacting with an external environment through observation and action interfaces. Keep environment state distinct from agent state.
• Let the model handle flexible interpretation and planning. Put permissions, irreversible constraints, verification, budgets, retries, and stopping conditions in deterministic Harness code.
• Preserve principles that survive model upgrades, but treat compatibility prompts, parsing repairs, and capability bridges as testable adapters. Re-evaluate their net value after model or provider changes and retire scaffolding that no longer helps.
• Models, SDKs, frameworks, APIs, pricing, and provider behavior can change. Before committing to implementation details, inspect the target project and consult current primary official documentation.

Choose the Working Mode

Infer the narrowest mode that satisfies the request. A request may pass through several modes, but do not force the user through all of them.

• Explore: Clarify the objective, users, environment, risk, and evidence of success when the idea is still vague.
• Design: Produce an implementable agent design or architecture decision.
• Build: Implement an established design in an existing or new codebase. Inspect and reuse the local stack before choosing libraries or abstractions.
• Review: Inspect and evaluate an existing agent. Prioritize concrete reliability, safety, and evaluation gaps instead of redesigning to personal taste.
• Improve: Diagnose evaluated failures, propose attributable minimal changes, and protect behavior that already works.

Shared Workflow

1. Establish the task contract: desired outcome, actors, environment, inputs, outputs, non-goals, constraints, risks, and observable completion state. Ask only about unknowns that would materially change the design or create unacceptable risk.
2. Apply the complexity ladder. Before adding an autonomous loop or multiple agents, explain why a simpler option is insufficient.
3. If traces exist, find the first divergence and locate it in observation/context, model decision, action/tool, environment, state/recovery, or verification. Do not hide an interface or Harness defect behind a stronger model.
4. Define the control contract: observations, actions, state, decision points, trace integrity, progress signals, completion checks, retry policy, budgets, escalation, and failure behavior.
5. Design context and tools around the task contract. Expose only the information and actions needed by the current role; assess risk from the tool, normalized arguments, and scope. Keep high-risk actions narrowly permissioned, strongly typed, auditable, and previewable. If required approval is absent, pause and preserve recoverable state.
6. Define evaluation before a design or implementation is deliverable: representative tasks, boundary and adversarial cases, allow/deny pairs, deterministic checks where possible, process evidence, cost, latency, and regression protection.
7. In explore mode, clarify; in design mode, specify; in build mode, implement and test in proportion to risk; in review mode, separate facts from recommendations; in improve mode, bind every change to failure evidence and verify both the target repair and retained behavior.

Reference Routing

Read only the files needed for the current request:

• For deciding between code, workflow, and autonomy, or for control-loop, Harness-boundary, and agent-specification work, read references/architecture.md.
• For API message protocols, Chat Templates, KV/Prompt Cache, prompts and context construction, Skills, status bars, memory, RAG, knowledge organization, or context compression, read references/context-memory.md.
• For tool selection, schemas, execution, permissions, errors, recovery, sandboxing, MCP trust, or tool discovery, read references/tools-harness.md.
• For coding agents, code interpreters, executable rules, artifacts/generative UI, adaptive programs, or agent bootstrapping, read references/coding-agent.md. Also read tools-harness.md when the request includes low-level tool contracts or sandbox implementation.
• For events, asynchronous work, user interruption, voice, GUI/computer use, or embodied interaction, read references/interaction.md.
• For acceptance criteria, evaluation datasets, metrics, memory/RAG retrieval, prompt ablations, judges, trace analysis, observability, cost, or model selection, read references/evaluation.md.
• For learning from feedback, deciding whether experience belongs in knowledge, instructions, code, or parameters, and safe continual improvement, read references/improvement.md.
• For agent-model mid-training, SFT, distillation, preference optimization, RL, training environments, or reward design, read references/post-training.md. If production feedback supplies training data, also read improvement.md and evaluation.md.
• For deciding whether multiple agents add value, or for context sharing, topology, communication, concurrency, and coordination-failure design, read references/multi-agent.md.

Do not load every reference by default. Architecture and build requests usually need architecture.md plus one or two specialist files; pure evaluation, improvement, or post-training requests can load only the relevant specialist files.

Deliverables

Match the artifact to the request:

• Give a concise recommendation for a single decision.
• For architecture work, produce an Agent Design Specification covering the task contract, simplest sufficient architecture, environment, observations, actions/tools, context/state/memory, control flow, guardrails, failure handling, evaluation, and open decisions.
• For implementation work, produce runnable code and focused verification, with brief design rationale.
• For review work, order findings by severity and cite the responsible component and missing test evidence.
• For improvement work, produce a failure-to-change record: evidence, first attributable error, minimal change, expected gain, regression risk, and verification result.

Do not invent implementation evidence, treat tool-call success as task completion, or equate a plausible answer with a verified environment result.