A project-level instruction file that an AI coding agent may load before handling a task. In autonomous workflows it behaves like executable context, so any command, path, or setup step inside it must be treated as potentially adversarial until reviewed and approved.
Expanded Definition
AGENTS.md is a project-scoped instruction file that an AI coding agent may ingest before it acts on a repository task. In practice, it functions as trusted operational context, which makes it materially different from ordinary documentation or README content. Because the file can shape tool use, file access, command execution, and setup behavior, its contents should be treated as executable guidance until verified against policy and repository intent.
Usage is still evolving across agent frameworks, but the security issue is consistent: instructions inside the file can redirect an agent toward unsafe commands, unexpected paths, or hidden assumptions about environment state. That places AGENTS.md squarely in the NHI and agentic AI governance domain, especially when paired with the risks described in the OWASP Agentic AI Top 10 and the NIST AI Risk Management Framework.
The most common misapplication is treating AGENTS.md as harmless documentation, which occurs when teams allow an agent to execute repository instructions without review, provenance checks, or task-scoped restrictions.
Examples and Use Cases
Implementing AGENTS.md safely often introduces friction because teams must balance agent autonomy against the cost of verification, approval, and repo-specific guardrails.
- A development team uses AGENTS.md to describe build steps, but requires human approval before any command that installs packages or modifies production configuration.
- An AI coding agent reads AGENTS.md to learn test conventions, while policy blocks it from following instructions that point to untrusted scripts or external downloads.
- A security team reviews AGENTS.md content during pull requests to ensure the file does not embed credential locations, privileged paths, or environment variables that could be abused.
- A platform team pairs AGENTS.md with task-level allowlists so the agent can only access the files needed for a specific ticket, not the whole repository.
- A governed workflow uses AGENTS.md as an onboarding aid for the agent, but validates any setup step against the repository owner’s approved runbook before execution.
NHIMG has documented how agentic systems can be abused through tool and instruction paths in cases such as Analysis of Claude Code Security and Amazon Q AI Coding Agent Compromised, both of which show why instruction-file trust boundaries matter.
Why It Matters in NHI Security
AGENTS.md matters because it can become an attack surface for non-human identities that act with execution authority. If the file is poisoned, copied from an untrusted source, or granted excessive authority, the agent may amplify a low-grade repository issue into secrets exposure, destructive operations, or unauthorized code changes. That risk is especially relevant in environments where agents can reach CI/CD systems, package managers, cloud credentials, or deployment scripts.
The operational stakes are high. NHI Mgmt Group reports that 79% of organisations have experienced secrets leaks, with 77% of these incidents resulting in tangible damage, which is a strong indicator that any file influencing agent behavior deserves strict control. A well-governed AGENTS.md process should support least privilege, change review, and task scoping, not open-ended autonomy. Guidance from the MITRE ATLAS adversarial AI threat matrix and the CSA MAESTRO agentic AI threat modeling framework helps frame these risks as adversarial, not merely operational.
Organisations typically encounter the consequences only after an agent runs a malicious or stale instruction file, at which point AGENTS.md becomes operationally unavoidable to address.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Agentic AI Top 10 and OWASP Non-Human Identity Top 10 address the attack and risk surface, while NIST AI RMF, NIST CSF 2.0 and NIST Zero Trust (SP 800-207) set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Agentic AI Top 10 | NHI-01 | Agent instruction files are a prompt-injection and tool-abuse exposure point. |
| OWASP Non-Human Identity Top 10 | NHI-02 | Instruction files can expose or redirect access to secrets and credentials. |
| NIST AI RMF | Risk management requires governance over AI inputs, outputs, and operational context. | |
| NIST CSF 2.0 | PR.AC-1 | Access control governs what an agent can execute after reading repository instructions. |
| NIST Zero Trust (SP 800-207) | SC-7 | Zero trust demands verification before executing machine-readable instructions. |
Review AGENTS.md as untrusted input and restrict agent actions to approved tools and paths.
Related resources from NHI Mgmt Group
- What governance controls should every enterprise put in place before deploying AI agents?
- What is MCP Step-Up Authorisation and how does it implement least privilege for agents?
- When is it crucial to implement least-privilege access for AI agents?
- What is the difference between managed identities and hardcoded secrets for AI agents?
