---
name: Agent Spec
slug: agent-spec
category: AI Engineering
description: Agent Spec defines the goal, tools, control loop, guardrails, memory, escalation, evaluation, and failure handling for an autonomous or tool-using AI agent before it is built. Use it when asked to design an AI agent, define its tools and permissions, or write an agent spec/PRD.
github: "https://github.com/mohitagw15856/pm-claude-skills/tree/main/skills/agent-spec"
language: HTML
stars: 1295
forks: 231
install: "npx degit https://github.com/mohitagw15856/pm-claude-skills/tree/main/skills/agent-spec ~/.claude/skills/agent-spec"
installs_to: ~/.claude/skills/agent-spec
source_path: skills/agent-spec/SKILL.md
collection_size: 25
category_size: 2451
collection_url: "https://dirskills.com/collections/mohitagw15856/pm-claude-skills"
added: 2026-08-20T07:55:00.164Z
last_synced: 2026-08-20T07:55:00.164Z
canonical_url: "https://dirskills.com/skills/agent-spec"
---

# Agent Spec

Agent Spec defines the goal, tools, control loop, guardrails, memory, escalation, evaluation, and failure handling for an autonomous or tool-using AI agent before it is built. Use it when asked to design an AI agent, define its tools and permissions, or write an agent spec/PRD.

**Install:**

```bash
npx degit https://github.com/mohitagw15856/pm-claude-skills/tree/main/skills/agent-spec ~/.claude/skills/agent-spec
```

## README

# 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.

| Tool | Purpose | Reversible? | Gate |
|---|---|---|---|
| search_kb | read context | yes | none |
| send_email | notify | **no** | **human approval** |

**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`](../action-runner/SKILL.md)).

**5. Memory & state** — what it remembers within a task vs. across tasks, and where (link a [`professional-brain`](../professional-brain/SKILL.md) 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`](../ai-eval-plan/SKILL.md), 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).

## Quality Checks

- [ ] Every tool is marked reversible/irreversible, and every irreversible action has a human gate
- [ ] There is a hard max-steps and max-cost budget — the loop cannot run unbounded
- [ ] Escalation triggers are explicit (confidence, repeated failure, out-of-scope, high-risk)
- [ ] The safe default on uncertainty is "stop and ask", not "guess and act"
- [ ] Evaluation includes a safety metric (wrong/unauthorised actions), not just task success
- [ ] Non-goals and authority limits are stated, not implied

## Anti-Patterns

- [ ] Do not give an agent irreversible actions without an approval gate — autonomy and irreversibility together is how agents cause real damage
- [ ] Do not omit a step/cost budget — an agent that can loop is an agent that can rack up cost or thrash forever
- [ ] Do not measure only task success — an agent that completes the task by taking a wrong action has failed
- [ ] Do not let the agent invent tool calls or arguments — validate against the schema and fail safe
- [ ] Do not skip the "what's the worst case" analysis — the risk surface determines how many guardrails you need

## Based On

Tool-using / agentic design practice — bounded control loops, least-privilege tools, human-in-the-loop approval, and safety evaluation.