Agent Spec Skill

Agent Spec Skill

An agent is a model plus tools plus a loop — and the danger lives in the tools and the loop, not the model. This skill specifies an agent so its authority is explicit: what it can do, what needs a human yes, and what happens when it's wrong. Scope and guardrails first; cleverness second.

Required Inputs

Ask for these only if they aren't already provided:

• Job to be done — the outcome the agent owns, and the boundary of its authority.
• Tools/actions — what it can call (read APIs, write actions, code execution), and which are irreversible.
• Autonomy level — fully autonomous, propose-then-approve, or co-pilot.
• Risk surface — what's the worst thing a wrong action could do (spend money, send a message, delete data)?
• Success definition & escalation — how "done" is judged, and when it must hand off to a human.

Output Format

Agent Spec: [name]

1. Goal & scope — the job in one sentence; explicit non-goals and authority limits.

2. Tools / actions — a table; mark each action's reversibility and required permission.

3. Control loop — plan → act → observe → reflect; the stopping condition; and a hard max-steps / max-cost budget so it can't loop forever.

4. Guardrails & approval gates — which actions require a human yes (default: anything irreversible, outbound, or spending), input/output validation, and allow/deny lists. Pair irreversible actions with a dry-run preview (see action-runner).

5. Memory & state — what it remembers within a task vs. across tasks, and where (link a professional-brain for durable memory).

6. Escalation & handoff — the triggers that stop the agent and route to a human (low confidence, repeated failure, out-of-scope request, high-risk action).

7. Evaluation — task success rate, action correctness, and safety (false-action rate). Define with an ai-eval-plan, and test on adversarial/trap tasks.

8. Failure handling — timeouts, tool errors, hallucinated tool calls, and the safe default (stop and ask, never guess on a high-risk action).