feat: add call_adcp_agent tool and Claude Skills for full AdCP access

.changeset/fiery-maps-tan.md

@@ -0,0 +1,12 @@
+---
+---
+
+Add call_adcp_agent tool and Claude Skills for full AdCP protocol access.
+
+This enables clients to execute the full AdCP spec (not just testing API) via:
+- `call_adcp_agent` tool: Low-level proxy to any AdCP-compliant sales agent
+- Claude Skills: Protocol knowledge for media-buy, signals, and creative
+
+Skills teach Claude the protocol schemas and workflows; the tool routes to
+whatever agent the user specifies. Auth tokens are looked up from saved
+agent context or can be provided directly.

.gitignore

@@ -40,6 +40,9 @@ coverage/
 # Addie external repo cache
 .addie-repos/
 
+# Generated skill schemas (built from dist/schemas)
+skills/*/schemas/
+
 # Stripe webhook secret (dynamically generated)
 .stripe-webhook-secret
 test-results/

docs.json

@@ -204,6 +204,9 @@
           {
             "group": "Reference",
             "pages": [
+              "docs/reference/media-buy-quick-reference",
+              "docs/reference/signals-quick-reference",
+              "docs/reference/creative-quick-reference",
               "docs/reference/roadmap",
               "docs/reference/release-notes",
               "docs/reference/changelog",

docs/reference/creative-quick-reference.mdx

@@ -0,0 +1,285 @@
+---
+title: Creative Quick Reference
+description: Compact reference for executing AdCP Creative Protocol tasks. Use this when interacting with creative agents via call_adcp_agent.
+keywords: [adcp tasks, creative api, creative agent, build_creative, preview_creative, quick reference]
+---
+
+Use the `call_adcp_agent` tool to execute these tasks against any AdCP creative agent.
+
+## Task Overview
+
+| Task | Purpose | Response Time |
+|------|---------|---------------|
+| `list_creative_formats` | View format specifications | ~1s |
+| `build_creative` | Generate or transform creatives | ~30s-5m |
+| `preview_creative` | Get visual previews | ~5s |
+
+## Typical Workflow
+
+1. **Discover formats**: `list_creative_formats` to see available format specs
+2. **Build creative**: `build_creative` to generate or transform a manifest
+3. **Preview**: `preview_creative` to see how it renders
+4. **Sync**: Use `sync_creatives` (media-buy task) to traffic the creative
+
+---
+
+## Task Reference
+
+### list_creative_formats
+
+Discover creative formats and their specifications.
+
+```json
+{
+  "type": "video",
+  "asset_types": ["image", "text"]
+}
+```
+
+**Key fields:**
+- `format_ids` (array, optional): Request specific format IDs
+- `type` (string, optional): Filter by type: `video`, `display`, `audio`, `dooh`
+- `asset_types` (array, optional): Filter by accepted asset types
+- `max_width`, `max_height` (integer, optional): Dimension constraints
+- `is_responsive` (boolean, optional): Filter for responsive formats
+- `name_search` (string, optional): Search formats by name
+
+**Response contains:**
+- `formats`: Array of format definitions with `format_id`, `name`, `type`, `assets_required`, `renders`
+- `creative_agents`: Optional array of other creative agents providing additional formats
+
+---
+
+### build_creative
+
+Generate a creative from scratch or transform an existing creative to a different format.
+
+**Pure Generation (from brief):**
+```json
+{
+  "message": "Create a banner promoting our winter sale with a warm, inviting feel",
+  "target_format_id": {
+    "agent_url": "https://creative.adcontextprotocol.org",
+    "id": "display_300x250_generative"
+  },
+  "creative_manifest": {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org",
+      "id": "display_300x250_generative"
+    },
+    "assets": {
+      "promoted_offerings": {
+        "brand_manifest": {
+          "url": "https://mybrand.com",
+          "name": "My Brand",
+          "colors": { "primary": "#FF5733" }
+        },
+        "inline_offerings": [
+          {
+            "name": "Winter Sale Collection",
+            "description": "50% off all winter items"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+**Transformation (resize/reformat):**
+```json
+{
+  "message": "Adapt this leaderboard to a 300x250 banner",
+  "creative_manifest": {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org",
+      "id": "display_728x90"
+    },
+    "assets": {
+      "banner_image": {
+        "asset_type": "image",
+        "url": "https://cdn.mybrand.com/leaderboard.png",
+        "width": 728,
+        "height": 90
+      },
+      "headline": {
+        "asset_type": "text",
+        "content": "Spring Sale - 30% Off"
+      }
+    }
+  },
+  "target_format_id": {
+    "agent_url": "https://creative.adcontextprotocol.org",
+    "id": "display_300x250"
+  }
+}
+```
+
+**Key fields:**
+- `message` (string, optional): Natural language instructions for generation/transformation
+- `creative_manifest` (object, optional): Source manifest - minimal for generation, complete for transformation
+- `target_format_id` (object, required): Format to generate - `{ agent_url, id }`
+
+**Response contains:**
+- `creative_manifest`: Complete manifest ready for `preview_creative` or `sync_creatives`
+
+---
+
+### preview_creative
+
+Generate visual previews of creative manifests.
+
+**Single preview:**
+```json
+{
+  "request_type": "single",
+  "format_id": {
+    "agent_url": "https://creative.adcontextprotocol.org",
+    "id": "display_300x250"
+  },
+  "creative_manifest": {
+    "format_id": {
+      "agent_url": "https://creative.adcontextprotocol.org",
+      "id": "display_300x250"
+    },
+    "assets": {
+      "banner_image": {
+        "asset_type": "image",
+        "url": "https://cdn.example.com/banner.png",
+        "width": 300,
+        "height": 250
+      }
+    }
+  }
+}
+```
+
+**With device variants:**
+```json
+{
+  "request_type": "single",
+  "format_id": { "agent_url": "...", "id": "native_responsive" },
+  "creative_manifest": { },
+  "inputs": [
+    { "name": "Desktop", "macros": { "DEVICE_TYPE": "desktop" } },
+    { "name": "Mobile", "macros": { "DEVICE_TYPE": "mobile" } }
+  ]
+}
+```
+
+**Batch preview (5-10x faster):**
+```json
+{
+  "request_type": "batch",
+  "requests": [
+    { "format_id": {}, "creative_manifest": { } },
+    { "format_id": {}, "creative_manifest": { } }
+  ]
+}
+```
+
+**Key fields:**
+- `request_type` (string, required): `"single"` or `"batch"`
+- `format_id` (object, required for single): Format identifier
+- `creative_manifest` (object, required): Complete creative manifest
+- `inputs` (array, optional): Generate variants with different macros/contexts
+- `output_format` (string, optional): `"url"` (default) or `"html"`
+
+**Response contains:**
+- `previews`: Array of preview objects with `preview_url` or `preview_html`
+- `expires_at`: When preview URLs expire
+
+---
+
+## Key Concepts
+
+### Format IDs
+
+All format references use structured objects:
+```json
+{
+  "format_id": {
+    "agent_url": "https://creative.adcontextprotocol.org",
+    "id": "display_300x250"
+  }
+}
+```
+
+The `agent_url` specifies the creative agent authoritative for this format.
+
+### Creative Manifests
+
+Manifests pair format specifications with actual assets:
+```json
+{
+  "format_id": {
+    "agent_url": "https://creative.adcontextprotocol.org",
+    "id": "display_300x250"
+  },
+  "assets": {
+    "banner_image": {
+      "asset_type": "image",
+      "url": "https://cdn.example.com/banner.png",
+      "width": 300,
+      "height": 250
+    },
+    "headline": {
+      "asset_type": "text",
+      "content": "Shop Now"
+    },
+    "clickthrough_url": {
+      "asset_type": "url",
+      "url": "https://brand.com/sale"
+    }
+  }
+}
+```
+
+### Asset Types
+
+Common asset types:
+- `image`: Static images (JPEG, PNG, WebP)
+- `video`: Video files (MP4, WebM) or VAST tags
+- `audio`: Audio files (MP3, M4A) or DAAST tags
+- `text`: Headlines, descriptions, CTAs
+- `html`: HTML5 creatives or third-party tags
+- `javascript`: JavaScript tags
+- `url`: Tracking pixels, clickthrough URLs
+
+### Brand Manifest
+
+For generative creatives, provide brand context:
+```json
+{
+  "brand_manifest": {
+    "url": "https://brand.com",
+    "name": "Brand Name",
+    "colors": { "primary": "#FF0000", "secondary": "#0000FF" }
+  }
+}
+```
+
+### Generative vs Transformation
+
+- **Pure Generation**: Minimal manifest with `promoted_offerings` in assets. Creative agent generates all output assets from scratch.
+- **Transformation**: Complete manifest with existing assets. Creative agent adapts to target format, following `message` guidance.
+
+---
+
+## Error Handling
+
+Common error patterns:
+
+- **400 Bad Request**: Invalid manifest or format_id
+- **404 Not Found**: Format not supported by this agent
+- **422 Validation Error**: Manifest doesn't match format requirements
+
+Error responses include:
+```json
+{
+  "error": {
+    "code": "INVALID_FORMAT_ID",
+    "message": "format_id must be a structured object with 'agent_url' and 'id' fields"
+  }
+}
+```