The collaboration between developers and AI is shifting from simple prompts to a more sophisticated partnership, guided by structured instruction sets. This evolution is driven by emerging standards like AGENTS.md, which serve as a “README for agents” by providing the necessary context to work effectively on a project (e.g. https://github.com/openai/agents.md) Understanding these formats is crucial for developers seeking to harness the full potential of autonomous AI systems.
Guiding AI with AGENTS.md
The AGENTS.md file is a predictable and centralized location for project-specific instructions for AI agents. Its primary goal is to accelerate an AI’s “onboarding” process, providing immediate context on a project’s architecture, conventions, and testing procedures. This structured guidance helps improve the quality and consistency of the AI’s output, ensuring its contributions align with existing project standards.
GitHub’s support for AGENTS.md in its Copilot coding agent marks a move toward a unified standard for instructing AI assistants, for example in VSCode.
Defining Workflows with agentic.md
While AGENTS.md focuses on instructing an existing agent, a more advanced format, agentic.md, allows developers to define and execute entire agentic workflows from a Markdown file (e.g. https://github.com/drivly/agentic.md). This standard uses a combination of Markdown text and Mermaid diagrams to create executable blueprints for AI agents. With agentic.md, the file itself becomes a version-controlled, executable definition of an agent’s logic and behavior.
Choosing the Right Approach
The choice between the two formats depends on whether the goal is to guide a powerful, general-purpose agent or to define a new, specialized one.
| Format | Primary Use Case | Key Feature | Best For |
|---|---|---|---|
AGENTS.md |
Instruction | Provides project context and guidelines to an existing AI agent. | Guiding general-purpose agents like GitHub Copilot to ensure consistency and quality within a specific codebase. |
agentic.md |
Definition | Defines an agent’s properties and executable workflow using Markdown and Mermaid diagrams. | Building and version-controlling new, specialized agents with predictable, state-driven logic. |
Practical Implementation
These standards are most effective when paired with powerful tools like GitHub Copilot in agent mode, for example in VSCode. By creating an AGENTS.md file in a repository, a developer can provide the agent with a high-level summary of the project, instructions for building and testing, and details on coding standards. This context transforms the AI from a generic tool into a context-aware partner, enabling it to operate autonomously and efficiently within the established development workflow.
Comments