What Is AGENTS.md? How to Define What Your OpenClaw Agent Can Do

SOUL.md gets all the attention. It defines who your agent is, how it talks, and what it refuses to do. But SOUL.md doesn't determine what your agent can actually do. That's the job of AGENTS.md.

AGENTS.md is the capability manifest for your OpenClaw agent. It declares which tools the agent can access, what permissions each tool has, and what skill integrations are available. If SOUL.md is your agent's personality, AGENTS.md is its job description and access badge combined.

## How AGENTS.md Differs from SOUL.md

The confusion between these two files is the single most common support question we get at ClawSprout. Here's the short version:

- **SOUL.md** controls behavior: tone, personality, boundaries, instructions - **AGENTS.md** controls capabilities: tool access, skill declarations, permission levels, rate limits

A customer support agent might have a SOUL.md that says "be empathetic, confirm the issue before suggesting solutions, never promise refunds over $50." Its AGENTS.md would say "can read customer records, can send emails, can create support tickets, cannot modify billing data."

You can have a perfectly written SOUL.md and still have an agent that can't do anything useful because its AGENTS.md doesn't grant the right permissions. The reverse is also true: an agent with broad capabilities but a weak SOUL.md will have the tools but no idea how to use them well.

## The Structure of AGENTS.md

An AGENTS.md file has three main sections: skills, permissions, and constraints.

**Skills** are the integrations your agent can use. Each skill declaration includes a name, a version, and a scope. A skill declaration looks like this:

```markdown ## Skills

### email - provider: resend - scope: send, read - rate_limit: 50/hour

### calendar - provider: google - scope: read - rate_limit: 100/hour

### database - provider: postgres - scope: read - tables: customers, orders, products ```

Each skill maps to a real integration. The provider field tells OpenClaw which adapter to use. The scope field controls what operations are allowed. The rate_limit field prevents runaway agents from flooding external services.

**Permissions** define what the agent can do within each skill. OpenClaw uses a three-tier permission model: read, write, and admin. Read lets the agent query data. Write lets it create and update. Admin lets it delete, modify configurations, or manage other agents. Most agents should never need admin permissions.

**Constraints** are global limits that apply across all skills. Things like maximum API calls per minute, maximum tokens per response, and which domains the agent can make HTTP requests to. Constraints act as a safety net even if individual skill permissions are too broad.

## Common Configurations

Here are the AGENTS.md patterns we see most often across ClawSprout deployments:

**Customer support agent:** Email (send + read), knowledge base (read), ticketing system (write), customer database (read). No write access to billing. No admin permissions anywhere.

**Sales outreach agent:** Email (send), CRM (read + write), calendar (read + write), LinkedIn (read). Rate-limited to 20 emails per hour to avoid spam flags.

**Internal ops agent:** Slack (send + read), project management tool (read + write), database (read), document storage (read). Scoped to specific Slack channels and project boards.

**Research agent:** Web search (read), document storage (write), database (read). No email, no external communication tools. This agent gathers and organizes but never sends anything outward.

## Permission Levels in Detail

The three-tier model is simple on purpose. Here's what each level actually means:

**Read** is the safest default. The agent can query and retrieve data but cannot change anything. Start every skill at read-only and upgrade only when you have a specific reason.

**Write** lets the agent create new records and update existing ones. This is where most agents need to be for their primary function. A support agent that can only read tickets but can't respond to them isn't very useful. But write access should always be scoped to specific resources. "Can write to the support_tickets table" is better than "can write to the database."

**Admin** should be rare. Admin permissions let the agent delete data, modify configurations, or manage other agents. In most deployments, no agent should have admin access. If you think you need it, you probably need a human approval step instead.

## Mistakes to Avoid

**Granting broad permissions because it's easier.** The most dangerous AGENTS.md is one that gives every skill read-write-admin access. It works until the agent misinterprets an instruction and deletes a production table. Start restrictive and loosen only when you hit a real limitation.

**Forgetting rate limits.** Without rate limits, a confused agent can send hundreds of emails in minutes or hammer an API endpoint until you get blocked. Always set rate limits, even generous ones. You can increase them later if they're too tight.

**Duplicating SOUL.md content in AGENTS.md.** If you find yourself writing behavioral rules in AGENTS.md, stop. Behavioral rules go in SOUL.md. AGENTS.md is strictly about what the agent has access to, not how it should use that access.

**Not versioning skill declarations.** When a skill provider updates their API, your agent's integration can break. Pin skill versions in your AGENTS.md and update them deliberately after testing. ClawSprout handles this automatically, but if you're editing AGENTS.md manually, always include version numbers.

**Ignoring the constraint section.** Individual skill permissions can be correct while the overall agent is still dangerous. A global constraint like "maximum 200 API calls per minute across all skills" catches edge cases that per-skill rate limits miss.

## Configuring AGENTS.md in ClawSprout

ClawSprout's setup wizard generates your AGENTS.md when you select tools in step 3 of the quickstart flow. Each tool toggle adds the corresponding skill declaration with sensible defaults: read-only permissions, conservative rate limits, and the most common scope for that use case.

You can customize everything from the dashboard after setup. The visual editor shows each skill as a card with toggle switches for permission levels and input fields for rate limits. Changes are saved as standard AGENTS.md Markdown, so you can always export and edit manually if you prefer.

The key insight is that AGENTS.md is not a set-it-and-forget-it file. As your agent handles real interactions, you'll discover it needs access to things you didn't anticipate, or that it has access to things it shouldn't. Review your AGENTS.md monthly and adjust based on actual usage patterns. ClawSprout's activity logs show which skills your agent uses most and which permissions it's never touched, making it easy to tighten or expand access based on evidence.

Related posts