awslabs · haofeif · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026
diff --git a/README.md b/README.md
@@ -540,6 +540,38 @@ Then ask your AI coding assistant to create a new provider:
 
 The assistant will follow the skill's step-by-step guide, reference the provider template, and apply lessons learnt from existing providers.
 
+### Managed Skills
+
+CAO also manages skills that are shared across all agent sessions. Builtin skills (`cao-supervisor-protocols`, `cao-worker-protocols`) are auto-seeded when the `cao-server` starts — no `cao init` required.
+
+```bash
+# List installed skills
+cao skills list
+
+# Install a custom skill from a local folder
+cao skills add ./my-coding-standards
+
+# Update an existing skill (overwrite)
+cao skills add ./my-coding-standards --force
+
+# Remove a skill
+cao skills remove my-coding-standards
+```
+
+Skills are delivered to each provider automatically:
+
+| Provider | Delivery Method |
+|----------|----------------|
+| Kiro CLI | Native `skill://` resources (progressive loading) |
+| Claude Code, Codex, Gemini CLI, Kimi CLI | Runtime prompt injection (every terminal creation) |
+| Copilot CLI | Baked into `.agent.md` at install time |
+
+When you add or remove a skill, all providers pick up the change automatically. Copilot agent files are refreshed immediately; other providers pick up changes on the next terminal creation.
+
+**Updating skills:** Use `cao skills add ./my-skill --force` to overwrite an existing skill. Without `--force`, the command errors if the skill already exists. Builtin skills are auto-seeded on server startup but are never overwritten — to update a builtin after a CAO upgrade, remove it first with `cao skills remove` then restart the server.
+
+For full details, see [docs/skills.md](docs/skills.md).
+
 ## Security
 
 The server is designed for **localhost-only use**. The WebSocket terminal endpoint (`/terminals/{id}/ws`) provides full PTY access and will reject connections from non-loopback addresses. Do not expose the server to untrusted networks without adding authentication.

