From 01385816b159f1af0c5014251848a55da50dbe12 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 25 Apr 2026 12:42:57 +0000 Subject: [PATCH] docs(skill): replace dist/schemas/ paths with SDK-agnostic probe list in call-adcp-agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four `dist/schemas//bundled/...` path references in skills/call-adcp-agent/SKILL.md pointed at the spec-repo source layout, which never exists in an SDK consumer's environment. Coding agents loading this skill — its only intended audience — hit a missing directory on every schema lookup, reverting the hop-count regression that motivated #3097. Replace with an ordered probe: (1) local SDK cache (path varies; e.g. @adcp/client at schemas/cache//bundled/), (2) local spec-repo build at dist/schemas//bundled/, (3) HTTP canonical fallback at https://adcontextprotocol.org/schemas/v3/bundled/ (always available). Add underscore→hyphen translation note: tool names use underscores (`create_media_buy`) but filenames use hyphens (`create-media-buy-request.json`). Remove false claim that `npm run sync-schemas` exists across all SDKs. Closes #3117 Session: https://claude.ai/code/session_014qvcxcqN1F9Gbh5V9Dw7Pu --- .changeset/fix-call-adcp-agent-schema-paths.md | 4 ++++ skills/call-adcp-agent/SKILL.md | 13 +++++++++---- 2 files changed, 13 insertions(+), 4 deletions(-) create mode 100644 .changeset/fix-call-adcp-agent-schema-paths.md diff --git a/.changeset/fix-call-adcp-agent-schema-paths.md b/.changeset/fix-call-adcp-agent-schema-paths.md new file mode 100644 index 0000000000..80af18cf3d --- /dev/null +++ b/.changeset/fix-call-adcp-agent-schema-paths.md @@ -0,0 +1,4 @@ +--- +--- + +Fix `skills/call-adcp-agent/SKILL.md` bundled-schema path references: replace hardcoded `dist/schemas/` paths (spec-repo source layout, wrong for all SDK consumers) with an ordered probe list (local SDK install → local spec-repo build → HTTP canonical URL at `https://adcontextprotocol.org/schemas/v3/bundled/`). Add underscore→hyphen translation note for tool names in filenames. Removes false claim that `npm run sync-schemas` exists across all SDKs. diff --git a/skills/call-adcp-agent/SKILL.md b/skills/call-adcp-agent/SKILL.md index f77c13f9ae..18a0e438c3 100644 --- a/skills/call-adcp-agent/SKILL.md +++ b/skills/call-adcp-agent/SKILL.md @@ -9,7 +9,7 @@ type: cross-cutting ## Overview -AdCP (Ad Context Protocol) agents expose a fixed tool surface (`get_products`, `create_media_buy`, `get_signals`, …) over MCP or A2A. Tool names come from `get_adcp_capabilities`; exact request/response shapes live in the spec's bundled JSON Schemas at `dist/schemas//bundled//-{request,response}.json` (or via `get_schema` when the agent exposes it). This skill teaches the invariants that don't live cleanly in any schema: cross-tool patterns, async flow, error recovery. +AdCP (Ad Context Protocol) agents expose a fixed tool surface (`get_products`, `create_media_buy`, `get_signals`, …) over MCP or A2A. Tool names come from `get_adcp_capabilities`; exact request/response shapes are available via `get_schema` when the agent exposes it, or from the spec's bundled JSON Schemas at `https://adcontextprotocol.org/schemas/v3/bundled//-{request,response}.json`. This skill teaches the invariants that don't live cleanly in any schema: cross-tool patterns, async flow, error recovery. ## When to Use @@ -25,7 +25,12 @@ Walk these in order on first contact: 1. **Agent card** (A2A) or **`tools/list`** (MCP): returns tool NAMES. AdCP MCP servers no longer publish per-tool parameter schemas in `tools/list` — everything shows `{type: 'object', properties: {}}`. Don't try to infer shape from here. 2. **`get_adcp_capabilities`**: returns supported protocols (`media_buy`, `signals`, `creative`, …), AdCP major versions, feature flags. Tells you WHICH tools this agent supports, not how to call them. 3. **`get_schema(tool_name)`** *(when the agent exposes it — pending standardization in [#3057](https://github.com/adcontextprotocol/adcp/issues/3057), not yet universal)*: returns the JSON Schema for a tool's request/response. Preferred over reading bundled schemas when available. -4. **Bundled schemas** (offline, authoritative): `dist/schemas//bundled//-request.json` and `-response.json`. The adcp main repo publishes these; SDKs sync them (`npm run sync-schemas` in `@adcp/client`, equivalents in other SDKs). Substitute your target AdCP major version in the path. +4. **Bundled schemas** (authoritative, no agent required): probe in order until one resolves — + 1. Local SDK cache — path varies by SDK (e.g., `@adcp/client` caches at `schemas/cache//bundled//-request.json`; check your SDK's README if this path doesn't exist) + 2. Local spec-repo build: `dist/schemas//bundled//-request.json` + 3. HTTP (always available): `https://adcontextprotocol.org/schemas/v3/bundled//-request.json` — use the major alias matching `adcp_version` (`"3.x"` → `v3`) + + Tool names use hyphens in filenames, not underscores: `create-media-buy-request.json` for `create_media_buy`. For local probes, `` is a full version string (e.g., `3.0.0`). ## Non-obvious rules every buyer must follow @@ -244,7 +249,7 @@ Priority order: 1. Re-read the failure's `issues[]`. The pointer list plus this skill covers 80% of cases. 2. Call `get_schema(tool_name)` if the agent exposes it (see [#3057](https://github.com/adcontextprotocol/adcp/issues/3057) for the pending standard). -3. Read the bundled JSON Schema at `dist/schemas//bundled//-request.json`. +3. Fetch the bundled JSON Schema — probe in order (see Discovery chain step 4 for full probe sequence): local SDK cache, `dist/schemas//bundled//-request.json` (spec-repo build), or `https://adcontextprotocol.org/schemas/v3/bundled//-request.json` (HTTP, always available). Tool names use hyphens in filenames (`create-media-buy-request.json` for `create_media_buy`). 4. Consult the per-protocol skill in this repo (`skills/adcp-media-buy/`, `skills/adcp-creative/`, …) for specialism-specific patterns. ## Related @@ -252,4 +257,4 @@ Priority order: - [Calling an agent (docs)](https://adcontextprotocol.org/docs/protocol/calling-an-agent) — human-readable narrative form of this skill - `skills/adcp-media-buy/`, `skills/adcp-creative/`, `skills/adcp-signals/`, `skills/adcp-governance/`, `skills/adcp-si/`, `skills/adcp-brand/` — per-protocol task skills (layered on top of this one) - `@adcp/client/skills/build-seller-agent/SKILL.md` — building agents on the other side of the call -- `dist/schemas//bundled/` — canonical JSON Schemas (every tool, pinned to the AdCP version) +- [Bundled JSON Schemas](https://adcontextprotocol.org/schemas/v3/bundled/) — fully dereferenced schemas for every tool, pinned to the AdCP version