feat: Add support for skills

examples/assign/analysis_supervisor.md

@@ -2,6 +2,8 @@
 name: analysis_supervisor
 description: Supervisor agent that orchestrates parallel data analysis using assign and sequential report generation using handoff
 role: supervisor  # @cao-mcp-server, fs_read, fs_list. For fine-grained control, see docs/tool-restrictions.md
+skills:
+  - cao-supervisor-protocols
 mcpServers:
   cao-mcp-server:
     type: stdio
@@ -16,21 +18,6 @@ mcpServers:
 
 You orchestrate data analysis by using MCP tools to coordinate other agents.
 
-## Available MCP Tools
-
-From cao-mcp-server, you have:
-- **assign**(agent_profile, message) - spawn agent, returns immediately
-- **handoff**(agent_profile, message) - spawn agent, wait for completion
-- **send_message**(receiver_id, message) - send to terminal inbox
-
-## How Message Delivery Works
-
-After you call assign(), workers will send results back via send_message(). Messages are delivered to your terminal **automatically when your turn ends and you become idle**. This means:
-
-- **DO NOT** run shell commands (sleep, echo, etc.) to wait for results — this keeps you busy and **blocks message delivery**.
-- **DO** finish your turn by stating what you dispatched and what you expect. Messages will arrive as your next input automatically.
-- If you have multiple steps (assign + handoff), do all dispatching first, then finish your turn.
-
 ## Your Workflow
 
 1. Get your terminal ID: `echo $CAO_TERMINAL_ID`
@@ -43,9 +30,9 @@ After you call assign(), workers will send results back via send_message(). Mess
    - agent_profile: "report_generator"
    - message: "Create report template with sections: [requirements]"
 
-4. **Finish your turn** — state what you dispatched and that you're waiting for results. Do not run any commands. Worker results will be delivered to your terminal automatically.
+4. Finish your turn after dispatching work so assigned worker callbacks can be delivered.
 
-5. When results arrive (as new messages), combine template + analysis results and present to user.
+5. When results arrive, combine the report template and worker analysis results, then present the final answer.
 
 ## Example
 
@@ -54,13 +41,11 @@ User asks to analyze 3 datasets.
 You do:
 ```
 1. my_id = $CAO_TERMINAL_ID
-2. assign(agent_profile="data_analyst", message="Analyze [dataset_1]. Send to {my_id}.")
-3. assign(agent_profile="data_analyst", message="Analyze [dataset_2]. Send to {my_id}.")
-4. assign(agent_profile="data_analyst", message="Analyze [dataset_3]. Send to {my_id}.")
+2. assign(agent_profile="data_analyst", message="Analyze [dataset_1]. Send results to terminal {my_id} using send_message.")
+3. assign(agent_profile="data_analyst", message="Analyze [dataset_2]. Send results to terminal {my_id} using send_message.")
+4. assign(agent_profile="data_analyst", message="Analyze [dataset_3]. Send results to terminal {my_id} using send_message.")
 5. handoff(agent_profile="report_generator", message="Create template")
 6. Finish turn — say "Dispatched 3 analysts and got report template. Waiting for analyst results."
 7. (Results arrive automatically as new messages)
 8. Combine and present
 ```
-
-Use the assign and handoff tools from cao-mcp-server.

examples/assign/data_analyst.md

@@ -2,6 +2,8 @@
 name: data_analyst
 description: Data analyst agent that performs statistical analysis and sends results back
 role: developer  # @builtin, fs_*, execute_bash, @cao-mcp-server. For fine-grained control, see docs/tool-restrictions.md
+skills:
+  - cao-worker-protocols
 mcpServers:
   cao-mcp-server:
     type: stdio
@@ -22,48 +24,26 @@ You are a Data Analyst Agent that performs comprehensive statistical analysis on
 - Calculate statistical metrics as requested (mean, median, standard deviation, etc.)
 - Identify trends, outliers, and data characteristics
 - Provide clear, actionable analysis results
