--- name: usdl-templates description: Holds the canonical USDL Element Templates and the rules for validating a proposed Element against its Template before it is written to a Section file. Loaded as a See-Also Reference by every section-spanning Skill (usdl-behaviour, usdl-topology, usdl-interfaces, usdl-composition) and preloaded by every Agent. Use this Skill whenever a Template lookup is needed (for example "actor Template", "use-case Template", "communication Template") or whenever Element validation is required — the conformance check that every required attribute and required child is present and no unknown attribute or child slipped in. Not user-invocable on its own. --- # usdl-templates ## Role in the plugin This Skill owns two things and nothing else: 1. The bundled Element Templates — one full-section skeleton plus one single-element Template per Element kind across all four Sections of a USDL Spec. 2. The validate-against-Template workflow that every authoring Skill and Agent runs before it writes a new Element to a Section file. It is not user-invocable. There is no `/usdl-templates` command. The Skill is loaded indirectly: every section-spanning Skill lists it as a See-Also Reference, and every section-authoring Agent preloads it. ## See-Also References - `usdl-behaviour` — section-spanning Skill that loads behavior Templates from this Skill. - `usdl-topology` — section-spanning Skill that loads topology Templates from this Skill. - `usdl-interfaces` — section-spanning Skill that loads interfaces Templates from this Skill. - `usdl-composition` — section-spanning Skill that loads composition Templates from this Skill. - `usdl-bin` — wraps the `usdl` CLI; called by Agents to run `usdl validate` after Templates have been used to draft Elements. ## The four Template families Templates live under `assets/templates/

/*.xml`. Each Section has one `full.xml` skeleton and one Template per Element kind. All Templates are pure XML — no comments, no business logic, no placeholders beyond the shape of the Element. ### behaviour (`assets/templates/behavior/`) - `full.xml` — full behavior.xml skeleton (root `` with every Element kind represented). - `glossary-term.xml` — one glossary-term Element. - `actor.xml` — one actor Element. - `use-case.xml` — one use-case Element (goal, preconditions, main-flow, alternative-flow, postcondition, acceptance, events, rules, invariants, nfrs). - `event.xml` — one event Element. - `rule.xml` — one rule Element. - `invariant.xml` — one invariant Element. - `nfr.xml` — one nfr Element. ### topology (`assets/templates/topology/`) - `full.xml` — full topology.xml skeleton. - `unit.xml` — one unit Element (service, database, topic, worker, external-api shapes). - `communication.xml` — one communication Element with the six mandatory attributes plus optional backpressure and carries. - `environment.xml` — one environment Element. ### interfaces (`assets/templates/interfaces/`) - `full.xml` — full interfaces.xml skeleton. - `contract.xml` — one contract Element. - `operation.xml` — one operation Element (with schema-ref for the wire schema). - `channel.xml` — one channel Element. ### composition (`assets/templates/composition/`) - `full.xml` — full composition.xml skeleton. - `component.xml` — one component Element (intent, structure, logic, requires, constraints). - `constraint.xml` — one constraint Element (require / forbid children). - `call-flow.xml` — one call-flow Element. ## The validate-against-Template workflow This is the contract every authoring Skill and Agent must honour before writing a new Element to disk. It enforces `beh.rule.template-validated-element` and the invariant `inv.template-conformance`. 1. **Identify the Element kind.** From the active task and the target Section file, determine which Element kind is being drafted (e.g. "a new use-case in behavior.xml" → kind = `use-case`, section = `behavior`). 2. **Load the matching Template.** Open `assets/templates/

/.xml` and read it as the reference shape. If the file does not exist for that kind, the Element kind is not part of USDL and the draft is rejected. 3. **Check required attributes.** Every attribute the Template carries on its top-level Element node is required on the proposed Element. Attributes whose value the Template fills with a placeholder (e.g. ``, ``) must be replaced with a concrete value before validation passes. 4. **Check required children.** Every child element the Template lists once must appear at least once on the proposed Element. Children the Template lists multiple times (e.g. multiple `` lines in a ``) are repeatable; one instance is sufficient. 5. **Reject unknown attributes and children.** The Template is the closed shape. Any attribute or child element on the proposed Element that does not appear anywhere in the Template is a validation error — the draft must be revised, not extended. 6. **Hand back a clean Element.** Only an Element that passes steps 3–5 is allowed to be written to the Section file. If validation fails, the Skill or Agent surfaces the diagnostics to the Spec author and does not write. The Template is the floor, not the ceiling. Section-level schemas (loaded by `usdl validate` via `usdl-bin`) are the second gate; this Template gate runs first because it is per-Element and gives faster, more localised feedback. ## Loading model This Skill is intentionally invisible to the Spec author: - Every section-spanning Skill (`usdl-behaviour`, `usdl-topology`, `usdl-interfaces`, `usdl-composition`) names `usdl-templates` as a See-Also Reference in its own SKILL.md. The agent host loads it on demand when the section-spanning Skill is active and a Template lookup is needed. - Every section-authoring Agent (`usdl-behaviour-author`, `usdl-topology-author`, `usdl-interfaces-author`, `usdl-composition-author`) preloads `usdl-templates` in its AGENT.md frontmatter, so the Templates are available the moment the Agent starts drafting. If you are editing a section-spanning Skill or an Agent and `usdl-templates` is not listed as a See-Also Reference (or preloaded), that is a bug in the parent Skill or Agent — fix it there, not here. ## Project-supplied overrides A future iteration of the plugin will let a project drop a Template into its own `.claude/usdl-templates/

/.xml` to shadow the bundled one. For the MVP, the bundled Templates in this Skill are the floor and the only source. No override lookup is implemented yet. ## What this Skill does not do - It does not run `usdl validate`. That is `usdl-bin`'s job. - It does not drive an Interview Script. That is the section-spanning or element-targeted Skill's job. - It does not write to Section files. The authoring Skill or Agent writes; this Skill only certifies that the draft conforms to its Template. - It does not contain executable code. Template lookup and conformance checks are described here and performed by the host or by `usdl-bin`; no script lives in this Skill body.

usdl-templates

Install this skill

Comments