MetaAgents

An open standard for composing agents from reusable skills and MCPs — with dependency resolution, naming rules, and MCP packaging built in.

Read the Spec GitHub

Why MetaAgents?

Existing standards define agents and skills in isolation. MetaAgents adds the missing pieces: how they compose, how they're named across publishers, and how MCPs they depend on stay portable across operating systems.

AGENTS.md tells an agent what to do
Agent Skills packages a single capability
MetaAgents declares how agents, skills, and MCPs depend on each other — and how MCP server configs ship without breaking on Windows

Core Concepts

Agent

An execution template that combines instructions with skills and MCPs.

AGENTS.md

Skill

A reusable capability package — methodology, knowledge, or workflow.

SKILL.md

MCP

A Model Context Protocol server configuration. Public servers are listed in the official MCP registry.

<namespace>_<short>.json

How It Works

Add MetaAgents fields to your frontmatter. name and scope are separate; dependencies reference other entries by their canonical URL.

---
name: code-reviewer
scope: example-org
description: Reviews PRs with security and style checks.
version: 1.0.0
dependencies:
  skills:
    - "https://github.com/example-org/catalog/tree/main/skills/security-audit"
    - "https://github.com/example-org/catalog/tree/main/skills/style-guide"
  mcps:
    - "https://github.com/example-org/catalog/tree/main/mcps/io.github.modelcontextprotocol_filesystem.json"
---

## Instructions

Review the PR for security vulnerabilities...

name is the kebab-case short identifier; scope is the optional publisher namespace (kebab-case, with reverse-DNS allowed for the scope part). The fully-qualified name is computed as <scope>/<name>.

MCP Packaging

MCP server configs ship as JSON files in mcps/. The on-disk filename replaces / in the FQN with _ for cross-platform compatibility (e.g. io.github.modelcontextprotocol/filesystem → mcps/io.github.modelcontextprotocol_filesystem.json).

{
  "_meta": {
    "name": "io.playwright/mcp"
  },
  "type": "stdio",
  "command": "npx",
  "args": [
    "-y",
    "@playwright/mcp@latest",
    "--storage-state",
    "${workspaceDir}/.playwright/storage-state.json"
  ]
}

Required _meta.*: name (the FQN). Two well-known placeholders are reserved:

${workspaceDir} — the active workspace's absolute path. Use for project-scoped state (per-workspace cookies, repo-local credentials).
${sharedDir} — a stable per-host directory chosen by the runtime. Use for state that belongs to the user account, not any single project (a global API token cache, model weights downloaded once per machine).

Hosts substitute these before spawning the MCP child, so the path the server sees is already absolute and platform-correct. Other shell expansions ($HOME, ~/, ${VAR}) and shell wrappers (["bash", "-c", "..."]) are forbidden — the MCP spec is literal and must work cross-platform.

Key Features

Backward compatible — an AGENTS.md / SKILL.md that omits the MetaAgents-only fields still parses as agents.md / Agent Skills
Separate name and scope — both are top-level frontmatter fields; the FQN is computed
URL-based dependencies — reference any public catalog by its canonical URL; cross-publisher composition works out of the box
Cross-platform MCPs — bare commands, literal args, and named placeholders for paths, so the same JSON ships to Windows and POSIX
Dependency graph — topological resolution with cycle detection; MCPs are leaves
Skill prerequisites — skills declare setup steps the LLM verifies after install (rejected on agents)
CHANGELOG conventions — every published entry ships a CHANGELOG.md with ## X.Y.Z (YYYY-MM-DD) headers and patch / minor / major bump guidance
Format-only — no opinions on package managers, runtimes, or execution

Comparison

	AGENTS.md	Agent Skills	MetaAgents
Agent instructions	✓		✓
Skill format		✓	✓
Dependency declarations			✓
Separate `name` + `scope`			✓
MCP packaging + cross-platform rules			✓
Graph resolution			✓

Get Started

MetaAgents is just YAML frontmatter in your existing markdown files plus a JSON shape for MCPs. No new tools required.

# 1. Add MetaAgents fields to your AGENTS.md
---
name: my-agent
scope: example-org
description: Does useful things.
version: 1.0.0
dependencies:
  skills:
    - "https://github.com/example-org/catalog/tree/main/skills/some-skill"
  mcps:
    - "https://github.com/example-org/catalog/tree/main/mcps/some_mcp.json"
---

# 2. Your skill declares its own deps
---
name: some-skill
scope: example-org
description: A reusable capability.
version: 1.0.0
dependencies:
  mcps:
    - "https://github.com/example-org/catalog/tree/main/mcps/another_mcp.json"
prereqs: "Run 'pip install x' first. Read references/setup.md for details."
---

Ecosystem

MetaAgents builds on existing community standards:

agents.md — the underlying instruction format for agents
Agent Skills — the underlying skill packaging format
Model Context Protocol — the underlying tool-server protocol for MCPs
MCP Registry — the official directory of public MCP servers; MetaAgents reuses its scope/name identifier convention for MCP _meta.name

Tools that don't understand MetaAgents simply ignore the extra frontmatter fields. Tools that do can resolve dependency graphs, install transitively, verify prerequisites, and spawn MCP children with the right per-workspace / per-host paths.