agents.md: your agent’s operating manual

agents.md is your agent’s operating manual. It defines the agent’s job, whether it works alone or coordinates others, the steps it follows, and when it must hand off to a human. Where soul.md shapes character, agents.md shapes conduct. Without it, even a well-defined agent reinvents its process for every task.

Who the agent is versus how it works

Think of a skilled craftsperson. Their temperament — patient, exacting, generous — is their soul. The way they set up the bench, check their measurements and decide when to call in a second pair of hands is their method. 干将 the sword-smith had both: a vision of the blade and a disciplined process for forging it. agents.md is the process, written down so the agent follows it the same way every time.

The four core fields

• job: the mission in one or two sentences. What the agent is for, and what success looks like.
• agentRole: solo or orchestrator. A solo agent does the work; an orchestrator plans, delegates to other agents and checks their output.
• steps: the ordered procedure. For example: clarify the request, gather what is needed, propose an approach, do the work, check it, report back.
• escalation: the conditions under which the agent stops and brings a human in — uncertainty, risk, irreversible actions, or anything outside its access.

What AgentSoul adds from your type

The agents.md you get from a forge goes beyond the four fields. A Gao Dao file names a role archetype — such as Principled Architect, Attuned Companion or Deep Investigator — and sets a hierarchy of priorities, a level of proactivity, a collaboration protocol, a decision style and voice constraints. Flash Forge writes a more compact version built around proactivity and challenge tolerance: how readily the agent pushes back on you. Both close with a failure-mode section: in Gao Dao files it reads like “if I drift, you will see this; pull me back toward that”, and in Flash Forge files it is a rule for what to do when unsure. All of these follow from your reading. If your result includes a type (Gao Dao), you will see it here too: a Type 8 soul tends toward decisive action and plain speech, while a Type 6 soul tends to surface risks and check before acting.

Tailoring escalation

If you change only one thing in agents.md, make it the escalation rule. It is where personality meets consequence. An agent with a bold temperament may need a firmer rule about irreversible actions; an agent with a cautious one may need permission to proceed on low-risk tasks without asking every time. Write the rule in concrete terms:

• Always ask before deleting, sending, publishing or spending anything.
• Ask when two reasonable interpretations of a request lead to different results.
• Proceed without asking on reversible, low-stakes steps, and mention what was done.
• Stop and say so when the task needs access the agent does not have.

Using agents.md in your tools

In OpenClaw, agents.md is one of the four workspace files loaded at the start of each session, usually named AGENTS.md. In Cursor and Hermes, a project-root AGENTS.md is read automatically, and AgentSoul’s agents.md makes a strong skeleton for it. In Claude Code, import it from CLAUDE.md. In chat assistants, distil the steps and escalation rule into a few lines of custom instructions. Wherever it goes, trim steps that do not apply to the work at hand: an operating manual is only useful if it describes the job you actually give the agent.

The reading behind agents.md is an AI-generated hypothesis, not a diagnosis. Treat the file as a solid first draft of your agent’s method, and revise it as you see how it works in practice.