build-agent-app
Kernel: agent = model + harness. This is the architect step. Implementation belongs to $ai-engineering-harness.
Trigger
Keywords: build an agent, convert PRD to agent, take over existing agent, agent is broken, diagnose agent, wrap script in agent loop, wire up LLM tool, chatbot, agent app.
Skip if: single-step script, pure LLM chat without tools, general code task (use $ai-engineering-harness).
Operating principles
- Decision 0: is this even an agent? Demand a written answer before designing tools/prompts/state.
- One agent, one goal. "Search + code + bookings + chat" = 4 products. Split before scaling.
- Tools are the boundary. If the agent can't do anything, it's a chatbot.
- Workflow beats free-form planning. ReAct or Planner patterns, not "let the LLM figure it out."
- Memory is for future decisions, not chat logs.
- High-risk actions require human approval. Deploy, delete, send money.
- Every agent must be observable. Trace decisions, tool calls, failures.
- Failure paths are part of the design. Plan retries, fallbacks, escalation.
- This skill writes contracts + entry workflow;
$ai-engineering-harness does code + tests + PR + review.
Workflow selection
Pick one:
workflows/new-from-prd.md — PRD/idea → design + spec + handoffworkflows/takeover-existing.md — existing agent → audit + integrateworkflows/refactor-broken.md — symptoms → diagnose + rebuild
Run references/decision-0.md first if unclear.
Contracts (always write)
Agent Contract (templates/agent-contract.md):
- Role, Goal, Constraints, Tools (name + description + input/output schema), Output format
Harness Contract (references/harness-checklist.md):
- State, Memory (short vs long), Eval, Observability, Failure paths, Human approval
Write contracts BEFORE writing code. Let code follow.
Hand-off
After contracts exist, emit docs/agent-spec/<name>.md (compatible with $ai-engineering-harness's docs/product/ style). Then:
Use $ai-engineering-harness to bootstrap this repo from docs/agent-spec/.md
Anti-patterns
- Universal Agent ("does search + code + bookings + chat") — split it.
- Tool-permission-everything — least privilege.
- Free-form plans without checkpoints — agent drifts.
- Storing chat in memory — bloats context, never useful.
- Prompt over 200 tokens with no Constraints section.
- "I'll add eval later" — set eval hooks before first prod run.
- Implementing before writing the contracts.
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
Read on demand
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 specscripts/scaffold-agent-spec.sh — scaffold docs/agent-spec/<name>.md$dashboard — sibling skill for visualizing harness project state$ai-engineering-harness — sibling for implementation (code + tests + PR + review)
1---2name: build-agent-app3description: Design/take over/refactor an agent app (LLM + tools + state). Triggers: build an agent, wire up LLM tool, chatbot, agent is broken, agent app. Writes Agent + Harness Contract, hands off to $ai-engineering-harness. Workflows: new / takeover / refactor. Install: bash install.sh --skill build-agent-app4---56# build-agent-app78Kernel: **agent = model + harness**. This is the **architect step**. Implementation belongs to `$ai-engineering-harness`.910## Trigger1112Keywords: build an agent, convert PRD to agent, take over existing agent, agent is broken, diagnose agent, wrap script in agent loop, wire up LLM tool, chatbot, agent app.1314Skip if: single-step script, pure LLM chat without tools, general code task (use `$ai-engineering-harness`).1516## Operating principles17181. **Decision 0: is this even an agent?** Demand a written answer before designing tools/prompts/state.192. **One agent, one goal.** "Search + code + bookings + chat" = 4 products. Split before scaling.203. **Tools are the boundary.** If the agent can't do anything, it's a chatbot.214. **Workflow beats free-form planning.** ReAct or Planner patterns, not "let the LLM figure it out."225. **Memory is for future decisions**, not chat logs.236. **High-risk actions require human approval.** Deploy, delete, send money.247. **Every agent must be observable.** Trace decisions, tool calls, failures.258. **Failure paths are part of the design.** Plan retries, fallbacks, escalation.269. **This skill writes contracts + entry workflow; `$ai-engineering-harness` does code + tests + PR + review.**2728## Workflow selection2930Pick one:31- **`workflows/new-from-prd.md`** — PRD/idea → design + spec + handoff32- **`workflows/takeover-existing.md`** — existing agent → audit + integrate33- **`workflows/refactor-broken.md`** — symptoms → diagnose + rebuild3435Run `references/decision-0.md` first if unclear.3637## Contracts (always write)3839**Agent Contract** (`templates/agent-contract.md`):40- Role, Goal, Constraints, Tools (name + description + input/output schema), Output format4142**Harness Contract** (`references/harness-checklist.md`):43- State, Memory (short vs long), Eval, Observability, Failure paths, Human approval4445Write contracts BEFORE writing code. Let code follow.4647## Hand-off4849After contracts exist, emit `docs/agent-spec/<name>.md` (compatible with `$ai-engineering-harness`'s `docs/product/` style). Then:5051> Use $ai-engineering-harness to bootstrap this repo from docs/agent-spec/<name>.md5253## Anti-patterns5455- Universal Agent ("does search + code + bookings + chat") — split it.56- Tool-permission-everything — least privilege.57- Free-form plans without checkpoints — agent drifts.58- Storing chat in memory — bloats context, never useful.59- Prompt over 200 tokens with no Constraints section.60- "I'll add eval later" — set eval hooks before first prod run.61- Implementing before writing the contracts.6263## Quick start6465```66# New app from PRD67Use $build-agent-app to design a code-review agent from PRD.md6869# Take over existing70Use $build-agent-app to integrate /path/to/agent-app into my project7172# Refactor broken73Use $build-agent-app to diagnose why /path/to/agent is doing X wrong74```7576## Read on demand7778- `references/decision-0.md` — "is this an agent" checklist79- `references/harness-checklist.md` — State/Memory/Eval/Observe/Failure/Approval80- `templates/agent-contract.md` — Role/Goal/Constraints/Tools/Output81- `templates/harness-checklist.md` — copy-paste harness spec82- `scripts/scaffold-agent-spec.sh` — scaffold `docs/agent-spec/<name>.md`83- `$dashboard` — sibling skill for visualizing harness project state84- `$ai-engineering-harness` — sibling for implementation (code + tests + PR + review)
lora-sys