Skip to content

docs(skills): schema refresh + brand-rights governance flow#716

Merged
bokelley merged 2 commits into
mainfrom
bokelley/skill-schema-refresh
Apr 21, 2026
Merged

docs(skills): schema refresh + brand-rights governance flow#716
bokelley merged 2 commits into
mainfrom
bokelley/skill-schema-refresh

Conversation

@bokelley

Copy link
Copy Markdown
Contributor

Summary

Follow-up to PR #709. The npm run compliance:skill-matrix dogfood run (14 skill × storyboard pairs) had 0/14 pass — but most failures stemmed from skill examples showing stale schemas that upstream redefined in the last several days (#691#708). This PR refreshes the skill examples and closes one real coverage gap in brand-rights.

Root-cause fixes

  1. list_creative_formats.renders[] (~6 pairs)
    Upstream redefined renders to require role plus oneOf { dimensions: object } or { parameters_from_format_id: true }. Skills showed renders: [{ width, height }] which fails validation. Updated seller, creative, generative-seller, retail-media examples and flagged the old shorthand explicitly.

  2. get_media_buys.media_buys[].currency + .total_budget (~4 pairs)
    Now required per row. Seller skill example shows both + a persistence note: save these on create_media_buy so subsequent reads can echo them.

  3. context response field shape (~4 pairs, signals/si/governance)
    Schema-typed as object. All 8 skills previously recommended context: args.context echo, which fabricates strings when args.context is undefined or when Claude conflates it with domain fields like campaign_context. New guidance: don't set context at all — createAdcpServer auto-injects the request's context object post-handler; hand-setting a non-object string fails validation and the framework does not overwrite.

  4. Brand-rights governance_denied flow (1 pair)
    Scenario expects check_governance call before acquire_rights. Added accounts.syncAccounts + accounts.syncGovernance handlers to the implementation example, plus a checkGovernance() call in acquireRights that returns GOVERNANCE_DENIED with findings propagated from the buyer's governance agent.

  5. Seller idempotency footnote (1 pair)
    Referenced Storyboard runner: raw-HTTP probe for idempotency missing-key vector (bypasses SDK auto-injection) #678 as a known grader-side MCP Accept-header issue so builders don't chase a skill fix for what's a grader bug.

Expected matrix delta

Baseline: 0/14 passed. Conservative estimate with these fixes: 10–12/14. Remaining failures likely need case-by-case diagnosis (e.g., pending_creatives → pending_start transition, creative state-machine quirks).

Test plan

  • All 8 skills compile clean in isolation (markdown only — no code)
  • Re-run npm run compliance:skill-matrix on this branch once merged
  • Validate remaining failures are new signatures, not regressions of what this PR fixed

🤖 Generated with Claude Code

bokelley and others added 2 commits April 21, 2026 10:52
Fix 10+ compliance:skill-matrix failures whose root causes were stale
skill examples:

list_creative_formats.renders[]: upstream now requires `role` plus
oneOf `dimensions` object | `parameters_from_format_id: true`. Updated
examples in seller, creative, generative-seller, retail-media.

get_media_buys.media_buys[]: `currency` + `total_budget` now required.
Seller skill shows both with a persistence note.

context response field: schema-typed as object. All 8 skills stopped
recommending `context: args.context` echo (which fabricates strings when
args.context is undefined or confused with domain fields like
`campaign_context`). Guidance now: leave the field out — createAdcpServer
auto-injects from the request.

Brand-rights governance_denied: added accounts.syncAccounts +
accounts.syncGovernance handlers plus a check_governance call in the
acquireRights example so the scenario returns GOVERNANCE_DENIED with
findings propagated.

Seller idempotency: referenced #678 as a
known grader-side MCP Accept-header issue so builders don't chase a
skill fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@bokelley bokelley force-pushed the bokelley/skill-schema-refresh branch from d347894 to 1ede03a Compare April 21, 2026 15:05
@bokelley bokelley merged commit c4ff3e6 into main Apr 21, 2026
14 checks passed
bokelley added a commit that referenced this pull request Apr 21, 2026
Conflict: src/lib/types/schemas.generated.ts — header timestamp only;
resolved by regenerating. Auto-merge combined overlapping fixes to
src/lib/server/test-controller.ts (main added `| SeedScenario` to the
exhaustiveness guard via #716; this branch narrowed `ControllerScenario`
to exclude `SeedScenario`). Both survive; functionally equivalent with
one redundant exclusion.
@github-actions github-actions Bot mentioned this pull request Apr 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant