Capture why an Agent, Skill, Multi-Agent system, or Workflow should exist, preserve the decisions that shape it, then hand approved intent directly to the Builder.
┌─ agentspec.yaml ────────────────────── v0.3.0 ─┐ │ │ │ apiVersion · kind · metadata · spec │ │ │ │ kind ─┬─ Agent one autonomous subject │ │ ├─ Skill a loadable capability │ │ ├─ MultiAgent members + a graph │ │ └─ Workflow the workflow graph │ │ │ │ intent · context · actions · capabilities │ │ targets[] · evaluation · decisionsRef │ │ │ └───────────────────────┬────────────────────────┘ ▼ spec → build → the agent you designed, any target
One closed apiVersion · kind · metadata · spec envelope — requirements-first intent, a context/action split, exactly one kind-native body, multi-target artifacts, an evaluation contract, and an optional decision log. Read it — you get it. Unknown fields fail · kind leakage fails · bounded loops · every reference resolves. This complete card passes the validator as shown.
apiVersion: agentspec.mutagent.io/v0.3.0 kind: Agent metadata: id: support-triage name: Support Triage Agent version: "1.0.0" description: "Grounded ticket triage with approval-gated external updates." spec: intent: problem: "Operators lose time gathering evidence and classifying every ticket." outcomes: ["Produce a cited triage recommendation within 60 seconds."] sop: - id: grounded-triage when: "A new support ticket requires triage." description: "Retrieve evidence, classify, propose, request approval, then apply or stop." onFailure: "Escalate with evidence and perform no outbound action." jobs: - id: triage-ticket description: "Gather evidence, classify the issue, propose the safest supported route." expectedOutput: "Cited summary, confidence, route, and proposed update." constraints: ["Every outbound write requires approval."] nonGoals: ["Issue refunds", "Contact customers directly"] assumptions: ["Read and update operations are separately authorized."] unknowns: ["Confidence threshold for mandatory escalation"] context: - id: ticket-record description: "Current ticket, message, history, priority, and routing state." modalities: [record, text] source: "support-platform/tickets" access: { kind: mcp, ref: "mcp://support/tickets.read", allowedOperations: [ticket.get] } actions: - id: update-ticket description: "Apply only the approved route, priority, and internal note." binding: { kind: mcp, ref: "mcp://support/tickets.update" } allowedOperations: [ticket.route.update, ticket.note.create] approval: { policy: required, when: "Before every write, show the exact field changes." } evidence: "Record approval ID, requested fields, and provider response." onFailure: "Stop and return the proposed change plus error; never auto-retry a write." capabilities: code: - { id: triage-confidence, description: "Scores confidence from cited signals." } skills: [] delegates: [] agent: persona: { role: "Senior support triage specialist", description: "Precise, privacy-aware, evidence-led." } systemPrompt: "Cite every routing claim. Present the exact proposed update and wait for approval. Never write without approval." operatingType: conversational targets: - id: claude-code type: harness name: claude-code artifact: { format: markdown, path: .claude/agents/support-triage.md } capabilityFit: "Native MCP bindings satisfy context reads and the approval-gated action." documentation: [{ purpose: agent-format, url: "https://example.test/claude-code/agents" }] - id: mastra type: framework name: mastra artifact: { format: code, path: src/agents/support-triage.ts } implementation: { language: typescript, toolchain: bun } capabilityFit: "SDK/MCP adapters, graph execution, tests, and approval middleware exist." documentation: [{ purpose: conventions, url: "https://example.test/mastra/agents" }] evaluation: criteria: - { id: no-unapproved-write, description: "No outbound action without an approval record.", type: code-check, goal: "100% approval coverage" } - { id: grounded-route, description: "Every proposed route cites retrieved evidence.", type: llm-judge, goal: "No unsupported routing claim" } scenarios: - { id: ambiguous-evidence, description: "Signals support more than one route.", expectedBehavior: "Explain the ambiguity; request operator judgment.", edgeCase: true } datasets: [] decisionsRef: ./agentspec.decisions.md
AgentSpec is the durable what & why. The Builder team translates it to a chosen target, builds it to spec, and proves the claim.
Problem, intent, context, actions — an evidence-backed design in human-readable YAML.
The engineer drafts the goal-based file/test plan; the architect signs off before any write.
Execute the approved plan, tests first — harness, code framework, platform, or custom target.
Compare actual output to spec, plan, and cited docs; then conformance + release checks.
kind is inferred after intent and selects exactly one design body. No anatomy leaks across kinds.
A persona, the system prompt (carried verbatim), triggers, and an optional workflow graph.
Purpose, host-aware invocation, instructions, resources — not an agent with a label.
Embedded member cards, an acyclic dispatch graph, distinct watch relations.
State, nodes, edges — with bounded loops. Any kind can reuse it inline.
Abridged from the validated examples — every full card validates under the closed 0.3.0 envelope. Real YAML — read it and you get it.
kind: Skill spec: skill: # a loadable capability, not an agent purpose: "Repo evidence → reviewed release brief." invocation: "Load explicitly for release briefs." failureBehavior: "Degrade to a manual-post brief." targets: [{ name: claude-code }, { name: codex }]
kind: MultiAgent spec: multiAgent: orchestrator: release-coordinator members: […researcher, assessor, publisher, watchdog] relations: observes: { safety-watchdog: [coordinator, publisher] } # watch ≠ dispatch
kind: Workflow spec: workflow: # a control-flow graph — no persona entry: intake nodes: - { id: retrieve, contextRefs: [incident-record] } - { id: page, executor: { kind: action, ref: page-on-call } }
# Support Triage — decision log D-01 · kind = Agent (not Workflow) the graph is control flow within the agent, not the resource. D-02 · approval-gated single action the only external write is human-gated with recorded evidence.
Real material from the shipped skills — not filler.
The guided interview gathers the whole problem space — problem, outcomes, the long-form standard operating procedure, constraints, context, and actions, plus the capability inventory (including any delegates) — before it infers the kind. Targets are chosen last.
One approved card builds to many destinations. Each target resolves independently from its own docs; a custom target is a normal target with path + doc refs. A capability gap blocks only that target.
The Builder freezes a goal-based plan (task · verifiable outcome · exact artifacts · components with their reason and doc source · check → expected). The architect signs it off before any write; then a tests-first build produces a fidelity/loss report.
When optimization changes the code first, the reader proposes a reverse spec/decision/eval update — each cited. Operator approve/revise/reject; only approved deltas persist.
Author criteria-first or dataset-first. Datasets own local categories + case dimensions + items with kind-specific input/expected payloads. Every item maps to one scenario.
Access/action bindings use a closed kind enum (cli·saas·mcp·sdk·host-tool). Workflow executors are strict {kind,ref}; any returning edge must declare a bounded loop.
One combined plugin per host, on Claude or Codex.
The first versioned baseline. The standard is versioned in the repository; install commands and release links are wired at launch.