agent-spec
Specify an autonomous or tool-using AI agent before building it. Use when asked to design an AI agent, define an agent's tools and guardrails, scope what an agent is allowed to do, or write an agent spec/PRD. Produces an agent spec — goal & scope, tools with permissions, the control loop, guardrails & approval gates, memory, escalation/handoff, evaluation, and failure handling.
git clone --depth 1 https://github.com/mohitagw15856/pm-claude-skills /tmp/agent-spec && cp -r /tmp/agent-spec/plugins/pm-ai/skills/agent-spec ~/.claude/skills/agent-specSKILL.md
# 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.
Conduct a structured ethical review of an AI or ML feature, model, or product. Use when preparing to deploy an AI system, assessing algorithmic risk, auditing a model for bias, or producing a responsible AI impact assessment. Produces a structured ethics review covering fairness, transparency, privacy, safety, accountability, and societal impact with a risk tier score, pre-deployment checklist, and prioritised mitigations.
Structure AI and ML product decisions with the rigour of any product decision. Use when building AI-powered features, evaluating LLM integrations, designing AI products, or assessing AI readiness. Produces a complete AI product canvas covering problem definition, model approach, data requirements, evaluation framework, UX design, responsible AI checklist, and launch monitoring plan.
Transform feature briefs into structured design briefs that give designers the context they need before opening Figma. Use when asked to write a design brief, create a design handoff, brief a designer on a new feature, or translate a PRD into design requirements. Produces a brief with user goal, emotional context, success criteria, constraints, edge cases, and out-of-scope boundaries.
Design statistically rigorous A/B tests and interpret experiment results. Use when asked to design an experiment, run an A/B test, calculate sample size, interpret test results, or assess whether an experiment was successful. Produces a complete experiment design with hypothesis, sample size, run time, success criteria, and risk flags — or a results interpretation with ship/iterate/kill recommendation.
Synthesises user signals from multiple research sources into a unified, weighted insight brief. Use when you have data from interviews, support tickets, NPS verbatims, app reviews, or sales calls and need to reconcile contradictions, surface the underlying need behind requests, or answer 'what are users really telling us'. Produces ranked insights with confidence ratings, source weighting rationale, divergent signal analysis by user segment, and a research gap identification section.
Structure a product data analysis, metric deep-dive, funnel analysis, or cohort study. Use when asked to analyse product metrics, investigate a drop in conversion, explain a data change to stakeholders, or find the root cause of a metric movement. Produces a structured analysis with question, root cause, confidence level, and recommended action.
Interpret product metrics against goals and surface actionable signals. Use when asked to analyse product health, review key metrics, investigate a performance issue, produce a health report, or assess product-market fit signals. Produces a structured health report with RAG status, trend analysis, root cause hypotheses, and prioritised actions.
Structure a retention analysis, churn investigation, or engagement deep-dive for any product team. Use when asked to analyse user retention, investigate churn, measure DAU/MAU, or build a retention improvement plan. Produces a retention snapshot with root cause hypotheses, aha-moment correlation, and prioritised interventions.