agentproto

agentproto publishes open, numbered specifications — called AIPs (Agentproto Improvement Proposals) — for the markdown files that AI agents read, write, and operate from. The project is hosted on GitHub under CC-BY-4.0 for specs and MIT for code, and currently sits at version 0.1.0-alpha with 47 proposals in the registry.

What It Is

agentproto is a community standards registry for the AI-agent ecosystem, modeled after ERC (Ethereum), BIP (Bitcoin), and PEP (Python) improvement proposal processes. Each AIP is a numbered markdown specification that defines a single primitive — a skill manifest, a tool contract, a governance policy, an operator profile — so that any agent runtime can consume the same file without rewriting it. The project's README frames the motivation as: every serious agent system is converging on a folder of markdown files the agent reads, writes, and runs from, but without a shared vocabulary there is zero interoperability — "Is it skill.title or skill.name? Does AGENTS.md mean Codex's flavour, Cursor's flavour, or yours?"

The AIP Registry Structure

The 47 proposals in the registry are organized into 8 semantic layers, each answering a distinct question about agents:

• Process — how the standard itself evolves (AIP-1, AIP-2)
• Primitives — shared building blocks like IO, RUNNER, COLLECTION, SECRETS, REF
• Identity — who acts: OPERATOR, IDENTITY, PERSONA
• Memory — what the agent remembers: KNOWLEDGE, LESSON, PLAYBOOK
• Work, Org & Governance — COMPANY, GOVERNANCE, AGENCY, WORK, OFFICE, ASSEMBLY
• Capabilities — SKILL, TOOL, WORKFLOW, INTENT
• Drivers — how capabilities are implemented: DRIVER, CLI, HTTP, MCP, SDK
• Surfaces — what the agent produces or reads: DESIGN, CANVAKIT, CODE

Final-status specs are considered stable; Draft and Review specs may change before promotion.

Why Markdown, Not YAML or JSON

The README explains the design choice directly: agents read the file every turn, so prose in a SKILL.md can carry behavioral semantics — "if the document isn't an invoice, return { error: 'not_an_invoice' } — don't hallucinate fields" — and the model acts on that instruction each run. YAML frontmatter holds the typed fields machines need; the prose body holds the behavioral contract the model reads. The same intent in JSON is described as "dead data"; in a compiled function it is "locked into a release."

Relationship to MCP and A2A

The project's FAQ explicitly positions AIPs as complementary to, not competing with, existing protocols. MCP solves tool transport; AIPs specify the layer above transport and below frameworks — where context lives, roles are defined, and memory is structured. A TOOL.md contract (AIP-14) can be served over MCP, HTTP, CLI, or in-process via the DRIVER layer (AIP-30 through AIP-33). A2A solves agent-to-agent communication; AIPs address how a single agent's components are structured on disk.

Self-Modifying Agents and the Runtime

The reference TypeScript runtime lives in the separate agentproto/ts repository and exposes packages including @agentproto/tool, @agentproto/driver, @agentproto/agencies, @agentproto/governance, and @agentproto/ref, with framework adapters for Mastra and ai-sdk. Because every component — memory, runtime, governance, work backlog — is a file with a declared contract, the README argues that self-modification "stops being a research problem and becomes a write_file call": an agent can add a new tool by writing a TOOL.md and DRIVER.md to disk, swap an OpenAI call for a Replicate one by adding a second DRIVER and updating policy, or deploy itself by running its own CLI driver against its own files.

Current Status: 0.1.0-alpha

The GitHub repository was created in April 2026 and last pushed in May 2026. The project self-describes as "0.1.0-alpha" with specs stabilizing and minor breaking changes expected between alpha releases. The registry currently holds 47 AIPs, with AIP-1 through AIP-6 at Final status and AIP-7 onward at Draft or Review.