--- name: usdl-topology-services description: Element-targeted Skill that authors one USDL `` Element in topology.xml. Owns the unit Interview Script that collects the kebab-case id (prefixed `top.`), the runtime kind (open-ended kebab-case slug; common values include service, worker, scheduled-job, cli, database, queue, topic, cache, object-store, external-api, firmware, browser-app, mobile-app, function, gateway, proxy, claude-code-skill, claude-code-agent), the owning team, the internal-or-external flag (default `true`; asked explicitly only when the author signals an external integration), and the one-sentence-to-one-paragraph domain-terms description, plus the optional `produces`/`consumes` event/channel cross-references when the unit emits or reads named events. Trigger this Skill when the active task mentions "unit", "service", "worker", "scheduled job", "deployment", "runnable thing", "deploy thing", "process", "topology unit", or `kind=` in the context of authoring or extending topology.xml. Not user-invocable directly; surfaced as a See-Also Reference from usdl:topology (and preloaded by top.agent.topology-author). Drafts XML matching templates/topology/unit.xml via usdl:templates and the parent skill then calls Bin through usdl:bin to validate. Carries no executable code. --- # usdl-topology-services ## What this Skill is This is the element-targeted Skill that authors **exactly one `` Element** for `topology.xml`. It owns the unit **Interview Script** (`term.interview-script`): the ordered sequence of questions an element-targeted Skill asks the Spec author to fill one Element kind. Its sole job is to gather every required Template slot, draft the Element from the unit Template, and hand the draft to the parent skill for validation and writing. It is **not user-invocable directly**. It is surfaced as a **See-Also Reference** from `usdl:topology` (per `beh.rule.peer-skill-cross-reference`) and preloaded by `top.agent.topology-author`. The agent host loads it when `usdl:topology` recognises that a `` Element is about to be drafted. This Skill writes Topology Elements only. It must not author Behavior, Interfaces, or Composition Elements; it must not author other Topology Element kinds (`` is the responsibility of the peer `usdl:topology:communication`; `` is the responsibility of the parent `usdl:topology`). ## How it fits with peer Skills - **Parent (See-Also source):** `usdl:topology` — the section-spanning Skill. When the section interview reaches the "units first" step, `usdl:topology` names this Skill in its response so the host may load it. - **Template authority:** `usdl:templates` — owns `templates/topology/unit.xml` (the canonical unit Template) and the Element-versus-Template conformance check. Every draft this Skill produces is validated against the Template before being written. - **Persistence and structural validation:** `usdl:bin` — wraps the `usdl` CLI. After this Skill emits a draft, the parent skill calls `usdl validate` through `usdl:bin` to confirm the Section file is structurally sound and references resolve. - **Peer Element Skills (informational only):** `usdl:topology:communication`, `usdl:behaviour:usecase`, `usdl:behaviour:nfr`, `usdl:interfaces:contracts`, `usdl:composition:skatchbook` are siblings; none are called by this Skill. Routing between Skills is the host's job. This Skill does not invoke peers. It surfaces information so the host can route, per `beh.rule.peer-skill-cross-reference`. ## Authoritative inputs Before asking a single question, the Skill loads: 1. `templates/topology/unit.xml` — the canonical unit Template (via `usdl:templates`). Every required Template slot becomes a required interview question; every optional slot becomes an optional question (asked only after the author signals interest). 2. The current `topology.xml` (via the parent skill) — to detect id collisions on the new unit's id and to know which `top.*` ids already exist. 3. `behavior.xml`, treated as authoritative input — to know which `evt.*` (event) and channel ids the author may legitimately name in `produces=` and `consumes=`. Per `term.chain-of-trust`, Topology trusts Behavior; the Skill never invents an event id that does not appear in `behavior.xml`. 4. The Topology dictionary `` row, its quick-reference required-attributes table, and the common `kind=` values table — encoded in this script's required-slot list and `kind=` offer below. The Skill never asks for an attribute or child the Template does not declare, and never omits one the Template requires. ## The Interview Script (ordered) The Skill runs the questions below in order. **Required slots are asked unconditionally.** Optional slots are surfaced as offers ("Does this unit emit or consume any named domain events or channels?") and asked only when the author signals interest. This implements `beh.rule.minimum-interview`. ### Required slots (asked unconditionally) 1. **`id`** — the unit id. Kebab-case, unique across the entire Spec, prefixed `top.`. Example question: "What kebab-case id should this unit carry? (We'll prefix `top.` — e.g. `top.booking-svc`, `top.payments-worker`, `top.checkout-db`.)" The Skill rejects ids that collide with an existing ``, ``, or `` id in `topology.xml`. 2. **`kind`** — the runtime shape of the unit, as a kebab-case slug. The `kind=` attribute is **open-ended**: any descriptive kebab-case slug is valid, but the language recognises a list of **common values** that fit most runtime shapes. The Skill offers the common values as a menu and explicitly states the enum is open-ended. Example question: "What kind of runnable thing is this? Pick a common value if one fits, or supply a project-specific kebab-case slug if the runtime shape isn't on the list. Common values: - `service` — long-running server process exposing one or more contracts. - `worker` — long-running consumer process subscribed to a queue, topic, or stream. - `scheduled-job` — process invoked on a schedule (cron-like). - `cli` — command-line tool invoked by a human or another process. - `database` — authoritative durable store (use this; the dictionary's relational/nosql distinction lives in `` or an ADR). - `queue` — point-to-point message queue. - `topic` — pub-sub topic / log. - `cache` — volatile or semi-durable cache layer. - `object-store` — blob / object store (S3-style). - `external-api` — third-party API consumed by the system (typically paired with `internal=\"false\"`). - `firmware` — embedded device firmware. - `browser-app` — single-page or multi-page web app running in a browser. - `mobile-app` — mobile application. - `function` — serverless / FaaS unit invoked per event. - `gateway` — API gateway or ingress. - `proxy` — reverse or forward proxy. - `claude-code-skill` — a Claude Code Skill (SKILL.md), loaded by the agent host on demand. The unit's `` states whether the Skill is user-invocable and gives its full namespaced name (e.g. `usdl:behaviour:usecase`). - `claude-code-agent` — a Claude Code Agent (AGENT.md): an isolated execution context spawned by the host. The unit's `` states the preloaded Skill set, the return shape (summary diff, structured status), and any tool allowlist. None of these fit? Supply a custom kebab-case slug (e.g. `iot-sensor`, `lambda-edge`, `unikernel`). The enum is open-ended — whatever value you pick is still the verification anchor: a deployment-time inventory must show a running thing matching it." The Skill records the chosen value verbatim. It does not paraphrase, normalise, or coerce a custom slug into a common value. 3. **``** — exactly one prose block: one sentence to one paragraph, in **domain terms** describing what this unit is responsible for at runtime. Example question: "In one sentence to one paragraph, what is this unit responsible for at runtime? Use domain terms. Do not name the tech stack (no 'Postgres 15', no 'Express server'); a technology hint goes in `` instead, and substantive technology decisions go into an ADR referenced via ``." If the author's draft mentions a specific product or framework, the Skill restates the question and asks for a domain-terms version; if the author insists, the Skill records the prose verbatim **and** offers a `` child to carry the technology hint separately. ### Conditional and optional slots 4. **`owner`** (optional per the dictionary, but project convention is to fill it) — the team or person responsible. Example question: "Which team or person owns this unit? (Free-text string — team name, squad name, or individual.) If you don't know yet, say 'unknown' and I'll escalate rather than guess." The Skill **never fabricates** an owner. If the author says "unknown" or "skip", the Skill records the slot as unfilled and surfaces it to the parent skill as an escalation note — the parent decides whether to proceed with the attribute omitted (legal, since `owner=` is optional) or to pause and ask the author to find out. This follows `beh.rule.escalate-not-fabricate`. 5. **`internal`** — boolean, **defaults to `true`**. The Skill **does not ask** this question unconditionally. It only surfaces the slot when the author has signalled an external integration (e.g. the unit's name or description mentions "third-party", "external", "vendor", "supplier", "customer-supplied", "outside our boundary", or the proposed `kind` is `external-api`). When that signal is present, the Skill asks: "This unit looks like it sits outside the system boundary. Set `internal=\"false\"` to make that explicit? (Default is `true`; the explicit override keeps the boundary visible at a glance.)" When no external signal is present, the Skill leaves `internal=` unset and relies on the dictionary default. 6. **`` block** (optional; per project extension) — surfaced only if the author signals interest in declaring named configuration knobs. Example offer: "Does this unit have named configuration knobs you want documented in the Spec?" If yes, the Skill loops over knob name + purpose pairs in domain terms. 7. **`` block** (optional; per project extension) — surfaced only if the author signals interest in documenting runtime attributes (replica count, resource envelope, scheduling hints) in domain terms. The Skill **never invents** runtime details: replica counts, memory ceilings, scheduling cadences. If the author cannot supply a value, the Skill escalates per `beh.rule.escalate-not-fabricate`. 8. **``** (optional) — surfaced when the author named a specific product or framework in question 3 and accepted moving it out of ``. One free-text line, e.g. "Postgres 15", "Kafka 3.x". Informational only; spec lint does not derive claims from it. 9. **`produces`** (optional) — comma-separated `` or `` ids the unit writes. Surfaced under the umbrella offer "Does this unit emit or consume any named domain events or channels?" If yes, the Skill asks for each id and resolves it against `behavior.xml`. **Missing referenced ids are escalated, not fabricated** (see below). 10. **`consumes`** (optional) — comma-separated `` or `` ids the unit reads. Same resolution discipline as `produces`. ### Status attribute (asked last, with default) 11. **`status`** — defaults to `accepted`. The Skill confirms ("Set status to `accepted`, `draft`, `proposed`, `deprecated`, or `superseded`? Default is `accepted`.") and only inserts the attribute if the answer differs from the default. ## Forbidden slots — Topology stays at unit grain The Skill **explicitly forbids** every attribute or child that does not belong on a ``. The script never asks for, never accepts, and never emits: - Endpoint paths, message names, payload shapes, class names, function signatures — those live in **Interfaces** or **Composition** and never appear on a ``. Forbidden. - A use-case id, a behaviour rule id, a component id — Topology never points down into Behavior, Interfaces, or Composition from a ``. The only outward links a `` carries are `produces=`/`consumes=` (which point at ``/`` ids defined in Behavior/Interfaces, per Topology's reference direction) and the cross-section references on `` (which this Skill does not author). Anything else is forbidden. - A `` child, an `` child — `` is a leaf in Topology's top-level grammar (with ``, optional ``, optional ``, plus the optional `` and `` extension blocks). Other Topology Element kinds are authored by their own peer Skills. Forbidden. This implements `beh.rule.no-code-in-spec` and the Topology dictionary's section invariant that "no endpoint paths, message names, payload shapes, class names, or use cases appear in Topology". If the Skill detects a forbidden slot proposed by the author or by upstream context, it refuses the slot and explains the section-boundary rule. ## Escalate-not-fabricate The Skill follows `beh.rule.escalate-not-fabricate` for every slot. The flow on an unparseable, ambiguous, or missing answer: 1. **Restate once with the legal shape.** If the `kind` answer is "it's the booking thing" (free text where a kebab-case slug was expected), the Skill responds: "I need a kebab-case slug. From the common values, `service` or `worker` look closest given your description — which fits? Or supply a project-specific slug like `booking-engine` if neither fits." 2. **If the second answer is still unparseable, escalate and pause.** The Skill returns to the parent skill with the open question and the legal shapes; it does **not** invent a placeholder, omit the slot, or write a malformed draft. 3. **Owner is never fabricated.** A "skip" or "unknown" answer to question 4 records the slot as unfilled and surfaces it to the parent — `owner=` is optional in the dictionary, but the Skill never invents a team name. 4. **Runtime details are never fabricated.** Replica counts, memory ceilings, scheduling cadences, configuration values — if the author cannot supply them, the Skill escalates. It never invents a number. 5. **Missing referenced ids are escalated, not fabricated.** If the author says the unit produces `evt.booking-confirmed` but that event does not exist in `behavior.xml`, the Skill pauses and tells the parent skill: add the event in `behavior.xml` first; do not invent it inline. Same discipline for `consumes=`. The Skill never inserts placeholders (no `TODO`, no `owner="unknown-team"`, no empty ``). Missing required input always escalates. ## Drafting and validation Once every required slot has a parseable answer (and any affirmed optional slots are filled), the Skill drafts the `` Element to match `templates/topology/unit.xml`: 1. **Load the Template** via `usdl:templates`. The Template is the slot map; the Skill fills each slot with the corresponding gathered answer in the order the Template prescribes. 2. **Validate the draft against the Template** before writing — every required attribute (`id`, `kind`) present, no unknown attributes, the required child (``) present, child order correct, optional children (``, ``, project `` / `` blocks) in their declared positions. This is the `usdl:templates` Element-versus-Template conformance check, run on the draft in memory, per `beh.rule.template-validated-element`. 3. **Hand the draft to the parent skill** (`usdl:topology` or the spawning Agent). The parent owns Section-file mutation; this Skill never writes to `topology.xml` itself. 4. **Parent calls Bin via `usdl:bin`** to run `usdl validate` against the updated `topology.xml`. Per `beh.rule.self-validate-before-done`, completion is reported only after validation passes; on failure the parent applies trivial repair or escalates back into this Skill's script for the offending slot. ## Response shape A successful pass returns to the parent skill: - The drafted `` XML, conforming to `templates/topology/unit.xml`. - The set of gathered answers, keyed by slot name. - The list of any **referenced ids that need to be added first** (events or channels the author named in `produces=`/`consumes=` but that do not yet exist in `behavior.xml`). - The list of any **unfilled optional slots that warrant author follow-up** (e.g. `owner=` recorded as "unknown" — the parent may want to chase this). - An empty list when no escalation is needed. An escalation pass returns instead: the open question, the legal shape that was rejected, the slot it belongs to, and the partial draft (never written). ## What this Skill does not do - It does not author any Element other than one ``. Authoring a `` is delegated to the peer `usdl:topology:communication`; authoring an `` is delegated to the parent `usdl:topology`. - It does not author Behavior, Interfaces, or Composition Elements. Cross-section additions (missing events, missing actors) are escalated to the parent skill. - It does not write `topology.xml` directly. Mutations go through the parent skill, which uses Bin. - It does not call `usdl:bin` itself. Bin invocation is the parent's responsibility. - It does not invoke peer Skills. Routing is the host's job. - It does not normalise, paraphrase, or coerce custom `kind=` slugs into common values. The author's choice is recorded verbatim. - It carries no executable code (`con.no-implementation-code-in-skill-md`). Everything above is prose describing what to ask, in what order, and what to forbid.

usdl-topology-services

Install this skill

Comments