--- name: usdl-interfaces description: Section-spanning Skill for authoring and extending the USDL Interfaces Section (interfaces.xml) — the "what crosses the wire out of the system" layer of a USDL Spec. User-invocable directly as /usdl:interfaces. Reads behavior.xml AND topology.xml as authoritative input (per the Chain of Trust); refuses to draft any interfaces Element when either higher Section is missing or fails `usdl validate`, surfacing exactly which Section is at fault (the missing-higher-section failure mode of `ifc.skill.interfaces`). Enforces the language-level scope rule of the Section: only contracts whose `provider` is an internal unit are declared — contracts the system consumes from external parties are deliberately out of scope and refused. Drives the Section-level interview in the order Stage 5 of how-to-use.md prescribes — walk every `` from topology.xml whose `provider` is internal, declare its ``, then its `` and `` children, then attach `` and `` blocks. Enforces all six mandatory attributes on every `` (`contract`, `name`, `intent`, `mode`, `consistency`, `delivery`, `idempotency`) and the "no paraphrase of URL into `intent`" rule that makes `intent` the semantic-review anchor. Enforces the mode-consistency rule between an `` and its carrying ``. Surfaces a See-Also Reference to usdl:interfaces:contracts whenever an operation needs a derived wire schema (the Skatchbook flow). Self-validates every batch via usdl:bin (`usdl validate interfaces.xml`) and emits the Section Handoff signal only after validation passes — releasing usdl:composition to begin. Trigger this Skill when the active task mentions "interfaces.xml", "contract", "operation", "schema-ref", "wire surface", "wire schema", "failure-mode", "author interfaces", "interfaces section", "exposed contract", "intent", "idempotency", or any of the kebab-case `ifc.*` ids that live in interfaces.xml. Description-only; no executable code. user-invocable: true --- # usdl-interfaces ## What this Skill is This is the **section-spanning Skill** that drives authoring (and extending) of one USDL Spec's `interfaces.xml`. It is the `/usdl:interfaces` user-invocable Skill the agent host loads when the active task is about the Interfaces Section: declaring every wire surface this system exposes to its consumers, with the domain `intent`, the four communication-shape attributes, the authoritative `schema-ref`, and the realistic `` blocks each consumer must honour. Its job is to: 1. Confirm that the **Chain of Trust** is intact before any drafting — both `behavior.xml` and `topology.xml` exist and pass `usdl validate`. 2. Refuse to author any contract whose `provider` is not an internal unit (the language-level scope rule of this Section). 3. Drive the Section-level interview in the order Stage 5 of `how-to-use.md` prescribes — walk every internal-provider `` in `topology.xml`, declare the matching ``, then its `` and `` children, then attach `` and `` blocks. 4. Enforce all six mandatory attributes on every `` (`contract`, `name`, `intent`, `mode`, `consistency`, `delivery`, `idempotency`) and reject any `intent` that paraphrases the URL or message name. 5. Enforce the cross-section mode-consistency rule between an `` and its carrying ``. 6. Surface a See-Also Reference to `usdl:interfaces:contracts` whenever an operation needs a derived wire schema (no authoritative external schema yet exists for it). 7. Self-validate every batch via `usdl:bin` (`usdl validate interfaces.xml`). 8. Emit a **Section Handoff** signal once `interfaces.xml` validates cleanly, releasing `usdl:composition` to begin. This Skill writes Interfaces Elements only. It must not author Behavior, Topology, or Composition Elements. Individual `` + `` drafting whose wire schema must be derived from a Skatchbook draft is delegated to `usdl:interfaces:contracts` via a See-Also Reference; the host routes between Skills. This Skill is **user-invocable**. It also is preloaded by `top.agent.interfaces-author` (the section-authoring Agent), which runs the same interview in isolated context and returns a summary diff of `interfaces.xml` plus any newly written schema files. ## How it fits with peer Skills - **Higher Sections (read-only, authoritative input):** - `usdl:behaviour` — the source of truth for actors, use cases, and shared Behavior Elements. Every `` resolves into use-case ids declared here. - `usdl:topology` — the source of truth for units (which `` resolves into) and `` edges (which carry the contracts Interfaces declares). Every internal-provider edge in `topology.xml` implies one or more `` Elements in this Section. - Interfaces trusts both Behavior and Topology unconditionally per `term.chain-of-trust` and `inv.section-chain-of-trust`. - **Element-targeted peer (See-Also Reference, surfaced at drafting time):** - `usdl:interfaces:contracts` — authors one `` + `` pair plus the operation's derived wire schema via the Skatchbook flow. Surfaced when an operation under interview has no authoritative external schema and the wire shape must be drafted as a typed code abstraction first, then translated into a JSON Schema (or AsyncAPI / Protobuf, per contract style). - **Template authority:** `usdl:templates` — owns the canonical Element Templates under `templates/interfaces/` (`full.xml`, `contract.xml`, `operation.xml`, `channel.xml`). Every draft validates against its Template before being written. - **Persistence and structural validation:** `usdl:bin` — wraps the `usdl` CLI. Used to run `usdl validate behavior.xml` and `usdl validate topology.xml` for the chain-of-trust pre-check and `usdl validate interfaces.xml` after every batch and at Section Handoff. - **Lower Section (downstream consumer):** `usdl:composition` — reads `interfaces.xml` as authoritative input once this Skill emits the Section Handoff signal. This Skill does not call it. This Skill never invokes peers directly; it surfaces See-Also References so the host can route, per `beh.rule.peer-skill-cross-reference`. ## See-Also References This Skill lists the following peer Skills as See-Also References, per `beh.rule.peer-skill-cross-reference`: - **`usdl:interfaces:contracts`** — when the active interview is about to draft an `` whose wire schema must be derived (no authoritative external schema yet exists). The peer opens a Skatchbook entry alongside the operation, walks the author through a typed code abstraction (PHP class, Python class, pseudo-code), derives a JSON Schema (or AsyncAPI / Protobuf, depending on contract `style`), writes the schema to the Spec's `schemas/` directory, and attaches it via `` children to the operation. Surfaced exactly when the Skatchbook flow is required; not surfaced when the author already has an authoritative external schema file. - **`usdl:bin`** — the wrapper around the `usdl` CLI. Used for the chain-of-trust pre-check (`usdl validate behavior.xml` AND `usdl validate topology.xml`) and the self-validate-before-done step (`usdl validate interfaces.xml`). Surfaced whenever the Skill needs the CLI. - **`usdl:templates`** — the bundled Element Templates and the Element-versus-Template conformance check. Surfaced whenever a ``, ``, or `` draft is being shaped against a Template. - **`usdl:behaviour`** — the section-spanning Skill for `behavior.xml`. Surfaced because Interfaces references Behavior (every `` points at a `` declared in `behavior.xml`): if the chain-of-trust pre-check fails on `behavior.xml`, the author is routed back to `usdl:behaviour` to fix or complete the higher Section before any interfaces Element is drafted. - **`usdl:topology`** — the section-spanning Skill for `topology.xml`. Surfaced because Interfaces references Topology (every `` points at a `` declared in `topology.xml`) and because the Section-level interview walks the inventory of internal-provider `` edges in `topology.xml`: if the chain-of-trust pre-check fails on `topology.xml`, the author is routed back to `usdl:topology` to fix or complete the higher Section before any interfaces Element is drafted. The Skill does not list `usdl:composition` or any lower-Section peer as a See-Also Reference, because references in the Spec flow upward only (`term.reference-direction`, `inv.reference-direction-monotonic`). ## Chain-of-trust pre-check (run before any drafting) Per `beh.rule.chain-of-trust`, `beh.halt-on-broken-chain`, and `inv.section-chain-of-trust`, this Skill **always** runs the chain-of-trust pre-check before authoring a single interfaces Element. The pre-check is non-negotiable: it is the Skill's first action on every invocation, including when the author asks to add a single Element to an already-existing `interfaces.xml`. The pre-check is the realisation of the `missing-higher-section` failure mode declared on `ifc.skill.interfaces` (`provider-promise="reports which higher Section is missing or invalid; no interfaces Element is written"`). It is doubly gated — both higher Sections must exist and validate cleanly before any drafting is permitted. Steps, in order: 1. **Confirm `behavior.xml` exists** in the Spec directory. If absent, the Skill halts immediately. The Skill reports: **"Interfaces cannot be authored: `behavior.xml` is missing. Behavior is one of two higher Sections that Interfaces trusts; please author it first via `usdl:behaviour`."** 2. **Confirm `topology.xml` exists** in the same directory. If absent, the Skill halts immediately. The Skill reports: **"Interfaces cannot be authored: `topology.xml` is missing. Topology is the other higher Section that Interfaces trusts; please author it via `usdl:topology` after `behavior.xml` validates."** 3. **Run `usdl validate behavior.xml`** via `usdl:bin`. The Skill does not parse `behavior.xml` itself; it delegates structural validation to Bin (per `beh.rule.self-validate-before-done` applied to the higher Section). If Bin exits non-zero, the Skill halts and surfaces the Bin diagnostics verbatim, including file path, line number, and the offending Element id. The Skill reports: **"Interfaces cannot be authored: `behavior.xml` fails `usdl validate`. Please fix the diagnostics below via `usdl:behaviour` and re-invoke `/usdl:interfaces` once Behavior validates cleanly."** 4. **Run `usdl validate topology.xml`** via `usdl:bin`. Same discipline: on non-zero exit, halt and surface diagnostics; route the author back via `usdl:topology`. 5. **Only on a clean pass of all four checks do further interview steps begin.** Until step 4 passes, the Skill refuses to draft any interfaces Element — no ``, no ``, no ``, no ``, no ``. It also refuses to load or pre-fill any Template. This is the language-level guarantee that broken Behavior or broken Topology never silently contaminates a downstream Section. On a halt, the Skill follows `beh.rule.escalate-not-fabricate`: it does not invent missing use cases or units to push past the failure; it names the higher-Section Element at fault (when Bin's diagnostics identify one) and routes the author back to the responsible Skill via a See-Also Reference. The halt is final for this invocation; the Skill exits without writing. The pre-check is also re-run **at every re-invocation** during a long authoring session — if the author edits `behavior.xml` or `topology.xml` mid-Interfaces-authoring, the next batch will re-validate both higher Sections before drafting more interfaces Elements. The Chain of Trust does not weaken over time. ## Scope rule — internal-provider contracts only Per Stage 5 of `how-to-use.md`, the Interfaces dictionary, and the Section reference (`sections/interfaces.md` § *Scope: exposed contracts only*), this Section documents **only contracts whose `provider` is an internal unit** — the wire surfaces this system stands behind. Contracts the system consumes from external parties are deliberately out of scope and **the Skill refuses to author them**. This is a hard refusal, enforced at the section-spanning grain, for three reasons: - The external party is the source of truth for its own contract. Restating it here creates a second source of truth that drifts as the external party changes their spec. - Caller-side verification of an external contract is the job of consumer-driven contract tests written against the external party's authoritative schema, not of a redeclaration in this Spec. - The fact that the system reaches out to an external party is already captured in `topology.xml` as a `` edge whose `to=` resolves to a ``. The consumer-side handling lives in Composition (the outbound adapter component's constraints) and in Behavior (the use case's alternative flows). The Skill enforces the rule mechanically: 1. **Walk the inventory.** For every `` in `topology.xml`, look up the unit named by the `provider` of the carried contract — operationally, the `to=` end of a request-response edge, or the `from=` end of an event-broadcast edge — and resolve the unit's `internal` attribute. 2. **Refuse external providers.** If the resolved unit has `internal="false"`, the Skill refuses to draft a `` for that edge and explains the rule to the author. The refusal is not negotiable; if the author insists, the Skill escalates per `beh.rule.escalate-not-fabricate` and exits the slot. 3. **Accept internal providers only.** A `` is drafted only when its `provider` unit has `internal="true"` or the attribute is omitted (Topology defaults `internal` to `true`). The Skill never paraphrases an external party's published API as a USDL ``. The Topology edge to the `internal="false"` unit is sufficient documentation of the outbound interaction; the consumer-side adapter belongs in Composition. ## Authoritative inputs Once the chain-of-trust pre-check passes, the Skill loads: 1. **`behavior.xml`** — read-only, authoritative. Source of the use-case ids that `` resolves into. The Skill cross-checks every `realizes-behavior` value against `behavior.xml` before writing the operation; an unresolved reference is rejected before Bin sees it. 2. **`topology.xml`** — read-only, authoritative. Source of the unit ids that `` and `` resolve into; source of the `` edges the Section-level interview walks; source of each unit's `internal` attribute (the gate for the scope rule). The Skill also reads each ``'s `mode` so the cross-section mode-consistency rule can be enforced (see below). 3. **`interfaces.xml`**, if it already exists — to detect id collisions on new Elements, to resolve `contract=` references against existing `` ids, and to extend rather than re-create when the author invokes `/usdl:interfaces` on a partially-authored Section. 4. **`sections/interfaces.md`** — the Section reference (purpose, scope, what belongs, what does not belong, the six-attribute table, the four-enum grid, the failure-mode caller-action enum). The Skill **refers to** this file when explaining the Section to the author; it does **not** inline its content into the SKILL.md body. 5. **`dictionaries/interfaces_dictionary.md`** — the Interfaces dictionary, source of the closed enums for `style`, `mode`, `consistency`, `delivery`, `idempotency`, `role`, `format`, `caller-action`, and `ordering`. The Skill **refers to** the dictionary when offering enum menus and when defending rejections; it does **not** inline the dictionary's tables. 6. **`templates/interfaces/full.xml`** plus the per-Element templates (`contract.xml`, `operation.xml`, `channel.xml`) — loaded via `usdl:templates`. Element drafts are validated against these Templates before being written. ## Section-level Interview Script (contracts → operations → schemas → failure modes) The Skill drives the Section-level interview by walking the inventory of internal-provider `` edges in `topology.xml`. For each such edge, in declaration order, the Skill works **outside-in**: declare the `` first, then enumerate its `` and `` children, then attach `` and `` blocks to each operation or channel. Within each Element, the minimum-interview rule (`beh.rule.minimum-interview`) applies: required slots are asked unconditionally; optional slots are surfaced as offers and asked only when the author signals interest. ### Stage A — Contracts first For each internal-provider edge in `topology.xml`, the Skill asks: 1. **Does an existing `` already document this edge?** If so, the Stage moves to operations under that contract. 2. **Otherwise, draft a new ``.** Required slots: `id`, `provider` (looked up from the Topology edge, must be internal), `consumers` (looked up from the edge), `style` (asked unconditionally; the enum is the contract-style table from the Section reference). Optional slot: `spec-ref` (asked only if the author indicates an authoritative external spec file already exists for this contract). The Skill drafts each `` Element inline against `templates/interfaces/contract.xml` via `usdl:templates`. No element-targeted peer Skill exists for contracts alone — `usdl:interfaces:contracts` is surfaced only at the operation level, when an operation needs a derived wire schema. At the end of Stage A for one contract, the Skill batches the new contract, runs `usdl validate interfaces.xml` via `usdl:bin`, and only proceeds when validation passes. ### Stage B — Operations second For each `` just declared (or already present), the Skill walks every operation the contract exposes. Each operation becomes one `` Element. The required slots, asked unconditionally per `beh.rule.minimum-interview`, are exactly the seven on the Section's six-attribute table (`id` is the seventh, structural): - `id` — kebab-case, unique within the Spec. - `contract` — the owning contract's id; resolved from context. - `name` — the stable wire name (`POST /bookings`, `BookingCreated`, `RPC.ChargePayment`). - `intent` — a short imperative sentence in domain terms. **The Skill rejects any `intent` that paraphrases the URL or message name.** "Create a Booking in PENDING for a selected Offer" is correct; "Handle POST to /bookings" is not. The `intent` is the semantic-review anchor — the only attribute on `` not captured mechanically by the wire schema — and is treated by this Skill as non-negotiable. When the author submits a paraphrase, the Skill asks the corrective question ("what does this operation *mean* in the language of the domain?") and refuses to draft until a domain-term sentence is supplied. - `mode` — the closed enum from the Section's Mode table (`sync-request-response`, `async-fire-forget`, `async-request-callback`, `async-event-broadcast`, `stream-push`, `stream-pull`). No implicit default. The Skill rejects abbreviated tokens (`sync` is not a legal `mode`). - `consistency` — the closed enum (`strong`, `read-your-writes`, `eventual`, `not-applicable`). `not-applicable` is a valid choice but must be chosen explicitly. - `delivery` — the closed enum (`at-most-once`, `at-least-once`, `exactly-once-effective`, `not-applicable`). Same rule. - `idempotency` — the closed enum (`required`, `recommended`, `not-applicable`). Same rule. Optional slots, surfaced as offers: - `realizes-behavior` — comma-separated `` ids in `behavior.xml`. Asked when the operation participates in one or more use cases; the Skill resolves each id against `behavior.xml` and rejects unresolved values before writing. (Filled by Interfaces.) - `governed-by` — comma-separated `` ids in `composition.xml`. **Left blank during the first Interfaces authoring pass** because Composition does not exist yet. A return pass after Composition is authored fills `governed-by` per Stage 5 of `how-to-use.md`. (Filled by Interfaces, but deferred.) The Skill drafts each `` Element against `templates/interfaces/operation.xml` via `usdl:templates`. The four-enum grid in the Section reference is offered as a cognitive shortcut when the author hesitates on the combination, but never overridden onto the author — every combination is asked explicitly. #### Cross-section mode-consistency rule Per the Section reference (Rule 7) and the Interfaces dictionary, an `` must match the `` declared in `topology.xml` for the carrying edge. The Skill enforces this at draft time: 1. Resolve the `` in `topology.xml` whose contract is the operation's contract (via `carries=` once filled, or via the Section-level inventory walk before `carries=` is filled). 2. Compare its `mode` attribute against the operation's proposed `mode`. 3. On mismatch, halt the slot, surface both values, and ask which is correct. The Skill never silently amends one to match the other; the author must reconcile them, either by amending the operation's `mode` or by routing back to `usdl:topology` to amend the communication's `mode`. The same enums (`mode`, `consistency`, `delivery`) appear on both Sections precisely so the values are comparable; the Skill treats divergence as a spec-level bug and refuses to write the offending operation until it is resolved. #### When to surface `usdl:interfaces:contracts` After the seven required slots are filled and accepted, the Skill asks: **"Does this operation have an authoritative external schema file already (OpenAPI, AsyncAPI, JSON Schema, Protobuf, Avro, etc.)?"** - **Yes** — the author supplies the path. The Skill attaches the `` inline (role, format, uri) and proceeds to failure modes. No peer Skill is surfaced. - **No** — the Skill surfaces **`usdl:interfaces:contracts`** as a See-Also Reference. The peer opens a Skatchbook entry alongside this operation, walks the author through a typed code abstraction (PHP class, Python class, or pseudo-code, per the author's preference), derives a schema in the format that matches the contract's `style` (JSON Schema for REST, AsyncAPI for event-stream, Protobuf for gRPC, etc.), writes the schema to the Spec's `schemas/` directory (`./schemas//.`), and returns the resulting `` children for this Skill to attach to the operation. The peer never writes the operation itself — that mutation goes through this Skill via `usdl:bin`, per `con.skatchbook-no-direct-spec-writes`. The See-Also Reference is surfaced exactly when the Skatchbook flow is required; the parent Skill does not invoke the peer directly, the host routes between Skills. At the end of Stage B for one contract, the Skill batches the new operations, runs `usdl validate interfaces.xml` via `usdl:bin`, and only proceeds when validation passes. ### Stage C — Channels (event-stream and command/query-bus contracts) For contracts whose `style` is `event-stream`, `command-bus`, or `query-bus`, the Skill enumerates every `` the contract publishes. Required slots per the Interfaces dictionary: `id`, `contract`, `name`, `delivery`, plus a `` child. Optional slots: `ordering` (closed enum: `none`, `per-partition-key`, `global`) and `retention` (free-form string like `7d`, `compacted`). Channels also carry one or more `` children — typically a single `event`-role schema. The same Skatchbook routing rule applies: surface `usdl:interfaces:contracts` when no authoritative external schema exists for the channel's event shape. The Skill drafts each `` Element against `templates/interfaces/channel.xml` via `usdl:templates`. ### Stage D — Failure modes (per operation, per channel) For each operation and each channel, the Skill walks the realistic failure modes the consumer must handle. *Realistic* means observed in production at this kind of unit OR required to be handled by the consumer (e.g. `validation-failure` for any input-bearing operation; `timeout` on any sync edge crossing a network boundary). Required slots on each ``: `condition` (free-form slug; the Section reference lists common ones — `timeout`, `validation-failure`, `upstream-5xx`, `duplicate-request`, `network-partition`, `quota-exceeded`, `schema-mismatch`, `poison-message`) and `caller-action` (the closed enum from the Section's caller-action table: `retry-with-backoff`, `circuit-break`, `dead-letter`, `compensate`, `fail-fast`, `log-and-ignore`, `fallback-to-degraded`). Optional slot: `provider-promise` — what the provider guarantees on this failure. A heuristic the Skill applies: **if more than five `` blocks accrue on one operation, the operation is doing too much.** The Skill surfaces this Section-reference observation to the author as a prompt to consider splitting the operation, but never amends the operation on the author's behalf. At the end of Stage D for one contract, the Skill batches the new failure modes, runs `usdl validate interfaces.xml` via `usdl:bin`, and proceeds to the next contract. ## Cross-reference attributes filled by Interfaces Per the Interfaces dictionary's cross-reference table, the Skill is responsible for filling the following attributes on Interfaces Elements; their referent targets are owned by other Sections, and the Skill resolves each against the relevant higher Section before writing: - **`provider`** on `` — resolved against `` ids in `topology.xml`; must point at an internal unit (the scope rule above). - **`consumers`** on `` — resolved against `` and `` ids in `topology.xml` and `behavior.xml` respectively. - **`contract`** on `` and `` — resolved against `` ids in `interfaces.xml` (internal to this Section). - **`realizes-behavior`** on `` — resolved against `` ids in `behavior.xml`. Use cases never reference operations; only the reverse direction is valid. - **`governed-by`** on `` — resolved against `` ids in `composition.xml`. **Filled by a return pass after Composition is authored**, not during the first Interfaces authoring pass; the Skill leaves the attribute unset and records the deferral in the Section Handoff payload so a future `/usdl:interfaces` invocation can complete the linkage. Inverse references (`` in `topology.xml`) are owned by Topology, not this Skill; the Skill notes which communications in `topology.xml` will need a return-pass `carries=` update once contracts are written, but does not mutate `topology.xml` itself. ## Minimum-interview rule Per `beh.rule.minimum-interview`, this Skill asks unconditionally only those questions whose answers fill **required** attributes or **required** children of the Element being authored: - For ``: `id`, `provider`, `consumers`, `style`. `spec-ref` is optional. - For ``: the seven required attributes from the Section reference (`id`, `contract`, `name`, `intent`, `mode`, `consistency`, `delivery`, `idempotency`) plus at least one `` for any payload-bearing operation. `realizes-behavior` and `governed-by` are optional in the dictionary but in practice `realizes-behavior` is asked because every operation realises at least one Behavior use case (the Skill prompts but does not invent). - For ``: `id`, `contract`, `name`, `delivery`, and a ``. `ordering` and `retention` are optional. - For ``: `role`, `format`, `uri`. - For ``: `condition`, `caller-action`. `provider-promise` is optional. Optional slots are surfaced as offers — short prompts the author can decline. If the author declines, the attribute or child is omitted. This minimises the author's cognitive load per `nfr.author-cognitive-load`. The Skill never invents an answer to satisfy an optional slot, never inserts placeholders, and never asks an optional question more than once per Element. ## Self-validate via usdl:bin (after each batch) Per `beh.rule.self-validate-before-done` and the `inv.spec-section-validity` invariant, this Skill runs `usdl validate interfaces.xml` via `usdl:bin` after each batch — once at the end of Stage A (contracts) for the current contract, once at the end of Stage B (operations), once at the end of Stage C (channels), and once at the end of Stage D (failure modes). The Skill does not declare a batch complete until validation passes. On a Bin failure: 1. Classify each diagnostic as Trivial or non-Trivial per `beh.attempt-trivial-repair`. 2. For Trivial diagnostics (id collision with a numeric-suffix rename, enum substitution, duplicate child removal), apply the repair and re-run `usdl validate`. 3. For non-Trivial diagnostics (semantic, ambiguous, missing required input — including any `intent` paraphrase rejection that slipped past the in-interview check, any unresolved `realizes-behavior` reference, any mode-consistency mismatch with `topology.xml`), escalate to the author per `beh.rule.escalate-not-fabricate` — re-open the interview slot the diagnostic points at, ask the corrective question with the legal shape, and re-run validation once the answer is in. 4. Bounded retries per `beh.rule.repair-bounded`; on exceeding the limit, the Skill halts and surfaces the remaining diagnostics without declaring the Section complete. The Skill itself does **not** mutate `interfaces.xml` directly. Mutations go through `usdl:bin` (or, when the host runs Write/Edit on its behalf, through a tool call the parent / Agent makes); this Skill describes the flow and surfaces the validation discipline. ## Section Handoff (releases usdl:composition) Per `beh.handoff-section` and `inv.section-chain-of-trust`, this Skill emits the **Section Handoff** signal exactly when: 1. Every contract implied by an internal-provider `` in `topology.xml` has been declared in `interfaces.xml` (or the author has explicitly deferred a contract with a recorded reason). 2. Every operation has its seven required attributes set, at least one `` attached for payload-bearing operations, and any required `` blocks declared. 3. The final `usdl validate interfaces.xml` invocation reports **zero errors** (warnings are reported to the author but do not block handoff). 4. The author has confirmed the diff for this authoring pass (when running under `/create-specification`, this is the orchestrator's confirmation; when running standalone via `/usdl:interfaces`, this is the author's direct acknowledgement). The handoff signal names the Section (`interfaces`), its validated state, and any deferred work — most commonly, the list of operations whose `governed-by` was deliberately left blank pending Composition authoring, and the list of `` Elements in `topology.xml` whose `carries=` will need a return-pass update once contracts are written. The handoff is the moment `usdl:composition` may be invoked with `behavior.xml`, `topology.xml`, and `interfaces.xml` all loaded as authoritative input. The Skill withholds the handoff signal if validation still reports errors at the moment handoff would normally occur. In that case it surfaces the diagnostics, refuses to declare completion, and waits for the author to either correct the offending input or accept an escalation that defers the failing Element. The handoff is the language-level commitment that downstream Sections may trust this Section; this Skill never signals it under false pretences. ## Response shape A successful invocation returns to the parent (`/create-specification` or the spec author directly): - A summary of every ``, ``, ``, ``, and `` Element written or modified in `interfaces.xml`, with their ids. - The list of newly written schema files in the Spec's `schemas/` directory, when `usdl:interfaces:contracts` was surfaced and the Skatchbook flow produced derived schemas. - The current pass/fail status of `usdl validate interfaces.xml`. - The list of operations whose `governed-by` was deliberately left blank pending Composition (so a future `/usdl:interfaces` invocation, after `usdl:composition` has run, can complete the linkage). - The list of `` ids in `topology.xml` whose `carries=` will need a return-pass update. - The Section Handoff signal when validation passes and the author confirms; otherwise the outstanding diagnostics or open interview questions. A halted invocation (chain-of-trust pre-check failure on either higher Section, external-provider scope refusal, or non-Trivial diagnostic exceeding the repair limit) returns instead: the Section at fault (when the halt is upstream), the Bin diagnostics, and a See-Also Reference to the Skill that owns the broken input (`usdl:behaviour` when `behavior.xml` is the cause; `usdl:topology` when `topology.xml` is the cause; `usdl:interfaces:contracts` when the Skatchbook flow failed to derive a schema). No `interfaces.xml` Element is written under a halt. ## What this Skill does not do - It does not author any Element outside `interfaces.xml`. Behavior, Topology, and Composition are out of scope; the Skill refuses to extend them and escalates if the author asks. - It does not declare a `` whose `provider` is an external unit. The Topology edge to the `internal="false"` unit is the only documentation; redeclaring the external party's contract creates a second source of truth. - It does not paraphrase an operation's URL or message name into `intent`. The `intent` attribute is the semantic-review anchor and is treated as non-negotiable. - It does not silently amend an `` to match the carrying `` (or vice versa). The mismatch is surfaced; the author reconciles. - It does not derive wire schemas inline. When no authoritative external schema exists, the Skill surfaces `usdl:interfaces:contracts` and lets the host route to the Skatchbook flow. - It does not inline `sections/interfaces.md` or `dictionaries/interfaces_dictionary.md` into its own body; it refers to them and lets `usdl:templates` and `usdl:interfaces:contracts` carry the dictionary's enum tables and the template skeletons. - It does not copy template XML into the body. Templates live under `templates/interfaces/` and are loaded via `usdl:templates`. - It does not skip the chain-of-trust pre-check — not on re-invocation, not on "just one more operation" requests, not on the author's verbal assurance that the higher Sections are fine. Bin is the only judge; both `behavior.xml` and `topology.xml` are checked. - It does not fill `governed-by` during the first Interfaces authoring pass; that linkage is deferred until Composition exists. - It does not emit the Section Handoff signal until `usdl validate interfaces.xml` passes with zero errors. - It does not invoke peer Skills. Routing between Skills is the host's responsibility, informed by the See-Also References declared above. - It does not carry executable code (`con.no-implementation-code-in-skill-md`). Everything above is prose describing what to check, in what order, and what to forbid.

usdl-interfaces

Install this skill

Comments