diff --git a/docs/skills.md b/docs/skills.md
@@ -75,7 +75,7 @@ Validation checks (in order):
 5. No path traversal characters in the name (`/`, `\`, `..`)
 6. Skill does not already exist (unless `--force` is passed)
 
-After installation, all CAO-managed Q CLI and Copilot CLI agent files are automatically refreshed to include the new skill in their prompt catalog.
+After installation, all providers pick up the new skill automatically — Copilot CLI agent files are refreshed immediately, and other providers pick up changes on the next terminal creation.
 
 ### `cao skills remove <name>`
 
@@ -85,13 +85,13 @@ Removes an installed skill from the skill store.
 cao skills remove python-testing
 ```
 
-After removal, all CAO-managed Q CLI and Copilot CLI agent files are automatically refreshed to remove the skill from their prompt catalog.
+After removal, all providers pick up the change automatically — Copilot CLI agent files are refreshed immediately, and other providers pick up changes on the next terminal creation.
 
-### `cao init` (skill seeding)
+### Builtin skill seeding
 
-Running `cao init` seeds default skills into the skill store. If a skill with the same name already exists, it is skipped — preserving any edits you've made. Re-running `cao init` after a CAO upgrade will seed any new default skills without overwriting your changes.
+Builtin skills are auto-seeded when `cao-server` starts — no manual step required. If a skill with the same name already exists, it is skipped — preserving any edits you've made. After a CAO upgrade, restarting the server will seed any new builtin skills without overwriting your changes. You can also run `cao init` to seed them manually.
 
-CAO ships with two default skills:
+CAO ships with two builtin skills:
 
 | Skill | Description |
 |-------|-------------|
@@ -119,7 +119,6 @@ Skills are delivered to agents differently depending on the provider. The table
 | Gemini CLI | Runtime prompt | Every terminal creation | `load_skill` MCP tool |
 | Kimi CLI | Runtime prompt | Every terminal creation | `load_skill` MCP tool |
 | Kiro CLI | Native `skill://` resources | Every terminal creation | Kiro progressive loading |
-| Q CLI | Baked into agent JSON at install | On `cao skills add/remove` | `load_skill` MCP tool |
 | Copilot CLI | Baked into `.agent.md` at install | On `cao skills add/remove` | `load_skill` MCP tool |
 
 ### Runtime Prompt Providers (Claude Code, Codex, Gemini CLI, Kimi CLI)
@@ -142,14 +141,6 @@ Kiro loads only skill metadata (name and description) at startup, then retrieves
 
 Because Kiro reads directly from the skill store, changes from `cao skills add` or `cao skills remove` take effect the next time a terminal is created. No agent file refresh is needed.
 
-### Q CLI
-
-The skill catalog is baked into the agent's JSON file (`~/.q/agents/{name}.json`) at install time via `cao install`. The `prompt` field in the JSON contains the agent's prompt with the skill catalog appended.
-
-When you run `cao skills add` or `cao skills remove`, all CAO-managed Q agent files are automatically refreshed — their `prompt` field is rewritten with the updated skill catalog.
-
-CAO identifies Q agents it manages by checking whether the agent's `resources` field contains a `file://` URI pointing to the CAO agent context directory (`~/.aws/cli-agent-orchestrator/agent-context/`).
-
 ### Copilot CLI
 
 The skill catalog is baked into the agent's `.agent.md` file (`~/.copilot/agents/{name}.agent.md`) at install time. The Markdown body of the file contains the agent's prompt with the skill catalog appended. The YAML frontmatter (`name`, `description`) is preserved during refreshes.
@@ -189,7 +180,7 @@ description: Team coding standards for Python services including naming, error h
 cao skills add ./my-coding-standards
 ```
 
-Once installed, the skill is automatically available to all CAO agents. Runtime prompt providers (Claude Code, Codex, Gemini CLI, Kimi CLI) and Kiro will pick it up on the next terminal creation. Q CLI and Copilot CLI agent files are refreshed automatically by the `cao skills add` command.
+Once installed, the skill is automatically available to all CAO agents. Copilot CLI agent files are refreshed immediately by the `cao skills add` command. All other providers pick up changes on the next terminal creation.
 
 ## Updating a Skill
 
@@ -205,7 +196,7 @@ Or overwrite it with an updated version from a local folder:
 cao skills add ./my-coding-standards --force
 ```
 
-For runtime prompt providers (Claude Code, Codex, Gemini CLI, Kimi CLI) and Kiro, changes take effect on the next terminal creation. For Q CLI and Copilot CLI, running `cao skills add --force` automatically refreshes all installed agent files. If you edited the skill file directly instead, run `cao skills remove <name>` followed by `cao skills add <folder>` to trigger the refresh — or reinstall the affected agents with `cao install`.
+Running `cao skills add --force` refreshes Copilot CLI agent files immediately. All other providers pick up the change on the next terminal creation. If you edited the skill file directly in the store instead of using `cao skills add --force`, Copilot files won't be refreshed — run `cao skills remove <name>` followed by `cao skills add <folder>` to trigger the refresh, or reinstall the affected agents with `cao install`.
 
 ## Known Limitations
 

diff --git a/src/cli_agent_orchestrator/agent_store/developer.md b/src/cli_agent_orchestrator/agent_store/developer.md
@@ -32,6 +32,14 @@ You are the Developer Agent in a multi-agent system. Your primary responsibility
 3. **ALWAYS consider edge cases** and handle exceptions appropriately.
 4. **ALWAYS write unit tests** for your implementations when appropriate.
 
+## Multi-Agent Communication
+You receive tasks from a supervisor agent via CAO (CLI Agent Orchestrator). There are two modes:
+
+1. **Handoff (blocking)**: The message starts with `[CAO Handoff]` and includes the supervisor's terminal ID. The orchestrator automatically captures your output when you finish. Just complete the task, present your deliverables, and stop. Do NOT call `send_message` — the orchestrator handles the return.
+2. **Assign (non-blocking)**: The message includes a callback terminal ID (e.g., "send results back to terminal abc123"). When done, use the `send_message` MCP tool to send your results to that terminal ID.
+
+Your own terminal ID is available in the `CAO_TERMINAL_ID` environment variable.
+
 ## File System Management
 - Use absolute paths for all file references
 - Organize code files according to project conventions