Practical guide / Development and agents
AGENTS.md and Skills: documenting a project for AI agents
An agent needs to find how the project builds, what to check and which boundaries to respect. That information needs a clear home and regular maintenance.
A repository can contain good code and still be difficult to change because its working knowledge lives in conversations and team habits. AGENTS.md provides a recognisable place for context a coding agent needs.
Its value becomes visible in a task: finding the right command, respecting a project decision and checking the result.
What is AGENTS.md?
It is an open Markdown instruction format. The official site suggests content such as environment setup, tests and conventions.
File discovery and instruction priority depend on the tool. Check its documentation rather than assuming every agent supports identical names, locations and precedence rules.
What belongs in the main file?
Start with information that prevents real mistakes:
| Content | Example |
|---|---|
| Structure | Source locations and generated files |
| Setup | Required dependencies and commands |
| Validation | Checks appropriate to different changes |
| Conventions | Rules that are not obvious from the code |
| Boundaries | Actions requiring review or authorisation |
Use commands you have tested. Where one file is generated from another, identify the editable source. That prevents fixes disappearing during the next build.
Keep credentials out of the file. Reference access documentation and use the intended secret-management mechanism.
What belongs in a Skill?
Skills package instructions, resources and, where appropriate, scripts for a specific task. Anthropic's design uses progressive loading so every procedure need not occupy every task's context.
Publishing, preparing assets or reviewing documents may warrant a separate procedure. Its description should make applicability clear, and its steps should identify the result to verify.
Avoid creating multiple Skills that repeat the same general team preference.
Test whether instructions help
Run a small representative task. Check which instructions were loaded, whether commands worked and whether validation caught the expected issue.
Remove obsolete rules and resolve contradictions. Version the documentation and review third-party changes: an instruction file should not independently expand execution permissions.
For defining the task itself, see specification-driven development.
Make the project usable by the next team
Write enough context for a person to understand it too. Commands, editable sources and acceptance criteria help both an agent and the next developer.
To organise that documentation, tell us which tasks are difficult to repeat.
Sources
Reviewed on 20 September 2026.
- Official AGENTS.md site.
- Anthropic: Agent Skills.
Checked on September 20, 2026