Skip to main content
An agent folder is a directory of plain files — agent.yaml, an instruction file, and one subdirectory per thing the agent needs — that the CLI loads into a bundle and installs. Use this when you are building an agent as a project you check into version control and iterate on locally. Reach for the raw bundle document instead when you are installing something someone else already published, or scripting an install with no local files at all.

​
Prerequisites

  • A running platform and a workspace — see Run AgentArea locally.
  • The agentarea CLI, signed in: agentarea login --api-url=<api>.
  • Nothing else. agent.yaml is the only required file.

​
The folder layout

Anything else — a stray README.md, a file directly under skills/ — is skipped with a warning, not an error. The whole folder describes one agent; there is no way to define more than one per folder. An entity <key> — the file or directory stem under mcp/, skills/, schedules/, channels/, or policies/ — matches [a-zA-Z][a-zA-Z0-9_-]*: a letter, then any mix of letters, digits, _, and -. A setup field’s key in agent.yaml is stricter, [a-zA-Z][a-zA-Z0-9_]* with no dashes, since it is interpolated literally into ${setup.<key>}.

​
Steps

1

Scaffold the folder

This lays down agent.yaml and instructions.md. Edit agent.yaml:
and instructions.md:
name is the only required field. It also becomes the bundle’s name — the key a redeploy matches against, so renaming it starts a new agent rather than updating this one. model takes a literal model instance id or, as above, a ${setup.<key>} reference resolved from --set at deploy time.Three more settings are optional:
reasoning_effort is a level the model takes, such as low or high; reasoning_max_tokens is a token budget instead. Set one or neither, never both. A level the model’s catalog entry does not list blocks the deploy, since every run would refuse it. client runs the agent’s tasks through the runner of a Codex or Claude Code client of the workspace, named by the client’s id — a literal id or a ${setup.<key>} reference. A client’s name is not unique, so a name is refused; a client you may not use, or one that is no runner’s, blocks the deploy.
2

Attach an MCP server

One file per server, under mcp/; the file’s stem is the key other files reference it by. Name a server from the catalog by its id, and give it the credentials it asks for:
The id is the catalog spec’s full name: <server> for a remote server, and for one the platform runs the full name plus /docker or /command, for example io.github.n24q02m/better-telegram-mcp/oci/docker.io/n24q02m/better-telegram-mcp-latest/docker. The server connects the way the catalog’s connect flow connects it, so the folder carries no endpoint, command or image. A bindings key is a header for a remote server and an environment variable otherwise. An id the catalog does not have blocks the deploy.A binding takes its value one of two ways:${secret.<name>} must be the whole value — put a prefix such as Bearer into the secret itself. The secret must already exist in the workspace (create it on the Secrets page or with POST /v1/workspaces/<workspace>/secrets), and you must be allowed to use it: its creator or a workspace admin. Otherwise the plan blocks naming the binding, and the plan shows each reference as <name> from secret '<secret>' to <host>, the host the value is sent to. A secret reference anywhere else in the server’s spec blocks the plan.A server that is not in the catalog takes its spec instead:
Set exactly one of catalog or json_spec. Docker and URL servers are always supported. A command-type server is only supported when the command is npx, uvx, uv, python, python3, node, bunx, or deno — a local path or a ${CLAUDE_PLUGIN_ROOT}-relative binary is not. An unsupported command does not fail the deploy; it shows as unsupported in the plan and the agent is created without that tool.
3

Attach a skill

Everything in the skill’s directory installs with it — a script under skills/cite-sources/scripts/, a reference doc — as one skill package; the agent reads the files when it activates the skill. SKILL.md must sit at the top of the directory. Binary files are skipped, like everywhere else in the folder.
4

Add a schedule, a channel, or a policy

All three are optional, and all three bind to the one agent in this folder.
Leave enabled out of a schedule or channel and it installs disabled — see schedule an agent for activating it afterwards. A policy’s subject defaults to this agent; set it to workspace to bind the rule to the whole workspace instead.
5

Preview the plan

Reads the folder — skipping dotfiles, node_modules, .git, and binary files, capped at 5MB total — and prints the plan without writing anything. Every entity is tagged create, update, unchanged, orphaned, changes not applied, already exists, or unsupported, alongside any issue found (a reference to an MCP key that does not exist, a binding that points at an undeclared setup field or a secret you may not use, a required setup field with no --set value and no default, and the like). A blocking issue stops the deploy; a warning does not.
6

