Appearance

Authoring Crews (v2) ​

Crews are named teams that bind one coordinator role, one or more worker roles, optional skills, a workflow, and a communication topology. This guide uses the current v2 coordinator tools. For prompt ordering and runtime-owned invariants, see the canonical Composition Guide.

The v2 artifacts ​

ArtifactFile suffixResponsibility
Role.role.mdPersona for either a coordinator or worker
Skill.skill.mdReusable knowledge composed into roles
Workflow.workflow.mdStages and coordinator execution guidance
Crew.crew.mdCoordinator, members, workflow, and topology

Names must be lowercase kebab-case: release-coordinator, not Release_Coordinator. Save tools serialize roles, skills, and crews and manage versioned backups such as name.v1.role.md, name.v1.skill.md, and name.v1.crew.md. save_workflow instead writes the supplied full Markdown verbatim after linting it.

Create a complete crew with coordinator tools ​

The examples below form one small documentation crew and are suitable as coordinator tool arguments.

1. Save the coordinator role ​

json
{
  "name": "docs-coordinator",
  "description": "Coordinates documentation drafting and review",
  "agentType": "coordinator",
  "systemPrompt": "You coordinate documentation work.\n\n## Operating approach\n\nBreak requests into drafting and review work, delegate each part, and synthesize a concise final result.",
  "whenToUse": "When a documentation crew needs orchestration"
}

Call save_role with that object. A coordinator role defines the long-lived crew persona. It does not become a worker and should not claim worker tools.

2. Save worker roles ​

Call save_role once for each worker persona:

json
{
  "name": "docs-writer",
  "description": "Writes clear project documentation",
  "agentType": "coder",
  "systemPrompt": "You write accurate project documentation.\n\n## Approach\n\nRead the implementation and existing docs, make focused edits, and preserve the repository's style.",
  "whenToUse": "When documentation files must be created or updated"
}
json
{
  "name": "docs-reviewer",
  "description": "Reviews documentation for accuracy and clarity",
  "agentType": "reviewer",
  "systemPrompt": "You review documentation against source code.\n\n## Review approach\n\nReport factual errors, missing prerequisites, broken examples, and ambiguous wording with file references.",
  "whenToUse": "After documentation changes need an independent review"
}

agentType selects the runtime permission profile. For example, reviewer is read-only and coder can edit. Prose in a role cannot expand those permissions.

3. Save an atomic skill ​

json
{
  "name": "docs-conventions",
  "description": "Shared conventions for project documentation",
  "systemPrompt": "## Documentation conventions\n\nUse descriptive headings, language-tagged code fences, relative internal links, and examples verified against the current implementation.",
  "tags": ["documentation", "markdown"],
  "allowOverride": false
}

Call save_skill with that object. Skills add knowledge and instructions; they do not add write, shell, MCP, or messaging permissions.

4. Save a workflow from full Markdown ​

Call save_workflow with the complete .workflow.md document in content:

json
{
  "name": "docs-draft-review",
  "tier": "project",
  "content": "---\nname: docs-draft-review\ndescription: Draft documentation, then review it\nrunner: coordinator-per-stage\nstages:\n  - name: draft\n    agents: [docs-writer]\n  - name: review\n    agents: [docs-reviewer]\n    after: [draft]\n---\n\n## Documentation workflow\n\nDelegate the requested documentation changes to the writer, then have the reviewer verify the result against the implementation."
}

The tool lints the supplied Markdown, refuses error-severity diagnostics, and writes the accepted content verbatim as .fleet/workflows/docs-draft-review.workflow.md. It does not synthesize or reformat the document.

5. Save the crew ​

save_crew uses members in its tool input (the serialized crew file uses the v2 agents: field):

json
{
  "name": "docs-crew",
  "description": "Drafts and reviews project documentation",
  "topology": "hub",
  "workflow": "docs-draft-review",
  "coordinator": {
    "role": "docs-coordinator"
  },
  "members": [
    {
      "role": "docs-writer",
      "skills": ["docs-conventions"],
      "parallel": true
    },
    {
      "role": "docs-reviewer",
      "skills": ["docs-conventions"],
      "after": "all"
    }
  ],
  "tier": "project"
}

The coordinator role controls orchestration. Entries in members are worker roles; each can compose zero or more skills and optionally declare parallel, after, model, mcpServers, or a display name.

6. Reload and activate ​

After all saves, refresh the in-memory registry:

json
{}

Call reload_registry with that empty object. Then activate the crew:

json
{
  "name": "docs-crew"
}

Call activate_crew with that object. Tool-driven activation is deferred until the coordinator's next message. The equivalent user command is:

text
/crew docs-crew

Generate a project-specific crew ​

For a guided synthesis flow, run:

text
/crew generate <name>

For example:

text
/crew generate api-maintenance

The coordinator profiles the project, calls save_role for one coordinator and worker roles, calls save_skill for reusable project knowledge, calls save_crew with members, and offers to activate the result. Do not use the legacy v1 create flows for v2 authoring.

Topology and ordering ​

TopologyWorker communication
silentIndependent workers; no inter-agent communication tools
hubWorkers report through the coordinator
meshWorkers can also communicate with peers

parallel: true permits concurrent members. after: all waits for all other members, while after: [role-name] waits for named dependencies. Topology and communication tools are runtime-owned; role or skill text cannot change them.

User and project tiers ​

save_role and save_skill currently write project-tier files. save_workflow and save_crew accept tier: "project" or tier: "user" and default to project.

Bundled and user artifacts load automatically. Project workflows load under their separate workflow policy, but project roles, skills, and crews are default-off and require --trust-project-skills or AGENTS_FLEET_TRUST_PROJECT_SKILLS=1 when a session starts.

There is one important current-session edge: save tools are trusted coordinator operations, so they can write project artifacts in the running session. reload_registry still applies that session's trust configuration, and a restart reevaluates trust from startup flags, environment, and config. Saving a project crew does not permanently opt future sessions into project artifact discovery.