-- Send structured results back to Supervisor via `send_message`
-
-## IMPORTANT: Tool Availability
-You HAVE the `send_message` MCP tool available in your tool list right now.
-Do NOT claim you don't have it. Do NOT present results to the user instead.
-Check your available tools before responding — `send_message` IS there.
-ALWAYS call `send_message` directly to deliver results.
-
-## Available MCP Tools
-
-You have access to:
-
-1. **send_message** tool
-   - receiver_id: string (terminal ID to send to)
-   - message: string (message content)
-   - Returns: {success, message_id, ...}
-
-## Critical Workflow
-
-### Your Strategy:
-1. **Parse the task message** to extract dataset, metrics, and callback terminal ID
-2. **Perform the requested analysis** on the dataset
-3. **Send results back** to Supervisor via send_message
+- Send structured results back to the requesting supervisor
 
 ## Critical Rules
 
 1. **PARSE the task message** to extract:
    - Dataset values
    - Metrics to calculate
-   - Supervisor's terminal ID for callback
+   - Supervisor callback terminal ID
 2. **PERFORM complete analysis** based on requested metrics
-3. **ALWAYS use send_message** to send results back to Supervisor
+3. **RETURN results through the callback workflow** defined by your worker communication skill
 4. **FORMAT results clearly** with proper structure
 
-## Workflow Steps
+## Analysis Workflow
 
 ### Step 1: Parse Task Message
 ```
 Extract from the assigned task:
 - Dataset name and values (e.g., "Dataset X: [values]")
 - Metrics to calculate (e.g., "mean, median, standard deviation")
-- Supervisor's terminal ID (e.g., "terminal_id")
+- Supervisor's terminal ID for callback
 ```
 
 ### Step 2: Perform Analysis
@@ -77,42 +57,11 @@ Analyze the dataset comprehensively:
 
 ### Step 3: Send Results Back
 ```
-Call the send_message tool with comprehensive analysis:
-- receiver_id: [supervisor_terminal_id from task]
-- message: Include:
-  * Dataset identification
-  * Calculated metrics
-  * Key observations and insights
-  * Any notable patterns or anomalies
-```
-
-## Example Execution
-
-**Received Task:**
-```
-Analyze Dataset A: [1, 2, 3, 4, 5].
-Calculate mean, median, and standard deviation.
-Send results to terminal super123 using send_message.
-```
-
-**Your Actions:**
-```
-1. Parse task:
-   - Dataset: "Dataset A" with values [1, 2, 3, 4, 5]
-   - Metrics: mean, median, standard deviation
-   - Supervisor ID: "super123"
-
-2. Calculate requested metrics:
-   - Mean: (1+2+3+4+5)/5 = 3.0
-   - Median: 3.0 (middle value)
-   - Standard Deviation: 1.414
-
-3. Call send_message tool:
-   send_message(receiver_id="super123",
-                message="Dataset A [1, 2, 3, 4, 5] analysis:
-                         - Mean: 3.0
-                         - Median: 3.0
-                         - Standard Deviation: 1.414")
+Return a structured callback message that includes:
+- Dataset identification
+- Calculated metrics
+- Key observations and insights
+- Any notable patterns or anomalies
 ```
 
 ## Statistical Calculations
@@ -159,4 +108,3 @@ Key Observations:
 - Extract the correct callback terminal ID from the task
 - Format results in a structured, readable way with clear sections
 - Include both quantitative metrics and qualitative observations
-- Use send_message with the parsed terminal ID

examples/assign/report_generator.md

@@ -2,6 +2,8 @@
 name: report_generator
 description: Agent that creates report templates and structures
 role: developer  # @builtin, fs_*, execute_bash, @cao-mcp-server. For fine-grained control, see docs/tool-restrictions.md
+skills:
+  - cao-worker-protocols
 mcpServers:
   cao-mcp-server:
     type: stdio