Supply setup values and deploy

--set supplies one key=value pair per setup field; repeat it for each one. A required field with no value and no default in agent.yaml blocks the install before anything is written. Without --yes, deploy shows the same plan as --dry-run and asks for confirmation before it writes; add --yes to skip the prompt in a script or CI job. --workspace can instead be set once with agentarea workspace use acme.The install carries out exactly the plan you confirmed, setup values included. If anything changed it in between — a teammate’s deploy, an entity deleted by hand — the install refuses with the deploy plan changed since it was shown and writes nothing; run deploy again to see the new plan.

​
What a redeploy changes

Run agentarea deploy again against an edited folder and it reconciles the workspace against the new content, matched by the bundle’s name — not by re-creating everything:
  • An agent, skill, schedule, channel, or policy this folder created before is updated in place when its file changed or a --set value it references changed — --set model_id=<new-id> against an otherwise untouched agent.yaml still shows as an update — and left alone otherwise.
  • A changed skill is stored as its next version, so the skill’s history keeps the one before it.
  • MCP servers are never updated on redeploy. Edit mcp/github.yaml and redeploy, and the existing server instance is unchanged; the plan keeps showing changes not applied on every redeploy until you change it by editing the MCP server directly, not through the folder.
  • Removing a file does not delete what it created. Delete schedules/daily.md and redeploy, and the schedule it created keeps running — the plan shows it as orphaned, not deleted. There is no prune flag; removing an entity for real is a manual step today.
  • Nothing is matched by name. An agent, MCP server, skill or schedule that only carries the same name — one a teammate made by hand, for instance — is not this folder’s, and the deploy creates its own. Something an earlier install linked instead of creating shows as already exists and is never changed. A rule with the same subject, target, effect, params and condition as a policy file is the one exception: the deploy reuses it rather than writing a second, and the plan says already exists. A rule that differs in any of them — a $1000 cap against the file's $10 — is another rule, and the deploy creates the file’s.
  • An agent this folder created and someone has since archived counts as gone: the deploy creates the agent again.
  • A redeploy changes only the agent’s tools and skills the folder declares or the last deploy attached. A tool, delegate or skill added to the agent in the workspace stays, a declared tool keeps the settings it was given there, and every approval on the agent’s tools stays as it was. reasoning_effort, reasoning_max_tokens and client are set only when agent.yaml names them, or named them last time and no longer does, which clears them.
  • A redeploy does not ask for a secret again. Repeat a --set only for a value an entity needs for the first time (it is being created) or one you are intentionally replacing. A channel’s stored credentials — a bot token, for instance — are rewritten only when you pass a new value for them; leave --set telegram_bot_token=... out and the one already stored keeps working. A credential that names a workspace secret is never replaced by a value: passing one for it blocks the deploy, so change that secret instead.
  • Updating an entity this folder owns needs edit permission on it. If a teammate changed its permissions, or someone else now owns it by hand, the deploy stops on that entity instead of silently skipping it.
  • A deploy that fails partway through removes whatever it created before the failure. An update it already applied stays, and the next deploy plans it again, so re-running the same command finishes the job.

​
Verify

confirms the agent exists under the name from agent.yaml. To confirm it actually runs, submit a task against its id — see start a task.

​
Troubleshooting

The folder root has no agent.yaml. Every agent folder needs one at the top level; it cannot live in a subdirectory.
Check the plan’s issues — an unrecognized path, a binary file, or anything outside the layout above comes back as a warning, not an error, and is left out of the bundle.
A field in agent.yaml’s setup list has required: true, no default, and no matching --set key=value on the deploy command. Supply it, or give it a default in agent.yaml if a missing value is actually fine.
Its json_spec.command is not one of the runtimes the platform can run (npx, uvx, uv, python, python3, node, bunx, deno), or it references a local path. The agent still deploys, without that tool attached.

Bundles

The document an agent folder loads into, and why it is portable by key

Create and configure an agent

Build the same agent directly over the API instead of from files

Schedule an agent

Activating the cron automation a schedules/ file installs disabled

Set a budget

The ceiling types available to a policies/ file’s cap effect
Last modified on November 10, 2026