RFC: competence advertisement for AdCP agents — declare what an agent can do within its capabilities

[lukasz-pubx]

Summary

get_adcp_capabilities tells a counterparty what an agent's deployment supports — feature
flags and compliance claims. Nothing on the wire tells a counterparty what the agent can
do in a conversation: whether the free-text asks the protocol already carries (refine
asks, briefs) will land on an agent that can reason about them. This proposes an optional,
non-breaking competence advertisement — a get_adcp_competences task returning name +
description pairs (e.g. price-negotiation, signal-selection) — so buyers can match
conversational asks to declared competence instead of discovering incapability by wasted
round-trips. The layering is the point: a capability says the agent processes refinement
requests; a competence says what the agent can do inside them — negotiate price, reason
about what "similar" means. Competences sit on top of capabilities; they never substitute
for them.

Current state (as of 298d99c85, docs build 3.1.2)

• Capabilities are feature flags. get_adcp_capabilities returns deployment facts —
  e.g. media_buy.features.inline_creative_management: true — which gate which requests are
  accepted, not which conversations are understood.
• Specialisms are compliance claims, not competence hints.
  protocol/get-adcp-capabilities-response.json defines specialisms as "specialized
  compliance claims this agent supports. Values MUST be kebab-case enum IDs" — a closed enum
  (enums/specialism.json) wired to the AAO compliance runner's storyboard bundles. It
  verifies protocol conformance per domain; it says nothing about conversational depth
  within a domain.
• The refinement surface already invites conversation it cannot scope.
  media-buy/get-products-request.json defines refine[] entries with
  action: ["include", "omit", "more_like_this"] plus free-text ask fields at entry and
  request level. The docs say the quiet part:

  "But for campaigns involving multiple products, proposals with budget allocations, or
  iterative negotiation, refinement is where the value is."
  (docs/media-buy/product-discovery/refinement.mdx)
  Nothing tells the buyer whether the seller can actually negotiate — the ask is free text,
  and any handling of it is conformant.

• Runtime discovery was considered and deferred — for schemas. Known limitations records:
  "A runtime tool was considered in Spec: standardize a get_schema capability tool for transport-symmetric schema discovery #3057 and deferred — the SKILL.md path covers coding-agent
  discoverability, the schema-bundle URLs cover SDK builders." That reasoning holds for
  schemas because every conformant agent has the same shapes, so out-of-band distribution
  works. Conversational competence is per-agent: no spec-packaged file can say whether
  this seller negotiates. The out-of-band escape hatch that justified deferring Spec: standardize a get_schema capability tool for transport-symmetric schema discovery #3057 does
  not exist for this problem.

Problem

A buyer in buying_mode: "refine" sends a request-level ask: "this plan, but at $12 CPM
rather than $15 — willing to drop the CTV package for it." Two conformant sellers:

• Seller A reasons about margins and data costs and returns a counter-proposal.
• Seller B is a mechanical refiner: it matches no product_id change request, treats the ask
  as unactionable free text, and returns the same products at $15.

