DRAFT · 2026-02-24 · dotagentsprotocol.com

.agents Protocol

An open directory convention for AI agent configuration. One place for MCP tools, AGENTS.md instructions, Skills, Memories, and model config — in plain, version-controllable files.

~/.agents/ directory layout

$ tree .agents/

.agents/
├── agents.md            # instructions (AGENTS.md compatible)
├── system-prompt.md     # system prompt
├── mcp.json             # MCP server configuration
├── models.json          # model presets & provider keys
├── skills/
│   └── code-review/
│       └── skill.md    # skill definition
└── memories/
    └── project-arch.md  # persistent memory

§ overview § ecosystem § structure § formats § get started

1. Overview

Why another convention?

Problem: Fragmentation

× MCP config in one place, AGENTS.md in another, skills scattered as vendor files
× Vendor lock-in: .cursor/ .claude/ .github/copilot-instructions.md
× No way to version-control or share a complete agent configuration
× Agent knowledge (memories, skills) lost between tools and sessions

Solution: .agents/

→ One directory (.agents/) houses everything an agent needs
→ Vendor-neutral — works with any AI tool, editor, or agent framework
→ Git-friendly — commit, diff, branch, and share entire agent configs
→ Layered — global at ~/.agents/, workspace at ./.agents/

2. Ecosystem

Five open standards. One directory.

standards mapping .agents/ ← convergence point

Standard	Steward	Purpose	Maps to
MCP ↗ Anthropic · Linux Foundation	Anthropic · Linux Foundation	Open standard for connecting AI to external tools and data. Agents discover and invoke tools via stdio, HTTP, or WebSocket.	`mcp.json`
AGENTS.md ↗ OpenAI · Linux Foundation	OpenAI · Linux Foundation	Simple markdown format for guiding coding agents. Build steps, conventions, project-specific instructions.	`agents.md`
Skills ↗ Anthropic	Anthropic	Codified procedural knowledge. Instruction files that teach agents specific tasks. Composable and portable.	`skills/*/skill.md`
ACP ↗ Zed Industries	Zed Industries	Open standard for agent-to-editor communication. Any ACP agent integrates with any compatible editor.	`agent profiles`
Memories .agents protocol	.agents protocol	Structured memory entries that persist across sessions. Tagged, searchable, importance-ranked.	`memories/*.md`

Note: The .agents/ directory is a convergence point, not a replacement. Each standard retains its own specification. This protocol defines how they coexist as files in a single, predictable location.

3. Directory Structure

Two layers with overlay semantics. Workspace overrides global.

full layout

.agents/
├── speakmcp-settings.json  # general settings
├── mcp.json                # MCP servers & tools
├── models.json             # model presets & keys
├── system-prompt.md        # system prompt
├── agents.md               # agent guidelines
├── layouts/
│   └── ui.json             # UI/layout prefs
├── skills/
│   ├── code-review/
│   │   └── skill.md
│   └── deploy-pipeline/
│       └── skill.md
├── memories/
│   ├── arch-decisions.md
│   └── user-prefs.md
└── .backups/               # auto-rotated
    ├── skills/
    └── memories/

LAYER 1 — GLOBAL

~/.agents/

Canonical config. Created on startup, synced with settings changes. Base layer for all projects.

LAYER 2 — WORKSPACE

<project>/.agents/

Optional overrides. Shallow-merges with global — workspace wins. Commit to git for team config.

MERGE ORDER

defaults ← config.json ← ~/.agents ← ./.agents

JSON: shallow-merge by key. Skills/memories: merge by ID (newest wins).

4. File Formats

Simple frontmatter + markdown for content. Plain JSON for config. No YAML dependency.

skills/code-review/skill.md

---
id: code-review
name: Code Review Expert
description: Thorough code review
enabled: true
---

Review code changes for:
- Security vulnerabilities
- Performance implications
- Test coverage gaps

memories/arch-decisions.md

---
id: arch_001
title: Database Architecture
content: PostgreSQL with Drizzle ORM
importance: high
tags: database, architecture, orm
---

We chose PostgreSQL over MongoDB for
relational data integrity and complex
query support across billing.

mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@mcp/server-filesystem"],
      "transport": "stdio"
    },
    "github": {
      "url": "https://api.github.com/mcp",
      "transport": "streamable-http"
    }
  }
}

agents.md

---
kind: agents
---

# Project Guidelines

## Build & Test
- Use `pnpm` for package management
- Run `pnpm test` before committing
- TypeScript strict mode required

Frontmatter format: Uses --- fences with simple key: value lines. Not full YAML — no external dependencies. Values can be quoted. List fields accept CSV (tags: a, b, c) or JSON arrays (tags: ["a", "b"]). Keys are sorted deterministically for clean diffs.

5. Design Principles

Constraints that shaped the protocol.

Principle	Rationale
Human-readable	Plain JSON and Markdown only. No binary formats, no proprietary schemas. Open any file in a text editor.
Version-controllable	Deterministic key sorting for clean diffs. Commit entire agent config to git — review, branch, collaborate.
Portable	Relative paths, no vendor lock-in. Share as profile packs, transfer between machines, distribute as packages.
Safe by default	Atomic writes (temp+rename). Timestamped backups with rotation. Auto-recovery from parse failures. Workspace layer only discovered if already present.
Layered	Global defaults at ~/.agents, workspace overrides at ./.agents. Shallow merge for configs, ID-based merge for skills and memories.
Extensible	Add new config files without breaking existing ones. Simple frontmatter avoids YAML dependency bloat.

6. Getting Started

Adopt incrementally. Start with what you need.

Create the directory

$ mkdir -p .agents/skills .agents/memories

Add agent guidelines

Compatible with the AGENTS.md standard.

# .agents/agents.md

# Project Guidelines
- Use TypeScript strict mode
- Run `pnpm test` before every commit
- Follow existing patterns

Configure MCP servers

// .agents/mcp.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@mcp/server-filesystem", "."]
    }
  }
}

Add skills as needed

# .agents/skills/deploy/skill.md
---
name: Deploy to Production
description: Our deployment workflow
---

1. Run `pnpm test`
2. Build with `pnpm build`
3. Deploy via `./scripts/deploy.sh`

✓

Commit and share

Your .agents/ directory is now a portable, version-controlled agent configuration.