AGENTS.md Tutorial: Configuring Agent Capabilities the Right Way
If SOUL.md is your agent's personality, AGENTS.md is its resume. This file declares what tools your agent can access, what skills it has installed, what external services it can connect to, and what permission boundaries constrain its actions. Getting AGENTS.md right is the difference between an agent that works reliably and one that fails in confusing ways.
The AGENTS.md File Structure
AGENTS.md uses a structured Markdown format with specific sections that the OpenClaw runtime parses. The core sections are capabilities (what the agent can do), permissions (what it's allowed to access), skills (installed skill manifests), and integrations (connected external services).
Each capability entry includes a name, description, and permission scope. For example, a "send-email" capability would declare that it needs write access to the email integration and read access to the contact list. The OpenClaw runtime enforces these declarations. If a skill tries to access a resource not declared in AGENTS.md, the request gets blocked.
Permission Scoping Done Right
The most common AGENTS.md mistake is over-permissioning. New builders grant every skill access to everything because it's easier than figuring out the minimum permissions. This works until a skill misbehaves and has unrestricted access to your email, calendar, and file system.
Follow the principle of least privilege. Each skill should declare only the permissions it actually needs. Read access where possible, write access only when necessary, and admin access never unless there's no alternative. ClawVortex's visual editor color-codes permission levels so you can see at a glance which skills have broad access.
Multi-Agent AGENTS.md Configuration
When you run multiple agents in a fleet, each agent gets its own AGENTS.md. The router agent needs permission to invoke other agents but shouldn't have access to end-user data. Specialist agents need access to their domain-specific tools but shouldn't invoke other specialists directly. That's the router's job.
This separation of concerns prevents cascading failures. If the billing agent's email skill breaks, it doesn't affect the tech support agent's ability to search the knowledge base. Each agent's failure domain is contained by its AGENTS.md boundaries.
Testing Your Configuration
Before deploying a new AGENTS.md, validate it. The OpenClaw CLI includes a validate command that checks for schema errors, missing dependencies, and permission conflicts. But schema validation only catches syntax problems.
Behavioral testing, running your agent through real scenarios and verifying it uses only its declared capabilities, is equally important. ClawVortex's stress testing simulates adversarial inputs that try to trick your agent into exceeding its permissions. If your AGENTS.md has a gap, the stress test will find it before a real user does.
Versioning and Change Management
AGENTS.md should be version-controlled alongside your SOUL.md. Every capability change is a potential behavior change. Track what changed, when, and why. When something breaks in production, being able to diff your AGENTS.md against last week's version is invaluable for quick diagnosis.