One Markdown file per agent
AgentLang is an open format for defining an AI agent: YAML frontmatter for its settings, a Markdown body for its instructions. It names the coding agent that runs it (Claude Code, Codex or OpenCode), the exact model, pinned skills and the connections it may use. The host that runs it keeps the lock.
---
name: PR reviewer
description: Reviews a pull request and posts one verdict comment.
harness: claude
model: claude-opus-5-5
effort: high
skills:
- https://github.com/anthropics/skills/tree/main/skills/webapp-testing
connections: [linear]
capabilities: { browser: true }
---
You review pull requests for correctness, security and tests.
Post exactly one comment that starts with APPROVE or BLOCK.The shape people already write
Claude Code subagents, Anthropic's ant apply and OpenCode all define agents as Markdown with frontmatter. name, description, model and effort are the keys Claude Code subagents use.
The file says what; the host pins it
Each save becomes an immutable revision recording the exact model, CLI release and skill commits it resolved to. The file stays short and portable; nobody tracks CLI releases by hand.
No secrets, no surprises
Connections are names, never URLs or tokens, so a file is safe to commit and share. Unknown keys are refused, so a typo never changes what runs.
A spec, not a compiler to everything
Version 0.1 of AgentLang was a YAML language with a compiler, signed containers and encrypted prompts, meant to run on any framework. It is withdrawn. Every attempt to compile one agent definition to many runtimes loses meaning on the way: the same instructions replace the system prompt in one coding agent and are added to it in another, effort levels differ per model, and tool names share no vocabulary. The formats that spread, like AGENTS.md and SKILL.md, are read in place.
So version 0.2 is a file a host runs as written, plus one export: a host may write the agent's own coding agent's native configuration, and must refuse, with a report, anything that cannot carry over.
Status
Draft 0.2, October 2026. Rush is building the first host. The spec will change while that lands; breaking changes are listed in the spec's change log.