agent-design-principleslisted

## Purpose Agent/prompt quality tends to erode the same way code quality does when there's no checklist forcing a second look: an agent persona quietly grows to cover more than it should, context accumulates instead of getting curated, and failures get retried with the same full error dump instead of a compacted summary. This skill exists to catch that drift when authoring or revising an agent, skill, or command — for this repo's own artifacts, or for a target repo an `ai-engineer`/`prompt-engineer` is working in. It draws specific, named ideas from [12-factor-agents](https://github.com/humanlayer/12-factor-agents) (humanlayer, Apache-2.0) — cited individually below, not reproduced wholesale; read the source for the full essays behind each one. ## When to use it Before adding a new agent persona or skill, before letting an existing one grow a new responsibility, and when designing how multiple agents hand work to each other (an orchestrator pattern, a pipeline of specialist agents). ## The checklist 1. **Small, focused agents** — Does this persona do one job well, with a clearly stated permission posture (what it does freely, what it never does)? If a persona's responsibility list is growing past what fits in a short paragraph, it's probably two personas. 2. **Own your control flow** — Is the sequence between stages/agents explicit (a named handoff, like this repo's `orchestrator` → `builder` → `verifier` pattern), rather than an open-ended loop hoping the model figures