Teams
Team is a combination of multiple specialized Agents: a set of AI workers each with its own role + shared norms (ANNOUNCEMENT / NORMS) + a collaboration/orchestration structure, optionally accompanied by runnable workflow templates. This page explains how to build a team package: member structure, orchestration config, repository layout, and publishing rules. For a single Agent, see Agents. ← Back to Assets · 中文原版
1. Concept Overview & Core Philosophy
| Concept | Description |
|---|---|
| Team Package | A self-contained, Hub-publishable directory artifact defining a group of Agents + shared norms + orchestration |
| Manifest (team.json) | team.members[] member structure, team.workflow orchestration, team.workflows workflow files |
| Member | Agent definitions under members/{slug}/, including ROLE.md etc. |
| Norms injection | ANNOUNCEMENT.md + NORMS.md injected into each member’s context after installation |
| Workflow | YAML DAG templates that can run automatically as task sequences |
Core philosophy: every Agent in a team must be specialized. Don’t take a generic template and just rename it — each member needs a unique identity, expertise, and detailed role documentation; safety constraints live in each member’s
POLICIES.md, not by removing tools.
2. Repository Structure (Artifact Directory)
~/.markus/builder-artifacts/teams/{team-name}/ ← {name} must be a valid slug
├── team.json # main config (manifest)
├── README.md # public description (Hub/Builder display, REQUIRED)
├── ANNOUNCEMENT.md # team announcement
├── NORMS.md # working norms
├── images/
│ └── icon.png # team icon (becomes avatar after install)
├── workflows/ # workflow templates (optional)
│ └── {workflow-name}.yaml # YAML workflow DAG
└── members/
├── {manager-slug}/
│ ├── ROLE.md # identity & system prompt (REQUIRED)
│ ├── HEARTBEAT.md # periodic patrol (RECOMMENDED)
│ ├── POLICIES.md # constraints/guardrails (optional)
│ ├── CONTEXT.md # domain context (optional)
│ └── images/ # member avatars
└── {worker-slug}/ # (same structure)
Only ~/.markus/builder-artifacts/teams/ is recognized by package_list / package_install. Don’t write to ~/.markus/shared/, the workspace, or anywhere else.
Install Destinations
| Package file | Deployed to | Purpose |
|---|---|---|
ANNOUNCEMENT.md | ~/.markus/teams/{teamId}/ANNOUNCEMENT.md | Injected into each member’s context |
NORMS.md | ~/.markus/teams/{teamId}/NORMS.md | Injected into each member’s context |
members/{name}/ROLE.md | ~/.markus/agents/{agentId}/role/ROLE.md | Member identity / system prompt |
members/{name}/HEARTBEAT.md | ~/.markus/agents/{agentId}/role/HEARTBEAT.md | ~30-min patrol |
members/{name}/POLICIES.md | ~/.markus/agents/{agentId}/role/POLICIES.md | Additional constraints |
members/{name}/CONTEXT.md | ~/.markus/agents/{agentId}/role/CONTEXT.md | Domain context |
members/{name}/images/ | ~/.markus/agents/{agentId}/role/images/ | Member avatar |
workflows/*.yaml | ~/.markus/teams/{teamId}/workflows/*.yaml | Runnable workflow templates |
3. Three-Step Workflow
Manifest first, then content files, then optional workflow YAML. Never inline file content into JSON. This rule applies to every mode (chat / task / A2A).
file_writeteam.json(manifest, see §4).file_writeeach file in turn: README / ANNOUNCEMENT / NORMS / each member’s ROLE.md, etc. (see §5).- Optional: write
workflows/*.yamlworkflow templates.
4. Manifest (team.json) Core Fields
{
"type": "team",
"name": "dev-squad", // slug, kebab-case, same rules as agent
"displayName": "Development Squad", // human-readable (may be Chinese)
"version": "2.0.0",
"description": "Team purpose and goals",
"author": "",
"icon": "images/icon.png",
"category": "development", // development | devops | management | productivity | general
"tags": ["development", "sprint"],
"i18n": { "zh-CN": { "displayName": "开发小队", "description": "…", "members": { "Tech Lead": "技术负责人" } } },
"team": {
"members": [
{ "name": "Tech Lead", "slug": "tech-lead", "roleName": "Tech Lead",
"role": "manager", "count": 1, "skills": ["team-building"] },
{ "name": "Backend Developer", "role": "worker", "roleName": "backend-developer",
"skills": ["coding-tools"] }
],
"workflow": {
"phases": ["plan", "implement", "review", "validate"],
"parallelImplementation": true,
"worktreeIsolation": true,
"requireReviewBeforeComplete": true
},
"workflows": ["workflows/content-publishing.yaml"]
}
}
Package Name (Slug) — Hard Rule
name is the package slug (directory name, Hub URL segment, share/publish ID). Rules are the same as Agent: English kebab-case only (lowercase letters/digits/hyphens), 2–64 chars, starts with a letter; not allowed: Chinese / space / underscore / uppercase / emoji; the human-readable name goes in displayName. Member directory slugs under members/ must also be English kebab-case. When the user only gives a Chinese name, invent an English kebab slug and keep the original name in displayName.
| User language | name (slug) | displayName |
|---|---|---|
| 智库研究团队 (Chinese) | think-tank-research | 智库研究团队 |
| ”Frontend Squad” (English) | frontend-squad | Frontend Squad |
Member Fields (team.members[]) — REQUIRED
| Field | Description |
|---|---|
name | Display name — may be Chinese (e.g. 技术负责人) |
slug (recommended) | kebab-case slug matching the members/{slug}/ directory name. Required when name contains non-ASCII — Chinese auto-kebab drops Unicode, causing directory misalignment and broken avatars |
roleName (recommended) | English display name, fallback for directory matching |
role | Only "manager" or "worker" — the UI uses it for coloring and management |
count | Instance count (usually 1), required |
skills | Skill IDs (from the dynamic context) — assign proactively; don’t leave empty |
⚠️ Hard rules:
membersmust be nested underteam(not at the root level);rolecan only be manager/worker;countis required;categorymust be in the enum; don’t putmembers/skillsat the root level; each team has exactly 1 manager + ≥1 worker.
Orchestration (team.workflow) & Workflow Templates
phases: array of team work phases (e.g.["plan", "implement", "review", "validate"]).parallelImplementation: whether multiple members work in parallel during implementation;worktreeIsolation:truerecommended for coding teams (git worktree isolation);requireReviewBeforeComplete: whether tasks must pass review before completing.workflows/*.yaml: step DAGs with dependencies (steps[].id/name/type/role/prompt/depends_on/inputs). After install, copied to~/.markus/teams/{teamId}/workflows/and runnable via the Workflows UI orworkflow_run. Full YAML format: see the workflow-building skill.
5. Content File Specs
- README.md (REQUIRED): public description shown on Hub/Builder — what the team does, what it solves, member composition, key capabilities, deployment scenarios (2–4 paragraphs).
- ANNOUNCEMENT.md: team mission, member introductions, collaboration style, key capabilities (at least 3 paragraphs).
- NORMS.md: phased process matching
team.workflow.phases— who owns each phase, which platform capabilities to use, file/module ownership for parallel development, communication protocol (when toagent_send_message/agent_broadcast_status), referencingspawn_subagent/background_exec/shell_execute/ worktree /deliverable_create. This is crucial for team effectiveness. - Each member’s ROLE.md: written individually, at least 5 substantive paragraphs (refer to existing base role templates), same style as Agents / ROLE.md.
- HEARTBEAT.md (RECOMMENDED), POLICIES.md (optional), CONTEXT.md (optional).
Visual Assets
- Team icon
images/icon.png: abstract logo/badge style (shield / gear / nodes / stars), no portraits. - Member avatars
members/{slug}/images/avatar.jpg: realistic digital portraits, same rules as Agent avatars.
6. Create ≠ Install (Red Line)
Creating an artifact ≠ installing/deploying. Only use package_install / hub_install when the user explicitly says “install” / “deploy” / “hire”. Once installed into an organization, each member of the team becomes a real Agent — assignable to tasks and collaborating together.
7. Next Steps
- Single Agent structure & building → Agents.
- Give members reusable capabilities → Skills.
- Publish the team package to the community → Markus Hub.