Agents.MD

What is agents.md?

agents.md is a lightweight, human-readable contract that defines how software agents should behave within a system.

Purpose

• Alignment: Captures the agent’s goals, boundaries, and decision principles.
• Consistency: Standardises behaviour across environments and teams.
• Governance: Makes assumptions, constraints, and safety rules explicit and reviewable.

Typical Contents

• Role & scope: What the agent is responsible for (and what it is not).
• Capabilities & tools: Which actions, APIs, or resources it may use.
• Decision logic: High-level policies, priorities, and escalation rules.
• Constraints: Security, compliance, and operational limits.
• Lifecycle: How the agent is initialised, monitored, and updated.

Why it matters

By externalising intent and rules from code, agents.md improves transparency, auditability, and long-term maintainability of agent-driven systems.

Agents.MD examples

• Agency Swarm
• Oh-my-posh
• AWS HPC Recipes
• RabbitMQ server
• AI Agents for Beginners
• Dart Code
• Vercel Labs Agent-skills
• Sentry
• Cloudflare workers SDK

References

• https://agentsmd.net/agents-md-examples/
• https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
• https://www.builder.io/blog/agents-md
• https://developers.openai.com/codex/guides/agents-md
• https://www.claude.com/blog/using-claude-md-files