Sync canonical agent skills from the protocol tarball

[bokelley]

Context

adcontextprotocol/adcp#3097 (merged) bundles agent-facing skills (skills/call-adcp-agent/SKILL.md plus per-protocol task skills) into the published protocol tarball at /protocol/<version>.tgz alongside schemas and compliance. Companion PR adcontextprotocol/adcp-client#965 wires the JS SDK to extract them on sync.

This issue tracks the equivalent for the Python SDK.

What's in the tarball

The tarball's manifest.json now enumerates protocol-managed skills:

{
  "contents": {
    "schemas": true,
    "compliance": true,
    "skills": ["adcp-brand", "adcp-creative", "adcp-governance", "adcp-media-buy", "adcp-si", "adcp-signals", "call-adcp-agent"],
    ...
  }
}

The seven directories live at adcp-{version}/skills/<name>/, each containing a SKILL.md (the agent-facing wire contract). Per-protocol skills also bundle a schemas/ subdir which should be filtered out — the SDK already has those in schemas/cache/<version>/.

Proposal

Extend the Python SDK's schema-sync path (or add a new sync_skills step) to:

1. After extracting the tarball, read manifest.json.
2. For each name in manifest.contents.skills (when present and an array), copy <extract>/skills/<name>/ into the SDK's local skills/<name>/, excluding nested schemas/ subdirs.
3. Snapshot the previous tree as <dst>.previous (matches the pattern used for schemas/compliance).
4. Manifest-driven means SDK-local skills (anything not enumerated) stay untouched — preserves any Python-SDK-specific skill packaging.

Reference implementation

JS sync: scripts/sync-schemas.ts in adcontextprotocol/adcp-client#965. The function syncSkillsFromBundle is ~30 lines; copySkillTree + copyTreeFiltered add another ~30. Translate to Python idiomatically.

Why now

Without this sync, the buyer-side call-adcp-agent skill (the canonical wire contract: idempotency replay, account oneOf variants, async submitted polling, error recovery via adcp_error.issues[]) doesn't reach Python SDK consumers. Coding agents (Claude Code, Cursor, Cline) using the Python SDK package would see no skill content at all — they'd fall back to training-data hallucinations of AdCP shapes, which we've already observed (anonymous Addie tier hallucinated account_name+account_email for the oneOf instead of the correct {account_id} OR {brand:{domain}, operator}).

Out of scope

• Adding new skills (those are tracked as separate issues in adcp-client and the spec repo)
• Changing the manifest format (already settled upstream)

Co-tracked: adcontextprotocol/adcp-go (same ask, different SDK).

[bokelley]

Triage

Classification: Feature request
Bucket(s): client (no client label exists in this repo — flagged in run summary)
Status: drafting-pr

What the experts said:

• code-reviewer: approved with fixes — 6 blockers: path-traversal guard on skill names, str validation per name, top-level import json, TemporaryDirectory[str] annotation, resource-leak fix in extract_bundle, tests required for new function
• dx-expert: approved with fixes — 4 blockers: update docstring/Makefile help text for expanded scope, add skills/*.previous to .gitignore, print feedback for skills sync, add --no-skills flag (critical for check-schema-drift target which diffs skills/)

My take: Non-breaking additive change with a clear reference implementation; all blockers are concrete and fixable. Drafting now — check-schema-drift Makefile target needs --no-skills so it doesn't fail on skill drift when only checking schemas.

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code