AGENT.md
An open, tool-agnostic standard for defining AI agent project guidelines.
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:
- YAML frontmatter — Structured, schema-validated metadata (
version,role,context,priorities,tech,rules,change-policy,output, etc.) - 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?
| Need | AGENT.md |
|---|---|
| One source of truth | Write once; generate Cursor rules, claude.md, Copilot agents |
| Validation | agentmd lint checks frontmatter against the schema before you commit |
| Consistency | Same priorities, rules, and change-policy across all generated outputs |
| Evolve safely | version and schema let format and tooling evolve without breaking existing files |
How it differs from tool-specific guidance
| File | Scope | Schema | Generation |
|---|---|---|---|
| AGENT.md | Tool-agnostic, one definition | Yes (JSON Schema) | Feeds adapters → Cursor, Claude, Copilot |
| AGENTS.md | Free-form Markdown; no frontmatter | No | Consumed directly by many agents |
| .cursor/rules/*.mdc | Cursor only | Cursor’s frontmatter | Produced by AGENT.md → Cursor adapter |
| claude.md | Claude only | No | Produced by AGENT.md → Claude adapter |
| .github/agents/*.agent.md | GitHub Copilot only | Copilot’s frontmatter | Produced by AGENT.md → Copilot adapter |
- 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.
| Field | Purpose |
|---|---|
version |
Schema version, e.g. "1.0" (required) |
name |
Short name for the profile (e.g. for Copilot) |
description |
One-sentence purpose of the agent |
role |
Persona, e.g. "Senior backend engineer" |
context |
project, domain, audience (or a string) |
priorities |
Ordered list, e.g. ["correctness", "security"] |
tech |
stack, versions, constraints |
rules |
List of strings or { description, globs?, id? } |
change-policy |
branching, commits, reviews, breaking |
output |
formats, conventions, docs |
extends |
Path or URL to a parent AGENT.md |
globs |
File patterns for path-scoped rules |
alwaysApply |
Hint for “always apply” where supported |
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
-
New frontmatter fields
Add them in your AGENT.md. The schema allowsadditionalProperties: true, so extra keys are kept. For shared tooling, you can propose new optional fields in the schema and spec. -
Custom body sections
Add any## Sectionyou need. Adapters can pass them through or map them to tool-specific sections. -
New adapters
Implement a writer that (a) parses AGENT.md (frontmatter + body), (b) optionally resolvesextends, and (c) emits the target format. See adapters/ for the built-in Cursor, Claude, and Copilot templates. -
Schema evolution
Theversionin 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
| Command | Description |
|---|---|
agentmd init |
Create a scaffold AGENT.md in the current directory |
agentmd lint |
Parse AGENT.md and validate frontmatter against the schema |
agentmd generate |
Produce tool-specific files (Cursor, Claude, Copilot) from AGENT.md |
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:
| Adapter | Output | Notes |
|---|---|---|
| Cursor | .cursor/rules/agent-from-agentmd.mdc |
Uses description, globs, alwaysApply in frontmatter |
| Claude | claude.md |
Structured sections from frontmatter + body |
| Copilot | .github/agents/agent.agent.md |
YAML frontmatter (name, description) + instructions from AGENT.md |
Templates: adapters/.
Examples
| Project type | Path |
|---|---|
| WordPress | examples/wordpress/AGENT.md |
| Node.js | examples/nodejs/AGENT.md |
| Python | examples/python/AGENT.md |
Tests and CI
- Tests:
pytestforagentmd lintandagentmd generate(see tests/). - CI:
.github/workflows/agentmd.ymlruns 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
Metadata
Release files for agentmd 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentmd-0.1.0.tar.gz | 57.2 kB | Without provenance | Details for agentmd-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentmd-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentmd-0.1.0-py3-none-any.whl |
Total release size: 68.9 kB
Release files / agentmd-0.1.0.tar.gz
| Download URL | agentmd-0.1.0.tar.gz |
|---|---|
| Size | 57.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2e6603ecdf4ebd0c28ec23e2091b5499dc4218947d26c0602c670ea9d1089d82
|
|
BLAKE2b-256 checksum How to use checksums |
a13f923a48125baaf9cdd008d7d12bbfa07779b7b943efbda53b5ee26a7a3ac3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.15.0 pkginfo/1.8.3 requests/2.27.1 setuptools/41.2.0 requests-toolbelt/1.0.0 tqdm/4.64.1 CPython/2.7.18
|
Release files / agentmd-0.1.0-py3-none-any.whl
| Download URL | agentmd-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e855e9456f8cffb66c45dc0bb06fe515a10e314488956321de44c1fa898f9203
|
|
BLAKE2b-256 checksum How to use checksums |
67a632dec66a095bad1512899b5feadab5914ccd9351ea17c5898f0aaddd289e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.15.0 pkginfo/1.8.3 requests/2.27.1 setuptools/41.2.0 requests-toolbelt/1.0.0 tqdm/4.64.1 CPython/2.7.18
|
Security for agentmd 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.