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

External tools, of two kinds. kind = "mcp-stdio" launches an MCP server and joins every tool it advertises to the registry; kind = "openapi" reads an OpenAPI 3.0 or Swagger 2.0 spec and turns each allowed operation into a tool. Both land alongside the agent’s WASM tools on the same dispatch path, and both take a filter (tools.allow for MCP, operations.allow for OpenAPI). stdio is the only MCP transport today. See Connect an MCP server and Connect an OpenAPI API.

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. The kinds are file-drop (a watched directory where each dropped JSON file becomes a message), telegram, slack, discord, github, linear and twilio. Every kind but file-drop and telegram receives its events as signed inbound webhooks and serves its own port. 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.