Agent folder layout

An agent is a directory. maiden discovers its capabilities by scanning that directory — nothing is registered in code. This page is the exhaustive list of what it looks for.

my-agent/
  agent.toml
  instructions.md
  skills/
  tools/
  connections/
  subagents/
  schedules/
  channels/
  evals/

Only agent.toml is required. Everything else is optional; a missing directory simply contributes nothing.

agent.toml (required)

The agent’s model and per-tool policy. See the agent.toml reference for every field.

instructions.md

The system prompt. By default maiden reads instructions.md next to agent.toml. You can instead set instructions (inline) or instructions_file (another path) in agent.toml — but not both.

skills/*.md

Extra guidance appended to the system prompt. Every *.md file under skills/ is read in filename order and joined onto the instructions under a # Skills heading. Use them to keep the base instructions short and layer in optional context.

tools/*.wasm

Sandboxed tools. Each *.wasm is a WASI-P2 component implementing maiden’s tool ABI. The tool name is the file stem — tools/fetch.wasm is the tool fetch. Its description and input schema are read from the component itself; agent.toml only overlays execution policy (timeout, memory, allowlist, secrets). See Add a sandboxed tool.

connections/*.toml

MCP servers. Each file describes an MCP server to launch; every tool the server advertises joins the agent’s registry alongside its WASM tools. Only the mcp-stdio transport is supported today. See Connect an MCP server.

subagents/<name>/

Nested agents. Each subdirectory is itself a complete agent folder, loaded recursively and exposed to its parent as a single tool named after the directory. A subagent uses its own agent.toml model. See Subagents.

schedules/*.toml

Time triggers. Each file fires a prompt on a fixed interval while the agent is served. See Schedules and channels.

channels/*.toml

Event triggers. Each file describes an inbound source that starts a run. Today the only kind is file-drop: a watched directory where each dropped JSON file becomes a message. See Schedules and channels.

evals/*.toml

Deterministic checks. Each file is a prompt plus a list of expect substrings the final answer must contain. maiden eval runs them. See Write and run evals.

Generated: .maiden/state/

Not authored — created at runtime. Thread snapshots live here as <thread>.json (subagent threads nest under subagents/<name>/). Safe to delete to reset conversation history; override the location with --state.