MADL files
Export a team as a Multi-Agent Descriptor Language file that other tools can read, and import MADL files as teams.
MADL, the Multi-Agent Descriptor Language, is an open, vendor-neutral file format for describing a multi-agent system. A MADL file holds:
- the agents and the groups they are in;
- who hands work to whom, and how agents communicate;
- global settings, and settings for each agent;
- the restrictions each agent works under.
Use it to share a team with tools other than Sculptured, to keep a readable copy in a Git repository, or to bring in a system designed elsewhere.
| Export | The team's Settings → Export → Export team file. The file goes to your downloads as <team>.madl.yaml. Leave Include folders off to share it. |
| Import | New project → Advanced: import a team file or a past run → choose a .madl.yaml (or .json) file, or paste it, then Import. |
What is kept
A team exported from Sculptured and imported again comes back unchanged. Everything is in MADL's own fields, with nothing in a Sculptured-only extension, so another MADL tool sees the whole team.
| Sculptured | MADL |
|---|---|
| Agents, their Jobs and kinds | agents, with instructions and runtime: claude-code or codex |
| Groups | groups, and each agent's groups |
| Hands work to, reports to, watches | connections of kind handoff, report, watch |
| The Input | inputs |
| Models | each agent's model, written as provider/model |
| Token, turn and time limits | settings.restrictions.budget, as { soft, hard } |
| Run budgets | system.budget |
| Contracts: what an agent reads, writes and decides | data_access and authority |
| Skills | skills, embedded as { name, description, body } |
| Checks | checks |
| Schedules | policies.schedules |
| Positions on the board | layout |
| Workflows: stages, routes, limits, and a dispatch command | workflows |
| Components, and the ones each agent uses | tools, given to agents by id |
| Restricted permissions | settings.restrictions.approvals, as runtime-permissions |
| The project folder and own copies | defaults.preferences.workspace |
| Question timeout | defaults.preferences.questions |
| Protections | preferences.context |
| Your Claude Code setup | preferences.config |
| An agent's briefing (full or minimal) | preferences.briefing |
| Safety rules | restrictions.tools.refuse |
| Plan pauses | system.budget.plan[].pause |
| The decision log | a channel with medium decision-log |
Importing a MADL file from elsewhere
MADL can describe more than Sculptured runs today. Importing keeps what Sculptured can use and lists the rest by its place in the file, under Not imported:
- People (
runtime: human) are not board agents; people answer agents' questions from the app. - Other runtimes, such as CAMEL or CrewAI, are imported as Claude Code agents.
- Delegate and review connections become hands work to; ask and approve connections are not kept.
- Tools become components. Channels (other than a decision log), communication rules, steps outside a workflow and placement are not kept yet. Skills named only by a path or name are listed under Not imported, because the file does not carry them; embedded skills are kept.
A file that is not valid MADL is refused with each error and where it is. A MADL file that refers to other files ($ref) can't be uploaded as it is. Join it into one file first with madl expand:
cargo install --git https://github.com/Sculptured/Multi-Agent-Descriptor-Language madl-cli
madl expand team.madl.yaml > one-file.madl.yaml
The madl command also validates a file (madl validate), shows every agent's effective settings (madl resolve) and draws it (madl graph).