# Envelope Skill

> **Envelope is the multi-agent designer.** It helps users design multi-agent AI teams — structuring roles, tools, handoffs, model assignments, and human gates — and exports a complete spec. It does not build or run agents itself; it produces the design that a human or engineering team implements.

**MCP server:** `https://mcp.openenvelope.org/api/mcp`  
**Schema:** `https://schema.openenvelope.org/team/v1.json`  
**Docs:** `https://openenvelope.org/docs/mcp`

---

## When to use this skill

Use Envelope when the user wants to:
- Design a multi-agent AI workflow from a plain-language description
- Add, remove, or modify agents in an existing design
- Browse their saved team designs
- Export a team definition as `.envelope.json` for implementation
- Install a design into their workspace
- Inspect or configure model assignments for installed agents

Do **not** use Envelope to:
- Execute arbitrary code or scripts
- Access services Envelope isn't connected to
- Replace the user's implementation platform (Envelope produces the design spec; the user's engineering team or runtime deploys it)

---

## Authentication

**Claude.ai / ChatGPT:** OAuth — the user signs in through the connector flow. No manual key needed.

**Claude Code / direct API:** Bearer token from the user's account settings page (`https://openenvelope.org/workspace/settings/api-keys`).

```
Authorization: Bearer $ENVELOPE_KEY
```

If the key is missing, ask the user to get one from their settings page. Never ask the user to paste a key into the conversation — ask them to set it as an environment variable or secret.

---

## Step 0 — Check identity before starting

Before doing anything else with a new API key, confirm who you are acting as:

```
GET /api/auth/key-identity
Authorization: Bearer $ENVELOPE_KEY
```

Response:
```json
{
  "userName": "Alice Chen",
  "orgName": "Acme Corp",
  "orgSlug": "acme-corp"
}
```

This confirms the key is valid and tells you which user and org you are operating under. If `userName` is null, the key is valid but not linked to a user — proceed with caution and confirm with the user.

---

## Core workflow

### 1. Discover before creating

Before generating or creating anything, check what the user already has:

```
GET /api/installs        # installed (runnable) teams
GET /api/templates       # saved draft and published teams
```

If the user's request matches an existing team, offer to modify it (`POST /api/templates/:id/apply`) rather than create a duplicate. Confirm with the user before overwriting or deleting anything.

### 2. Generate a design

Turn a plain-language description into a proposed team definition. **This does not save anything yet** — confirm with the user before calling Create Team.

```
POST /api/templates/generate
{
  "description": "A workflow that monitors GitHub issues, drafts reply suggestions, and sends them to Slack for approval before posting",
  "name": "GitHub Issue Responder"
}
```

Present the proposed design to the user in a readable summary (agent names, roles, tools required, any gates). Invite review before proceeding.

### 3. Save the design

After the user confirms:

```
POST /api/templates
{
  "name": "...",
  "description": "...",
  "definition": { ... }   // the full .envelope.json object
}
```

Returns a `templateId`. Tell the user the design is saved and show the workspace URL: `https://openenvelope.org/workspace`.

### 4. Install the team (if the user wants to run it)

```
POST /api/installs
{ "templateId": "tmpl_abc123" }
```

Two possible responses:

**Ready to run:**
```json
{ "installId": "inst_abc123", "status": "completed" }
```

**Credentials needed:**
```json
{
  "installId": "inst_abc123",
  "status": "pending_credentials",
  "setupUrl": "https://openenvelope.org/workspace/installs/inst_abc123"
}
```

If `status` is `pending_credentials`, send the user to `setupUrl`. **Never ask for or handle credentials yourself** — secrets must never pass through the conversation or the API.

## Modifying an existing design

Use natural-language instructions to modify an existing team without replacing the whole definition:

```
POST /api/templates/:id/apply
{ "instruction": "Add a summariser agent that writes a CRM note after each issue is resolved" }
```

> **Write action — confirmation required.** `POST /api/templates/:id/apply` modifies the saved team definition immediately. Always describe the proposed change to the user and get explicit confirmation before calling this endpoint. Do not call it speculatively or as a preview step — there is no dry-run mode.