Both are conformant — ask is advisory free text. The buyer cannot distinguish "no" from
"didn't understand": it may burn further refinement rounds negotiating with an agent that
cannot negotiate ("blind luck"), or worse, an orchestrator treats the returned $15 plan as
seller A-style considered output and proceeds toward create_media_buy on terms the ask was
specifically trying to move. The same failure shape applies to more_like_this (an agent
that cannot reason about what "similar" means, versus one that can ask "similar in cost, or
a lookalike audience?") and to signal selection conversations.

The general form: the protocol's free-text surfaces assume a sophistication the protocol
gives agents no way to declare. Smart agents can figure things out; less sophisticated
agents need explicit, strict requests — and the buyer can't tell which it is facing until
after the tokens (and rounds, and sometimes commitments) are spent.

Proposed change

Optional, additive, advisory. Three parts:

1. New optional task get_adcp_competences (schema pair under
   static/schemas/source/protocol/). Request: empty object, optionally
   { "domain": "media_buy" } to filter. Response:

   {
     "competences": [
       {
         "name": "price-negotiation",
         "description": "Can negotiate price and terms on refine asks: reasons about margins, data costs, and package trade-offs, and returns counter-proposals."
       },
       {
         "name": "signal-selection",
         "description": "Can discuss signal and signal-provider choices and recommend alternatives against a brief."
       }
     ]
   }

   name: free-form kebab-case (open vocabulary — deliberately not an enum; see
   Alternatives). description: what the counterparty can expect the agent to understand and
   do, in one to three sentences. The shape is directly inspired by what agent-skill
   ecosystems expose as frontmatter (name + description, per the agentskills.io
   specification) — enough for a counterparty LLM to route on, without exposing
   implementation. The wire vocabulary is deliberately competence, not "skill": this repo
   already ships skills/ — coding-agent skills bundled with the protocol tarball
   (feat(skills): hoist call-adcp-agent + bundle skills/ into protocol tarball #3097/release: re-cut 3.0.0 tarball with skills/ + manifest.contents.skills #3116, and the SKILL.md path in known limitations) — and overloading the noun would
   invite exactly the confusion this task exists to remove.

2. Discovery pointer in get_adcp_capabilities: one optional boolean (e.g.
   adcp.competence_discovery: true) advertising that the task is available. Two calls
   rather than inlining, deliberately: it keeps the capabilities response lean for the
   majority of callers that never need competences, and progressive disclosure matches the
   protocol's existing discovery chain (capabilities first, detail tools on demand).

3. Explicit non-goals, stated normatively in the doc page:

   • Declaring a competence is advisory, not a compliance claim — no storyboard
     verification, no conformance semantics; absence of a competence means undeclared, not
     incapable.
   • No competence-body exposure on the wire: names and descriptions only. Whether an agent's
     internal implementation is an Anthropic-style SKILL.md (the inspiration for this
     mechanism), a fine-tune, or hardcoded logic is the implementor's business.
   • No new request semantics: a declared competence grants no new fields and changes no
     handling rules; asks remain asks. The declaration only informs the counterparty's choice
     of what to attempt.

Normativity/optionality per addition: get_adcp_competences — optional task, response
shape normative when implemented; competence_discovery flag — optional; competence
semantics — advisory.

Rationale and evidence

• The refinement docs themselves market "iterative negotiation" as where refinement's value
  is, while the schema leaves ask-handling entirely to unadvertised agent sophistication —
  the gap is in the protocol's own framing, not a hypothetical.
• Precedent for extending the capabilities surface is active in this repo: RFC: capability-change notifications for get_adcp_capabilities #5794 (RFC:
  capability-change notifications for get_adcp_capabilities) and RFC: Measurement capability declaration (tracking_capabilities, attribution methodologies, TMP exposure data) #6207 (RFC: measurement
  capability declaration). This proposal is the same movement — from "what requests are
  accepted" toward "what the counterparty can expect" — applied to conversational surfaces.
