| name | build-agent-app |
| description | Design, take over, or refactor an agent app. Use when (a) the user has a PRD/idea and the answer is or could be an LLM-driven agent, (b) the user wants Codex to wire an existing agent app into a new harness / workflow / eval, or (c) the user hands over a "broken" agent app that needs diagnosis and a targeted rebuild. Acts as the Agent App Architect: writes the Agent Contract + Harness Contract, picks the entry workflow (new / takeover / refactor), then hands implementation off to $ai-engineering-harness. Pairs with that skill -- build-agent-app answers "should we even build an agent, and what should it look like"; ai-engineering-harness answers "how do we ship it as a working, evidence-gated piece of code."
|
build-agent-app
The kernel: agent = model + harness. Designing an agent app is the act of specifying the model (Role + Goal + Tools + Output) and the harness (State + Memory + Eval + Observe + Failure path + Human approval). Most agent failures come from one of these ten contracts being under-specified.
This skill is the architect step. Implementation belongs to $ai-engineering-harness. Never write business code from this skill.
New to this skill? Read QUICKSTART.md first — working tutorial with end-to-end examples for the 3 entry workflows (new / takeover / refactor), copy-paste prompt templates, and a do/don't cheat sheet.
When to use
Use this skill if the user's request is any of:
- "Build me an agent that does X."
- "Convert this PRD into an agent app."
- "Take over this existing agent and make it fit our workflow."
- "This agent is broken — diagnose and refactor."
- "Wrap this script/tool in an agent loop."
- "I have a tool. Should I add an LLM in front, and if so which one?"
Do not use it for:
- Single-step scripts (just write the script).
- Pure LLM chat / RAG without tool use (just write a prompt).
- Code tasks in general — use
$ai-engineering-harness directly.
Operating principles
- Decision 0: is this even an agent? Most "agent" requests are scripts. Demand a written answer before designing tools, prompts, or state. See
references/decision-0.md.
- One agent, one goal. An agent that "does search, writes code, books flights, and chats" is four products glued together. Split before scaling.
- Tools are the boundary. If the agent can't do anything, it's a chatbot. Quality of the agent ≈ quality of the tool design.
- Workflow beats free-form planning for repeated tasks. Use ReAct or Planner patterns, not "let the LLM figure it out."
- Memory is for future decisions, not chat logs. If nothing will read this state next week, don't store it.
- High-risk actions require human approval. Deploy, delete, send money, modify production. The harness enforces, the user ratifies.
- Every agent must be observable: trace the decision, the tool calls, the failures. Don't ship a black box.
- Failure paths are part of the design. Tool errors, permission errors, timeouts — plan retries, fallbacks, escalation.
- After this skill: implementation is
$ai-engineering-harness's job. This skill writes contracts + entry workflow; aeh does code + tests + PR + adversarial review.
Workflow selection
Pick exactly one:
workflows/new-from-prd.md — user has a PRD / idea / script → design + spec + handoff.workflows/takeover-existing.md — user has an agent code we don't recognize → audit + integrate.workflows/refactor-broken.md — user reports symptoms (cost, wrong answers, latency) → diagnose + minimal rebuild.
If the user's request doesn't fit cleanly, run references/decision-0.md first; the workflow falls out of the answer.
Agent Contract (always write this)
For every agent that comes out of this skill, fill templates/agent-contract.md:
- Role — who am I, in one sentence
- Goal — outcome the user can observe when I'm done
- Constraints — forbidden actions, format rules, response shape
- Tools — each with
name, description (the description is the LLM's guide), input schema (strict), output schema
- Output — wire format for the final result
Don't write the contract after writing the code. Write it first; let the code follow.
Harness Contract (always write this)
For the agent's runtime, fill templates/harness-checklist.md (or read references/harness-checklist.md):
- State — session vs long-term; what lives where
- Memory — short (conversation state, current plan) vs long (user prefs, facts); only what's future-useful
- Eval — how we measure success, and how that loops back to prompt/code changes
- Observability — tracing, logs, metrics
- Failure — retries, alt tools, escalations to user; never silent
- Human approval — which tool categories pause for "are you sure?"
Hand-off to $ai-engineering-harness
After contracts exist, this skill emits a docs/agent-spec/<name>.md (compatible with ai-engineering-harness's docs/product/ style). That file is what $ai-engineering-harness consumes as the project's PRD.
Suggested hand-off prompt to the user:
Use $ai-engineering-harness to bootstrap this repo from docs/agent-spec/<name>.md
If you're not in a real project yet, run scripts/scaffold-agent-spec.sh <name> to lay down the spec scaffold in any directory.
Anti-patterns
- Universal Agent ("does search + code + bookings + chat"). Split it.
- Tool-permission-everything ("root + full db + R + W"). Least privilege.
- Free-form long plans without checkpoints — agent drifts.
- Storing chat in memory — never useful; bloats context.
- Prompt over 200 tokens with no Constraint section — LLM weight vs rule imbalance.
- "I'll add eval later" — set the eval hooks before the first prod run.
- Implementing without first writing the Agent + Harness Contract — the whole skill exists to prevent this.
Quick start
# New app from PRD
Use $build-agent-app to design a code-review agent from PRD.md
# Take over existing
Use $build-agent-app to integrate /path/to/agent-app into my project
# Refactor broken
Use $build-agent-app to diagnose why /path/to/agent is doing X wrong
For installation:
npx -y skills add lora-sys/build-agent-app -g --all
Bundled resources
references/decision-0.md — "is this an agent" checklistreferences/harness-checklist.md — State/Memory/Eval/Observe/Failure/Approvaltemplates/agent-contract.md — Role/Goal/Constraints/Tools/Outputtemplates/harness-checklist.md — copy-paste harness specworkflows/new-from-prd.md — entry: greenfield design → hand offworkflows/takeover-existing.md — entry: reverse-engineer an existing agent → integrateworkflows/refactor-broken.md — entry: symptom → diagnosis → minimal rebuildscripts/scaffold-agent-spec.sh — make a docs/agent-spec/<name>.md skeleton
Read on demand. Concise is a feature.
