AGENTS.md, a README.md for agents.

2026-02-13 · Source: AI on Medium · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering · Depth: Intermediate, quick

Summary

AGENTS.md is an open, standardized file format designed to provide context and instructions specifically for AI coding agents working on software projects. Used by over 60,000 open-source projects, it functions as a "README for agents," complementing the human-focused README.md by detailing build steps, tests, and coding conventions relevant to AI. The format aims to offer agents a predictable location for guidance, keeping human-oriented documentation concise. Additionally, the `.agents/skills` folder introduces a lightweight, open format for extending agent capabilities. Each skill is a folder containing a `SKILL.md` file with metadata and instructions, optionally bundling scripts, templates, and reference materials. Skills use progressive disclosure, loading only name and description initially, then full instructions upon activation, and executing bundled code as needed. An example implementation in Lobechat demonstrates how AGENTS.md structures development guidelines, including tech stack, directory structure, and workflow.

Key takeaway

For AI Architects integrating coding agents into development workflows, adopting the AGENTS.md standard and defining custom agent skills can significantly improve agent effectiveness and project maintainability. You should establish AGENTS.md files in your repositories to provide explicit, machine-readable instructions for AI agents, ensuring consistent behavior and reducing the need for agents to infer project specifics. This approach streamlines AI-assisted development and keeps human-facing documentation clean.

Key insights

AGENTS.md and agent skills provide structured, open formats for guiding AI coding agents in software development.

Principles

• Separate human and agent documentation.
• Provide predictable instruction locations.
• Use progressive disclosure for agent context.

Method

Agent skills load name/description at startup, full instructions upon task match, then execute bundled code or reference files as needed, optimizing context management.

In practice

• Adopt AGENTS.md for AI agent instructions.
• Define agent skills in `.agents/skills` folders.
• Structure `SKILL.md` with metadata and instructions.

Topics

• AGENTS.md
• AI Coding Agents
• Agent Skills
• Agent Instruction Format
• Open-Source AI Development

Code references

• lobehub/lobehub

Best for: AI Architect, AI Engineer, Machine Learning Engineer, Software Engineer

Related on AIssential

• Writing a Good AGENTS.md — Effective `AGENTS.md` files are concise, human-written, and focus on essential, non-redundant information.
• The Agentic AI Toolkit: MCP vs. Agent Skills vs. AGENTS.md — MCP, Agent Skills, and AGENTS.md form a standardized toolkit for AI agent connectivity and behavior.
• A Primer on Using Agent Skills — Agent skills provide a modular, dynamic way to equip AI agents with specific capabilities, improving efficiency and reliability.
• tech-leads-club / agent-skills — Agent Skills provides a secure, validated, and extensible library of capabilities for AI coding agents.
• Learn to equip AI agents with reusable skills — Agent skills provide on-demand, specialized knowledge to AI agents through standardized, reusable task-specific modules.
• Agent Skills Work but the Research Shows Most Teams Are Building Them Wrong — Curated, focused agent skills improve AI performance, but require structured organization and security diligence to scale effectively.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by AI on Medium.