• docs: knowledge gap (critical) — Distinguishing Refinement from Negotiation Skills #6101 (open, docs) already proposes documenting that "agents should explicitly advertise
  distinct capabilities via SKILL metadata to help requesters understand which negotiations
  will be understood" — a docs patch with no mechanism behind it. This proposal is that
  mechanism (adopting "competence" as the wire vocabulary precisely to stay distinct from the
  repo's coding-agent skills).

Alternatives considered

• Extend specialisms. Rejected: specialisms are closed-enum compliance claims with
  runner semantics (an agent omitting one is skipped by compliance tracks). Overloading them
  with open-vocabulary advisory hints would weaken both meanings. The three surfaces layer
  cleanly: capability = "I accept these requests"; specialism = verified "I conform to X";
  competence = advisory "I can converse about Y".
• Inline competences[] in the capabilities response. Workable, and acceptable if maintainers
  prefer one surface — the cost is response bloat on every capabilities call for data most
  callers need rarely; the two-call shape preserves progressive disclosure.
• Per-proposal negotiability declaration (proposal.negotiable, from reviewer feedback). An optional
  typed field on core/proposal.json declaring which dimensions of a specific offer are open
  (e.g. "negotiable": ["pricing", "allocation"]). Strictly better than a competence claim on
  proposal surfaces: it anchors to the object being negotiated, is per-deal rather than
  per-agent (no drift, no RFC: capability-change notifications for get_adcp_capabilities #5794 staleness question), and proposal_status gives it a substrate
  for default semantics (committed + absent negotiable = firm) that no agent-level mechanism
  can offer. Not adopted as a substitute because it cannot cover pre-proposal surfaces —
  seller selection, brief mode, request-level asks, more_like_this, signal-selection — where
  the "no vs. didn't understand" failure begins and no proposal object exists. Proposed instead
  as a companion addition: proposal-level negotiable is authoritative for in-deal
  negotiation; competences cover pre-engagement routing. See discussion in the issue thread.
• A standardized competence taxonomy (enum) from day one. Premature: the useful vocabulary is
  unknown until agents advertise in the open. Open vocabulary now; if names converge,
  standardization can follow the same path specialisms took (free practice → enum + bundles).
• Do nothing. The cost is the failure narrative above, recurring: wasted refinement
  rounds, misread non-responses, and orchestrators proceeding on terms an ask tried to move.

Compatibility and migration

Purely additive: a new optional task plus one optional boolean. Agents that implement
neither behave exactly as today; callers that don't check the flag lose nothing. No changes
to any existing schema's required fields; no version-boundary framing needed (3.x-compatible).

Files affected (as of 298d99c85 — re-verify at implementation time)

• static/schemas/source/protocol/get-adcp-competences-request.json (new)
• static/schemas/source/protocol/get-adcp-competences-response.json (new)
• static/schemas/source/protocol/get-adcp-capabilities-response.json (optional
  competence_discovery flag)
• A docs page (plausibly the docs/building/implementation/agent-capabilities.mdx that
  docs: knowledge gap (critical) — Distinguishing Refinement from Negotiation Skills #6101 proposes, giving its patch the mechanism it currently lacks)
• No enum changes; no changes to refinement or any existing task schemas

Open questions

1. Terminology: "competence" is chosen deliberately — this repo already ships skills/
   (coding-agent skills bundled with the protocol tarball, feat(skills): hoist call-adcp-agent + bundle skills/ into protocol tarball #3097/release: re-cut 3.0.0 tarball with skills/ + manifest.contents.skills #3116, and the SKILL.md path
   in known limitations), so reusing "skill" on the wire would overload the noun. It also
   reads well next to specialisms: the capabilities response would carry two Latinate
   declaration surfaces with cleanly split semantics — verified conformance versus advisory
   depth — rather than one Latinate term and one borrowed from a different ecosystem's
   jargon. If maintainers prefer a different term (agent_skills, soft_capabilities), the
   mechanism matters more than the noun.
2. Should competence entries carry an optional task_scope (e.g. get_products.refine) anchoring
   where the competence applies, or stay free-form until practice shows the need?
3. Is there appetite for an optional richer exposure later (full competence descriptions,
   akin to public skill registries), or does name + description remain the ceiling on the
   wire?

Related

• docs: knowledge gap (critical) — Distinguishing Refinement from Negotiation Skills #6101 — docs-layer neighbour: proposes documenting the refinement-vs-negotiation-skill
  distinction; this issue proposes the wire mechanism that documentation presumes.
• RFC: capability-change notifications for get_adcp_capabilities #5794 — RFC extending get_adcp_capabilities (change notifications): precedent for
  evolving the capabilities surface.
• RFC: Measurement capability declaration (tracking_capabilities, attribution methodologies, TMP exposure data) #6207 — RFC: measurement capability declaration: precedent for domain-specific capability
  declarations.
• Spec: standardize a get_schema capability tool for transport-symmetric schema discovery #3057 / known-limitations "No runtime schema-discovery tool": the deferred runtime
  discovery case — distinguished above (schemas are per-version and coverable out-of-band;
  conversational competence is per-agent and is not).

[bokelley]

Thanks for filing!

Triage

Classification: RFC — Feature request
Bucket(s): spec / protocol
Status: ready-for-human

What the experts said:

• ad-tech-protocol-expert: Layering (capability / specialism / competence) is schema-coherent and non-breaking — new optional task + boolean on an additionalProperties: true object. Four conditions before a PR opens: rename filter field domain → protocol (matching the supported_protocols enum to avoid the hyphen/underscore collision), add a kebab-case pattern constraint on name, add optional task_scope per competence entry, and clarify whether a competence update triggers the capabilities.changed webhook (RFC: capability-change notifications for get_adcp_capabilities #5794 intersection).
• adtech-product-expert: Problem is real, but opposes the two-call / open-vocabulary shape. Open vocabulary contradicts the protocol's typed discipline and advisory-without-storyboard becomes unreliable marketing noise quickly — prefers inline structured enum (media_buy.refine_capabilities: ["price", "terms", "audience"], same house pattern as buying_modes) or tightening refinement_applied.status SHOULD → MUST as a lower-friction alternative.
• ad-tech-protocol-expert-deep: Structural fit is sound; treats task_scope as a blocker (not an iteration item) — without it a competence can't be anchored to a specific task surface and a buyer still can't act on it programmatically. Recommends namespaced vocabulary ({protocol}.{term}, e.g. media_buy.price-negotiation) and co-scheduling WG review with RFC: Measurement capability declaration (tracking_capabilities, attribution methodologies, TMP exposure data) #6207 (both extend the "what can the counterparty reliably do" surface with the same structural questions).

My take: Experts split on the fundamental design shape. The problem is genuine — #6101 documents it as a knowledge gap from a real conversation — and this RFC is the wire-level mechanism that issue asked for. The concept has strong support; the implementation shape needs a WG call.

---

@bokelley — two decisions before this can advance:

Option A — Separate task, open vocabulary (proposed shape, with expert-flagged additions)

// get_adcp_capabilities — discovery pointer only
{ "adcp": { "competence_discovery": true } }

// get_adcp_competences — called on demand
{
  "competences": [
    {
      "name": "media_buy.price-negotiation",
      "task_scope": ["get_products.refine"],
      "description": "Reasons about margins and package trade-offs; returns counter-proposals on price asks."
    }
  ]
}

Progressive disclosure; agents that don't expose competences are unaffected; naturally extensible. Risk: advisory-without-conformance can drift from reality with no protocol signal.

Option B — Inline typed enum (product expert alternative)

// get_adcp_capabilities — single call, typed
{
  "media_buy": {
    "buying_modes": ["brief", "refine"],
    "refine_capabilities": ["price", "terms", "audience", "allocation"]
  }
}

No extra call; typed and codegen-friendly; auditable against a future storyboard. Risk: enum vocabulary must be WG-curated upfront; loses description-level nuance; cross-domain competences (e.g. signals + media_buy) need separate fields.

Both options still need an explicit spec note on whether the capabilities.changed webhook (#5794) fires when competences change. The deep advisor also recommends co-scheduling with #6207 — both RFCs resolve the same "what can the counterparty expect" design question.

Connection to #6101: if this RFC lands, the docs-patch that issue proposed is superseded by the new wire mechanism.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01LjgYi6G1NoVUAW1KSG9e4w

---

Generated by Claude Code

[lukasz-pubx]

Author here — responding to the triage conditions and the A/B question.

On the expert conditions: all accepted.

• domain → protocol on the filter field, matching the supported_protocols enum — agreed, clean fix.
• Kebab-case pattern constraint on name — agreed.
• task_scope accepted as part of the core shape, not an iteration item. The deep advisor's blocker framing is right: a competence a buyer can't anchor to a task surface is a slogan, not a signal. Open question 2 in the RFC is hereby resolved in favour of requiring it.
• Namespaced vocabulary ({protocol}.{term}, e.g. media_buy.price-negotiation) — agreed; it also partially answers the product expert's noise concern by giving names a structured spine while descriptions keep the nuance.
• capabilities.changed intersection (RFC: capability-change notifications for get_adcp_capabilities #5794): our position — yes, a competence change SHOULD fire it once RFC: capability-change notifications for get_adcp_capabilities #5794 lands. The discovery pointer lives in the capabilities response, so a competence change is a capabilities-surface change; the notification carries the pointer, the refreshed list stays behind get_adcp_competences.
• Co-scheduling WG review with RFC: Measurement capability declaration (tracking_capabilities, attribution methodologies, TMP exposure data) #6207: supported — both RFCs are the same design question ("what can the counterparty reliably expect") and should get one coherent answer.

On A vs B: we support either; slight, non-decisive preference for A. The reasons are the two things B structurally can't carry: description-level nuance (an LLM counterparty routes better on "reasons about margins and package trade-offs" than on "price"), and progressive disclosure with cross-domain reach without per-domain field proliferation. That said, B's typed discipline and codegen-friendliness are real — and A with the accepted conditions converges most of the way toward it: namespaced, pattern-constrained names anchored by task_scope are semi-structured claims, not free prose. If practice shows names converging, the vocabulary can graduate to a WG-curated enum exactly as specialisms did — A now doesn't foreclose B later, whereas B's upfront WG-curated vocabulary forecloses A's flexibility now. If the WG prefers B, we're glad to see the problem solved in that shape.

On the refinement_applied.status SHOULD→MUST alternative: worth doing on its own merits, but it's complementary rather than substitutive — it tells the buyer what happened after an ask; competences tell it what's worth attempting before. The wasted-round failure in the RFC happens ahead of any refinement_applied echo.

Happy to draft the schema PR once the WG picks the shape.

[lukasz-pubx]

Capturing offline feedback received on this RFC, because it deserves a spot in the record: "Why wouldn't this be on the proposal itself, to tell the buyer which dimensions can be negotiated? Is this really a capability of the agent or a feature of the proposal? If a seller doesn't return proposal.negotiable.pricing then you are stuck."

To anchor it in the current spec: there is no negotiable field on core/proposal.json today — the feedback sketches a design, not existing surface. But it's a real third shape alongside the two in the triage comment, so naming it:

Option C — per-proposal negotiability declaration. An optional typed field on the proposal object declaring which dimensions of this offer are open:

{
  "proposal_id": "prop-123",
  "proposal_status": "draft",
  "negotiable": ["pricing", "allocation", "product_composition"]
}

What Option C gets right — and where it beats A and B:

• It anchors the signal to the object the buyer wants to move. A negotiable dimension on a proposal is a per-deal business fact, and a refine ask against it is guaranteed to be considered — which implicitly declares the conversational competence too. On proposal surfaces, C subsumes the competence signal.
• It sidesteps the drift concern. The product expert's strongest objection to A was advisory-without-conformance drifting into marketing noise. A per-offer declaration travels with the response, is scoped to one deal, and is falsified or confirmed within the same conversation. It also moots the RFC: capability-change notifications for get_adcp_capabilities #5794 capabilities.changed question for this surface — nothing to go stale.
• It can solve the absence problem, which no agent-level mechanism can. "If the seller doesn't return it you are stuck" is true of every opt-in advisory signal — including this RFC's competences (absence = undeclared, not incapable). But C uniquely has a substrate for default semantics: proposal_status already half-encodes pricing negotiability (draft = indicative pricing, committed = firm pricing with a hold). The WG could define: on a committed proposal, absent negotiable means firm — a crisp default that A and B structurally cannot offer.

What Option C cannot cover — why it's complementary, not substitutive:

The RFC's headline failure (distinguishing "no" from "didn't understand") begins before any proposal exists: at seller selection, in buying_mode: "brief", in request-level asks, in more_like_this reasoning, and in signal-selection conversations — none of which have a proposal object to hang the flag on. A buyer deciding which seller is worth a conversational engagement at all needs an agent-level declaration; a buyer deciding whether this deal's price can move needs the proposal-level one.

Suggested resolution: adopt both, layered — proposal.negotiable (typed enum array, Option-B-style discipline, with the proposal_status default-semantics rule) as the authoritative in-deal signal, and get_adcp_competences for the pre-proposal routing surfaces. Where both are present, the proposal-level declaration wins for that proposal. I've folded Option C into the RFC's Alternatives section; if the WG sees C as sufficient on its own, the residual question is what covers the pre-proposal surfaces that motivated this RFC in the first place.

[bokelley]

Triage — Option C analysis

Following @lukasz-pubx's Option C comment (per-proposal negotiability declaration). Re-ran ad-tech-protocol-expert and adtech-product-expert on the new shape. The original A vs B analysis stands; this adds the expert view on C and the updated WG agenda.

What the experts said on Option C:

• ad-tech-protocol-expert: Schema-coherent, non-breaking MINOR addition to core/proposal.json (additionalProperties: true). Enum vocabulary needs cross-walking against actual proposal fields — product_composition is ambiguous (add/remove products vs. reweight); pacing and terms are worth considering too. The committed + absent negotiable = firm rule CAN be normative spec text: MUST for committed; draft + absent SHOULD be seller-unspecified, not implicitly open (critical for backward compat with pre-Option-C drafts). Recommends two separate PRs: advance Option C as a standalone MINOR now without blocking on A/B; park Option A in 3.2 Spec Backlog pending its vocabulary/task_scope/namespace blockers.
• adtech-product-expert: C addresses the drift concern better than A for in-deal scenarios (falsifiable within the same conversation). However, negotiable is still open vocabulary ("pricing" vs "price" vs "cpm_floor"); sell-side negotiability is conditional, not flat — silent mis-declarations likely. committed = firm is NOT a settled industry convention; encoding it as a default creates migration risk (a seller marking a proposal committed without knowing about negotiable silently signals firm pricing across all dimensions). Revised recommendation: B+C, not A+C — adopt C for in-deal; adopt Option B (typed inline enum in capabilities) for pre-proposal routing; retire Option A.

Expert split on pairing:
Protocol expert sees A+C as coherent; recommends sequencing (C first, A when its blockers clear). Product expert recommends B+C and retiring A. The A vs B split from the original triage is unchanged.

Updated WG agenda — three questions, not two:

1. Option C — proposal.negotiable (in-deal; both experts support adopting):

{
  "proposal_id": "prop-123",
  "proposal_status": "committed",
  "negotiable": ["pricing", "allocation"]
}

Open sub-questions for WG: (a) finalize enum vocabulary (should pacing and terms be in scope?); (b) whether committed = firm default lands immediately or is deferred pending migration analysis.

2. Pre-proposal mechanism — Option A vs B: Still split. Product expert now explicitly recommends B. Protocol expert parks A in Spec Backlog behind its open blockers — compatible with the original triage conditions regardless of which way C goes.

3. Sequencing: Protocol expert recommends advancing C as a standalone MINOR schema PR in the 3.2 cycle without waiting for the A/B decision.

Status: ready-for-human — WG decision required on all three questions.

---

Triaged by Claude Code. Session: https://claude.ai/code/cse_01YVYJK5gzypfek5ZzBpzYEt

---

Generated by Claude Code