Loading...
Learn how to create, lint, and use proto.md agent contracts.
A proto.md file is a verifiable contract for AI agents. It defines what an agent does, what it can access, what it must never do, and how to test its behavior — all in a single markdown file that's both human-readable and machine-verifiable.
Think of it as the missing governance layer for the agentic era: explicit permissions, testable behavior, diffable changes, and trust by design.
The Guided Builder walks you through creating a proto.md with safe defaults. No spec knowledge required.
Create a proto.md file in your project root with YAML frontmatter + markdown sections:
---
proto: "0.1"
name: "My Agent"
summary: "Describe what this agent does."
version: "0.1.0"
tags: ["consumer"]
objective:
primary: "What should the agent accomplish?"
non_goals:
- "What it should never do"
capabilities:
mode: "browser_assist"
autonomy:
level: "assisted"
ask_before: ["submit_forms"]
permissions:
data_access:
passwords: "deny"
payments: "deny"
compute_access:
shell: "deny"
network: "allow"
observability:
receipts: true
replay: true
---
# Proto: My Agent
## What it does
- Describe the agent's purpose
## What it will NOT do
- List refusals
## Where it can act
- List allowed domains
## When it will ask you
- Before submitting forms
## What you will get (output)
- Describe output format
## Safety & privacy
- No data stored after sessionOpen the Live Editor and paste your proto.md to get instant ProtoLint feedback.
Check the Gallery for curated, linted proto.md examples across different use cases.
YAML between --- delimiters. Machine-readable. Used by linters, runtimes, and registries.
Markdown sections after frontmatter. Human-readable. Used by UI, gallery, and consumers.
Static analysis for proto.md. Catches dangerous permission combos, missing safety gates, and contract contradictions. See Lint Rules.