Skip to main content

The .agents Protocol

The .agents/ directory is an open standard for agent configuration. Define your skills, knowledge notes, and commands once, and they work across DotAgents, Claude Code, Cursor, Codex, and every tool adopting the protocol.

Protocol first, product second.

Why an Open Protocol?​

AI agents are proliferating across tools — coding assistants, voice interfaces, automation platforms. But each tool locks agent configuration into its own format. The .agents protocol solves this by providing a shared, file-based standard that any tool can read.

Your agents, skills, and knowledge notes become portable assets that travel with your projects.

Directory Structure​

.agents/
├── dotagents-settings.json  # General settings
├── mcp.json                 # MCP server configuration
├── models.json              # Model presets and provider keys
├── system-prompt.md         # Custom system prompt
├── agents.md                # Agent guidelines
├── layouts/
│   └── ui.json              # UI/layout settings
├── agents/
│   └── <agent-id>/
│       ├── agent.md         # Agent definition
│       └── config.json      # Agent-specific configuration
├── tasks/
│   └── <task-id>/
│       └── task.md          # Recurring loop/task definition
├── skills/
│   └── <skill-id>/
│       └── skill.md         # Skill definition and instructions
├── knowledge/
│   └── project-architecture/
│       ├── project-architecture.md  # Canonical note file
│       ├── diagram.png              # Note-local asset
│       └── db-schema.pdf            # Note-local asset
└── .backups/                 # Auto-rotated timestamped backups

Two-Layer System​

The .agents protocol uses a two-layer configuration system:

Global Layer (~/.agents/)​

  • Canonical source of truth for your global agent configuration
  • Created automatically on first app launch
  • Shared across all workspaces and projects
  • Stores global agents, skills, and knowledge notes

Workspace Layer (./.agents/)​

  • Optional overlay that lives in your project directory
  • Overrides global settings for project-specific configuration
  • Version-controllable with git
  • Set via explicit workspace configuration using the DOTAGENTS_WORKSPACE_DIR env var

Merge Semantics​

Final Config = Global Config + Workspace Config
                              (workspace wins on conflicts)

Agents, tasks, skills, and notes merge by ID — workspace versions override global versions with the same ID. JSON config files are shallow-merged by key, so avoid assuming nested objects merge deeply.

File Formats​

Markdown files in .agents/ use simple key: value frontmatter. It is not full YAML.

Agents (agent.md)​

Agents use markdown with frontmatter. Connection type is stored as connection-type in agent.md; nested connection details live in config.json.

---
kind: agent
id: code-reviewer
name: code-reviewer
displayName: Code Reviewer
description: Reviews code for bugs and security issues
enabled: true
role: chat-agent
connection-type: internal
---

You are an expert code reviewer...

## Guidelines

- Focus on security vulnerabilities
- Provide actionable feedback

Skills (skill.md)​

Skills are instruction files with metadata:

---
kind: skill
id: document-processing
name: Document Processing
description: Create, edit, and analyze .docx files
createdAt: 1234567890
updatedAt: 1234567890
source: local
---

# Document Processing Skill

## Overview
This skill enables working with Word documents...

Notes (.agents/knowledge/<slug>/<slug>.md)​

Notes are the canonical markdown knowledge artifacts in .agents/knowledge/. The small runtime-injected subset are working notes, selected with context: auto.

---
kind: note
id: project-architecture
title: Project Architecture
context: auto
updatedAt: 1234567890
tags: architecture, project, context
summary: Service-oriented Electron app with layered .agents config.
---

## Details

Additional notes and context...

Most notes should use context: search-only. Reserve context: auto for a tiny, curated set of high-signal working notes.

Note-Local Assets​

Notes can include related files in the same folder:

  • Images like diagrams or screenshots
  • Documents like PDFs or design notes
  • Any other supporting assets needed with the note

No fixed assets/ subfolder is required.

JSON Configuration Files​

Standard JSON files for structured settings:

// mcp.json
{
  "mcpServers": {
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." }
    }
  }
}

Resilience​

The .agents protocol is built to be resilient:

  • Atomic writes — Writes to a temp file first, then renames to prevent corruption
  • Timestamped backups — Auto-rotated backup copies in .backups/
  • Auto-recovery — Automatic recovery from corrupted files using backups
  • Human-readable — All files are markdown or JSON — editable by hand

Cross-Tool Compatibility​

The .agents/ directory is designed to work across AI tools:

ToolSupport
DotAgentsFull support (native)
Claude CodeSkills and knowledge notes
CursorSkills (via .cursor/ compatibility)
CodexSkills and agent configuration
OpenCodeSkills support

Skills and markdown-based .agents content are designed to stay portable across tools that adopt the protocol.

Next Steps​