agentmd

AGENT.md

An open, tool-agnostic standard for defining AI agent project guidelines.

Spec · Schema · Examples

AGENT.md gives you a single, schema-validated definition of how AI coding agents should work in your project. From one AGENT.md file, you can generate tool-specific instruction files for Cursor, Claude, GitHub Copilot, and others—keeping your rules in one place while staying compatible with each tool.

---

What is AGENT.md?

AGENT.md is a project file that describes:

• Who the agent is (role, context)
• What matters most (priorities, tech stack, rules)
• How to change code (branching, commits, reviews)
• What to produce (docs, formats, conventions)

It uses:

1. YAML frontmatter — Structured, schema-validated metadata (version, role, context, priorities, tech, rules, change-policy, output, etc.)
2. Markdown body — Human-friendly sections for setup, testing, code style, and more

Think of it as a README for AI agents that is both machine-parseable and human-editable.

---

Why AGENT.md?

How it differs from tool-specific guidance

• AGENTS.md is intentionally minimal: plain Markdown, no schema. Great when you want a quick, universal set of hints.
• AGENT.md adds structure: frontmatter + optional body. Use it when you want to validate, extend (extends), and generate tool-specific files from one place.

You can use both in a project: e.g. a short AGENTS.md for generic “read this first” and a richer AGENT.md for teams that use the CLI and adapters.

---

Quick start

1. Create AGENT.md

Put AGENT.md at your project root. Minimal example:

---
version: "1.0"
---

## Setup
- `pnpm install`
- `pnpm dev`

## Testing
- `pnpm test`

2. Optional: use the CLI

# Scaffold a new AGENT.md
agentmd init

# Validate frontmatter against the schema
agentmd lint

# Generate Cursor, Claude, and Copilot files from AGENT.md
agentmd generate

3. (Optional) Generate tool-specific files

agentmd generate writes:

• Cursor: .cursor/rules/agent-from-agentmd.mdc
• Claude: claude.md
• Copilot: .github/agents/agent.agent.md

You can choose targets, e.g. agentmd generate --target cursor,claude.

---

How to write AGENT.md

Frontmatter (optional but recommended)

When you use frontmatter, version is required. Everything else is optional.

Full spec: spec/SPEC.md. Schema: schema/agentmd.schema.json.

Markdown body

Use normal Markdown. These sections are conventional and work well with adapters:

• ## Setup — Install, env, run
• ## Testing — How to run tests and CI
• ## Code Style — Lint, format, naming
• ## Architecture — Patterns and layers
• ## Security — Sensitive data, safeguards
• ## Deployment — Build and release

Extending another AGENT.md

---
version: "1.0"
extends: "../AGENT.md"   # or a URL
priorities: [performance]  # overrides parent’s priorities for this key
---

The parent’s frontmatter is deep-merged; the child overrides. The child’s body replaces the parent’s body.

---

How to extend AGENT.md

1. New frontmatter fields
   Add them in your AGENT.md. The schema allows additionalProperties: true, so extra keys are kept. For shared tooling, you can propose new optional fields in the schema and spec.

2. Custom body sections
   Add any ## Section you need. Adapters can pass them through or map them to tool-specific sections.

3. New adapters
   Implement a writer that (a) parses AGENT.md (frontmatter + body), (b) optionally resolves extends, and (c) emits the target format. See adapters/ for the built-in Cursor, Claude, and Copilot templates.

4. Schema evolution
   The version in frontmatter tracks the schema. New optional properties are minor additions; breaking changes to existing required/optional structure should bump the spec’s major version.

---

CLI: agentmd

Install

pip install -e .   # from the repo root
# or
pip install agentmd   # when published

Examples

agentmd init
agentmd lint
agentmd generate
agentmd generate --target cursor,claude --out .cursor/rules,.

---

Adapters

Adapters turn AGENT.md (frontmatter + body) into tool-specific files:

Templates: adapters/.

---

Examples

---

Tests and CI

• Tests: pytest for agentmd lint and agentmd generate (see tests/).
• CI: .github/workflows/agentmd.yml runs lint and tests, and validates that generated Cursor/Claude/Copilot files are non-empty and well-formed.

---

Repository structure

.
├── spec/SPEC.md           # Formal specification
├── schema/
│   ├── agentmd.schema.json
│   └── agentmd.schema.yaml
├── adapters/              # Adapter templates (Cursor, Claude, Copilot)
├── examples/              # WordPress, Node.js, Python
├── src/agentmd/           # CLI and library
├── tests/
├── pyproject.toml
├── README.md
└── AGENT.md               # This project’s own AGENT.md

---

License and contributing

• License: MIT (or as specified in the repository).
• Contributing: Open an issue or PR on GitHub. For schema or spec changes, please update both the JSON schema and spec/SPEC.md.

---

References

• AGENTS.md — Simple, open format for agent instructions
• Cursor Rules
• Claude Code / CLAUDE.md
• GitHub Copilot Custom Agents