---

## Model routing

Inspect current model assignments for an installed team:

```
GET /api/installs/:installId/agents
```

Pin a specific model to an agent:

```
PATCH /api/installs/:installId/agents/:agentKey/model
{ "model": "anthropic:claude-haiku-4-5" }
```

Available models: `openai:gpt-5.4`, `openai:gpt-5-mini`, `openai:gpt-5-nano`, `openai:o4-mini`, `openai:o3`, `anthropic:claude-opus-4-5`, `anthropic:claude-sonnet-4-5`, `anthropic:claude-haiku-4-5`

Reset to automatic routing:
```
DELETE /api/installs/:installId/agents/:agentKey/model
```

---

## Exporting a design

The exported `.envelope.json` file follows the open Envelope schema (`https://schema.openenvelope.org/team/v1.json`). To validate a definition before saving:

```
GET /api/schema    # returns the full JSON Schema for validation
```

When returning a design to the user, include:
- A readable summary of the agents and their roles
- The workspace URL for their saved design
- The exported JSON (or offer to export it)

---

## Error responses

All Envelope API errors return JSON with a consistent shape. Always check the status code and `error` field before retrying.

| Status | Meaning | What to do |
|---|---|---|
| `400` | Bad request — missing or invalid field | Check required fields; read `error` for the specific issue |
| `401` | Not authenticated | API key missing or expired — ask the user to check their key |
| `402` | Feature requires upgrade | The requested feature (e.g. audit log, REST API) requires a Pro or Team plan |
| `403` | Forbidden | The key doesn't have permission for this resource or org |
| `404` | Not found | The template, install, or run ID doesn't exist |
| `500` | Server error | Retry once after a short delay; if it persists, surface the error to the user |

Error response body:
```json
{
  "error": "Human-readable description of what went wrong",
  "upgrade": true    // present on 402 responses only
}
```

**On 402:** The feature is plan-gated. Do not retry. Tell the user which plan is required and link them to `https://openenvelope.org/pricing`.

**On 401:** Do not retry automatically. Ask the user to confirm their API key is set correctly at `https://openenvelope.org/workspace/settings/api-keys`.

---

## What to return to the user

After completing any design or modification task, always return:

1. **Summary** — what was created or changed, in plain language
2. **Workspace link** — `https://openenvelope.org/workspace`
3. **Export** — the `.envelope.json` definition, or offer to provide it
4. **Next steps** — if credentials are needed, the `setupUrl`; if the team is installed and ready, confirm with the user what they'd like to do next

---

## Rules

- **Check identity first.** On first use of a new key, call `GET /auth/key-identity` to confirm who you're acting as.
- **Discover first.** Always check existing designs before creating a new one.
- **Confirm before writing.** Show the proposed design or change and get explicit confirmation before calling Create Team, Update Team, Apply (modify), Install, Uninstall, or Publish. These endpoints write immediately — there is no dry-run or preview mode.
- **Never handle secrets.** If credentials are required, send the user to `setupUrl`. Do not ask for API keys, tokens, or passwords in the conversation.
- **Design vs. build.** Envelope produces a spec. The spec is what a human team implements on their chosen runtime (Paperclip, LangGraph, Relevance AI, etc.). Don't imply Envelope will run the agents for them.
- **Handle errors structurally.** Read the status code and `error` field. Don't retry 401 or 402 automatically — surface them to the user.

---

## Key URLs

| Resource | URL |
|---|---|
| MCP server | `https://mcp.openenvelope.org/api/mcp` |
| Schema | `https://schema.openenvelope.org/team/v1.json` |
| User workspace | `https://openenvelope.org/workspace` |
| MCP docs | `https://openenvelope.org/docs/mcp` |
| Schema reference | `https://openenvelope.org/docs/schema` |
| API keys | `https://openenvelope.org/workspace/settings/api-keys` |
| Pricing / plan features | `https://openenvelope.org/pricing` |
| Full content index | `https://openenvelope.org/llms-full.txt` |