Envelope Team

Envelope Team

Design and generate .envelope.json AI agent team definition files — the open standard for building and deploying multi-agent teams on Envelope.

When to Use This Skill

• User asks to build, design, or generate an Envelope team
• User describes a workflow that could be automated by a team of AI agents
• User wants to create a .envelope.json file for deployment
• User needs help with agent hierarchy, access policies, or gates

What This Skill Does

• Takes a natural-language description of the team's purpose
• Designs the agent hierarchy (supervisor → managers → workers)
• Generates a schema-valid .envelope.json file
• Includes access policies, variables, secrets, and gates as appropriate
• Explains any schema concepts the user asks about

How to Use

Basic Usage

Build me an Envelope team for customer support triage — one supervisor,
two agents that read Zendesk tickets, and a Slack notifier for escalations.

Create an Envelope team definition for outbound sales — an SDR manager
overseeing two SDRs who work HubSpot leads and a RevOps analyst.

With human-in-the-loop gates

Build an Envelope team that drafts marketing emails and pauses for
human approval before sending.

Example

User: "Build me an Envelope team for content moderation — a supervisor and two reviewer agents that check posts against community guidelines."

Output:

{
  "$schema": "https://schema.openenvelope.org/team/v1.json",
  "name": "Content Moderation Team",
  "slug": "content-moderation",
  "version": "1.0.0",
  "description": "A supervisor and two reviewer agents that check posts against community guidelines.",
  "visibility": "team",
  "category": "ops",
  "requiredVariables": ["companyName"],
  "requiredSecrets": ["MODERATION_API_KEY"],
  "metadata": { "generatedBy": "Claude Code · openenvelope.org" },
  "agents": [
    {
      "key": "supervisor",
      "name": "Moderation Supervisor",
      "role": "supervisor",
      "capabilities": ["Route content to reviewer agents", "Aggregate decisions", "Escalate edge cases"],
      "model": "anthropic:claude-sonnet-4-5",
      "systemPrompt": "You supervise the content moderation team at {{companyName}}. Delegate each item to a reviewer and consolidate their verdicts."
    },
    {
      "key": "policy-reviewer",
      "name": "Policy Reviewer",
      "role": "reviewer",
      "capabilities": ["Check content against community guidelines", "Flag policy violations"],
      "model": "anthropic:claude-haiku-3-5",
      "systemPrompt": "You review content for policy violations at {{companyName}}. Return a verdict of approve, flag, or remove with a reason.",
      "reportsToKey": "supervisor",
      "accessPolicy": {
        "accessPolicyVersion": "1",
        "rules": [
          { "host": "api.moderation-service.com", "action": "allow" },
          { "host": "*", "action": "deny" }
        ]
      }
    },
    {
      "key": "spam-reviewer",
      "name": "Spam Reviewer",
      "role": "reviewer",
      "capabilities": ["Detect spam, bot activity, and duplicate content"],
      "model": "anthropic:claude-haiku-3-5",
      "systemPrompt": "You detect spam and bot activity at {{companyName}}. Return a verdict of approve, flag, or remove with a confidence score.",
      "reportsToKey": "supervisor"
    }
  ]
}

Schema Reference

Top-level fields

| Field | Required | Description |

|---|---|---|

| $schema | yes | Always https://schema.openenvelope.org/team/v1.json |

| name | yes | Human-readable team name |

| slug | yes | URL-safe, lowercase, hyphens only |

| version | yes | Semver e.g. "1.0.0" |

| description | yes | What this team does |

| visibility | yes | "public" · "team" · "private" |

| requiredVariables | no | Non-sensitive config, interpolated via {{varName}} |

| requiredSecrets | no | API keys, stored encrypted, injected as ${SECRET_NAME} |

| schedule | no | Cron schedule { cron, timezone, task } |

| agents | yes | Agent definitions |

| gates | no | Human-in-the-loop checkpoints |

Agent fields

| Field | Required | Description |

|---|---|---|

| key | yes | Unique identifier within this file |

| name | yes | Display name |

| role | yes | Free-form e.g. "supervisor", "analyst", "sdr" |

| capabilities | yes | What this agent can do — used for delegation routing |

| model | yes | e.g. anthropic:claude-sonnet-4-5, anthropic:claude-haiku-3-5 |

| systemPrompt | yes | Agent instructions. Use {{varName}} and ${SECRET_NAME} |

| reportsToKey | no | key of manager agent. Omit for the top-level supervisor |

| accessPolicy | no | Outbound HTTP allowlist |

Hierarchy rule

Exactly one agent should have no reportsToKey — this is the supervisor that receives the initial task. All others reference their manager's key.

Access policy

"accessPolicy": {
  "accessPolicyVersion": "1",
  "rules": [
    { "host": "api.example.com", "action": "allow" },
    { "host": "*", "action": "deny" }
  ]
}

Human-in-the-loop gates

"gates": [
  {
    "name": "approval-check",
    "type": "approval",
    "trigger": { "afterAgent": "drafter" },
    "onApprove": "continue",
    "onReject": "halt"
  }
]

Tips

• Use anthropic:claude-sonnet-4-5 for supervisors and managers; anthropic:claude-haiku-3-5 for leaf agents doing repetitive work
• Put anything org-specific (company name, support email, Slack channel) in requiredVariables
• End access policy rules with { "host": "*", "action": "deny" } for a strict allowlist
• Add gates before any agent that sends emails, posts publicly, or makes purchases
• Validate before deploying: npx @openenvelope/schema validate ./team.envelope.json

Links

• openenvelope.org — deploy and run teams
• schema.openenvelope.org/team/v1.json — JSON schema
• npmjs.com/package/@openenvelope/schema — TypeScript types + validator
• openenvelope.org/mcp — run teams via MCP from Claude.ai or ChatGPT