Instructions and description

An agent has values people read and values a run uses, and they live in different places.

Name and description help people recognise the agent in lists and on its page. Neither is passed to the model. How the agent should work goes in the repository's AGENTS.md or CLAUDE.md.

Write how to work in the repository fileCopy Anchor Link

There is one way to tell an agent how to work, how to answer, and which rules to keep: put an AGENTS.md (else CLAUDE.md) at the root of the repository the session works in. The card has no field for such text.

• Commit the file. A session reads the committed content when it starts, so a change reaches new sessions without a version or a release.
• It is read only when the profile has project_settings.claude_md: true. With it off, the file is not passed to the model even if it exists. Turn it on under "Read the repository's CLAUDE.md" on the profile's page. The local profile claude-coding-local has it on.
• A session reads the file of the repository it started in, so agents on the same repository share it.

How to write itCopy Anchor Link

The agent's role is its author's to define. The platform adds no sentences that set a role or personality, only facts it alone knows. They are listed under What the model reads today.

• Skip years of experience and inflated adjectives. "A top senior developer with 30 years of experience" says nothing about the work the agent takes on.
• Give the scope in one line.
• Name allowed actions with concrete verbs and a reason. With a reason, the agent can apply the same judgment in situations you did not write down.

Analyze payment incidents.
Read logs and summarize the cause.
Do not change code, because the owning team reviews every change.

Values from earlier cardsCopy Anchor Link

Earlier cards had "Role" (role) and "Instructions" (instructions) fields, and after them an "Agent instructions" (agent_instructions) field. The first two were never passed to the model, and the agent instructions field has been removed.

• New cards do not send these values. Values in versions already saved stay, but no screen shows them and no run uses them.
• A client that still sends agent_instructions is not refused. The key is dropped and never stored.
• To keep using what you wrote in the agent instructions, move it into the repository's AGENTS.md or CLAUDE.md.

Card fieldsCopy Anchor Link

Name (1–120 characters) and description (0–2,000 characters) are fields of the agent, not the card. Send them as name and description to POST /v1/agents and PATCH /v1/agents/{id}.

Choosing tools in the web consoleCopy Anchor Link

In card editing (the "What it does" step of a new agent, and Edit settings on the agent's page), "Tools it may use" is a checklist of one profile's tools.

• "Profile to choose tools from": pick one of the profiles that run the card's model. The new-agent flow lists first the profiles it can release without a repository, and picks the chosen one first in the release step. This value is not saved on the card.
• With "Every tool the profile does not block at release" on, tools is null. Turn it off and the checked tools are tools. Unchecking a tool is what forbids it.
• When saving, the tool_policy.per_tool entries of unchecked built-in tools are removed, because a release refuses a policy for a built-in tool it does not run. MCP tool policies stay.
• A name in tools that the profile does not have shows checked as "Not in the profile" and can only be turned off.
• Below the list is the number of profiles that allow every tool chosen. At 0, the card cannot be saved.
• An existing card's forbidden shows as a list, and "Clear blocked tools" empties it. Until then, those tools stay off in the checklist and cannot be changed.

What the model reads todayCopy Anchor Link

The worker adds these instructions to the model's system prompt, in this order.

1. For a session without a repository, a single line stating that out/ is the directory whose files a checkpoint collects as outputs.
2. AGENTS.md at the repository root, else CLAUDE.md. When the profile has project_settings.claude_md: true, the committed content is read. A CLAUDE.md that links to AGENTS.md, or is only an @AGENTS.md line, is read once. The local profile claude-coding-local has it on.

The text of item 1 is also placed at the workspace root as AGENTS.md, with CLAUDE.md a link to it. Both are listed in .git/info/exclude, so they never get into a commit. When the repository already has an AGENTS.md or a CLAUDE.md, neither is overwritten. The model still gets the same text in its system prompt.

The platform adds no other paragraph to the model's prompt. It writes no sentences that set a role or behavior and passes on facts only. The platform paragraph that earlier builds added is gone; the worker still recognizes the checkpoint fingerprints made with it, so existing sessions resume as before.

Editing and versionsCopy Anchor Link

Sending a card makes PATCH /v1/agents/{id} add a new version. To change only the name or description, send only name or description; no version is created. Sending a card identical to an existing version adds nothing. This continues with AID and WEB from Create.

curl -sS -X PATCH "$API/v1/agents/$AID" "${WEB[@]}" -d '{
  "description": "Reads the repository and answers questions",
  "card": {
    "model": "claude-sonnet-5",
    "language": "en",
    "capabilities": { "tools": ["Read", "Grep", "Glob"], "mcp": null },
    "rules": [{ "id": "no-guess", "text": "Never invent a file path.", "source": "user" }]
  }
}' | jq -c '.versions[] | {version_no, language: .card.language}'

{"version_no":1,"language":"follow-user"}
{"version_no":2,"language":"en"}

A new version does not change the active release. To use it, create a release from that version and activate it (Create). In the web console, "Save" in Settings does the same thing and shows the difference between the two versions.

Next stepsCopy Anchor Link

• Choose a profile: The profile that releases and sessions use
• Permissions: Tool permissions and agent administrators