█████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗██████╗ ███████╗ ██████╗
██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝██╔══██╗██╔════╝██╔════╝
███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗██████╔╝█████╗  ██║
██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║██╔═══╝ ██╔══╝  ██║
██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║██║     ███████╗╚██████╗
╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝╚═╝     ╚══════╝ ╚═════╝

AgentSpec

The YAML-first design standard for agentic systems — spec agentic systems in YAML and build them to spec.

---

What is this?

AgentSpec is a portable, versioned standard for writing down what an agentic system IS — its intent, its jobs, the context it reads, the actions it takes, and the binary criteria that say it worked — as one readable YAML file, before you commit to any framework. The spec is the durable what & why; the implementation is a build target you choose later.

The repository ships two things that fit together:

• The standard (standard/) — the frozen agentspec.mutagent.io/v0.3.0 contract, its field catalog, and conformance fixtures. Every example validates under the closed 0.3.0 envelope.
• The Builder — takes a validated agentspec.yaml and implements it into a chosen target (a coding framework or a coding-agent harness) tests-first. It ships in the same plugin, alongside the authoring skill.

author → validate → build. Design before deploy.

The four kinds

Every subject is exactly one kind. Each has a worked, contract-valid example in examples/:

Kind	What it is	Example
Agent	A standalone autonomous subject that decides and acts.	examples/agent-support-triage
Skill	A packaged capability invoked to do one job well.	examples/skill-release-brief
MultiAgent	A coordinated team of member agents with a control model.	examples/multiagent-controlled-release
Workflow	A defined graph of steps with explicit control flow.	examples/workflow-incident-routing

Install

AgentSpec ships as one combined plugin (two independently versioned skills: agentspec + builder) for Claude Code and Codex.

# 1. Add the marketplace (once)
/plugin marketplace add mutagent-io/agentspec

# 2. Install the plugin
/plugin install agentspec@mutagent

# 3. Use it
/agentspec:spec    # author + validate an agentspec.yaml (guided interview)
/agentspec:build   # implement a validated spec into your chosen target

Validate a spec

The standard is enforceable, not aspirational — a structural (TypeBox) + semantic gate. The validator ships inside the plugin's agentspec skill; from a clone of this repo:

plugins/agentspec/skills/agentspec/scripts/cli/run.sh \
  plugins/agentspec/skills/agentspec/scripts/validate/validate-spec.ts \
  examples/agent-support-triage/agentspec.yaml
# exit 0 = valid agentspec.mutagent.io/v0.3.0 · exit 1 = field-pathed errors

What's in the box

standard/    the 0.3.0 contract, field catalog, and conformance fixtures
examples/    four contract-valid specs — one per kind
plugins/     the combined Claude + Codex plugin (agentspec + builder skills)
docs/        the project site

License

Apache-2.0. See NOTICE for attribution terms.

---

_{AgentSpec 0.3.0 · design before deploy · mutagent.io}