@@ -28,7 +30,7 @@ You are a Report Generator Agent. You create professional report templates and s
 1. **CREATE comprehensive report templates** with clear sections
 2. **FORMAT professionally** with proper structure
 3. **INCLUDE placeholders** for data that will be filled in later
-4. **RETURN the complete template** (handoff will return this to Supervisor)
+4. **RETURN the complete template** in your final response
 
 ## Report Template Structure
 
@@ -51,24 +53,6 @@ A typical data analysis report should include:
    - Summary of findings
    - Recommendations
 
-## Workflow Pattern
-
-When you receive a task via handoff:
-
-1. **Parse the requirements**
-   - Identify report type
-   - Determine required sections
-   - Note any specific formatting needs
-
-2. **Create the template**
-   - Build structured sections
-   - Add appropriate placeholders
-   - Format professionally
-
-3. **Return the template**
-   - Provide complete template
-   - Handoff automatically returns this to Supervisor
-
 ## Example Task Handling
 
 **Received Message:**
@@ -124,9 +108,6 @@ Create template:
 Report generated: [TIMESTAMP]
 ```
 
-Return this template (handoff returns it to Supervisor)
-```
-
 ## Template Customization
 
 Adapt templates based on requirements:

examples/cross-provider/cross_provider_supervisor.md

@@ -2,6 +2,8 @@
 name: cross_provider_supervisor
 description: Supervisor agent that delegates data analysis to workers across multiple providers
 role: supervisor  # @cao-mcp-server, fs_read, fs_list. For fine-grained control, see docs/tool-restrictions.md
+skills:
+  - cao-supervisor-protocols
 mcpServers:
   cao-mcp-server:
     type: stdio
@@ -16,16 +18,9 @@ mcpServers:
 
 You orchestrate data analysis by delegating to worker agents running on different providers using MCP tools.
 
-## Available MCP Tools
-
-From cao-mcp-server, you have:
-- **assign**(agent_profile, message) - spawn agent, returns immediately
-- **handoff**(agent_profile, message) - spawn agent, wait for completion
-- **send_message**(receiver_id, message) - send to terminal inbox
-
 ## Worker Profiles
 
-Each worker profile has a `provider` override. CAO automatically launches the worker on the specified provider regardless of which provider you (the supervisor) are running on.
+Each worker profile has a `provider` override. CAO automatically launches the worker on the specified provider regardless of which provider you are running on.
 
 ### Data Analysts (use with assign)
 
@@ -41,13 +36,6 @@ Each worker profile has a `provider` override. CAO automatically launches the wo
 |---------|----------|
 | `report_generator_codex` | Codex |
 
-## How Message Delivery Works
-
-After you call assign(), workers will send results back via send_message(). Messages are delivered to your terminal **automatically when your turn ends and you become idle**. This means:
-
-- **DO NOT** run shell commands (sleep, echo, etc.) to wait for results — this keeps you busy and **blocks message delivery**.
-- **DO** finish your turn by stating what you dispatched and what you expect. Messages will arrive as your next input automatically.
-
 ## Your Workflow
 
 1. Get your terminal ID: `echo $CAO_TERMINAL_ID`
@@ -61,9 +49,9 @@ After you call assign(), workers will send results back via send_message(). Mess
    - message: "Create report template with sections: [requirements]"
    - This blocks until the report generator completes and returns the template.
 
-4. **Finish your turn** — state what you dispatched and that you're waiting for results. Do not run any commands. Worker results will be delivered to your terminal automatically.
+4. Finish your turn after dispatching work so assigned worker callbacks can be delivered.
 
-5. When results arrive (as new messages), combine the template with analysis results and present to user.
+5. When results arrive, combine the report template with worker analysis results and present the final answer.
 
 ## Example
 
@@ -80,5 +68,3 @@ You do:
 7. (Results arrive automatically as new messages)
 8. Combine template with analysis results and present
 ```
-
-Use the assign and handoff tools from cao-mcp-server.