---
name: "convention-artefact-format"
type: convention
description: The house format for every canon artefact — the frontmatter schema and the section skeleton each artefact type follows (skill, task, routine, agent, operator, assistant, convention, core, workflow, playbook). Read before authoring or editing any SKILL.md so artefacts are written the same way, render correctly on the agents site, and are classified correctly by build-manifest.ts. Companion to core-operating-model, which defines what each os.Claude artefact type is and its naming prefix; this convention defines how the file is written, and how an artefact is renamed or deleted. Grown as the format solidifies.
license: CC BY-NC-SA 4.0
---

# Artefact format

Every canon artefact is a `SKILL.md` in its own directory under `.claude/skills/` (or `.claude/tasks/`). `core-operating-model` defines *what* each type is and its naming prefix; this convention defines *how the file is written* — the frontmatter schema and the body skeleton. The failure modes are silent: a missing `type:`, a `summary:` where `description:` is expected, or an ad-hoc section order makes the agents site mislabel an artefact or render it wrong. Follow this so the estate reads as one hand.

## Frontmatter — the schema

Three keys, required on every artefact, in this order:

```yaml
---
name: <prefix>-<slug>
type: skill | task | routine | agent | operator | assistant | convention | standard | core | workflow | playbook
description: >-
  One paragraph: what the artefact is, then when to read or trigger it.
  Folded scalar (>-), sentence case, British spelling, no trailing quotes.
  Maximum 1024 characters.
---
```

Rules:

* **`name`** — kebab-case, and the prefix must match `type` (`skill-`, `task-`, `routine-`, `agent-`, `operator-`, `assistant-`, `convention-`, `standard-`, `core-`, `workflow-`, `playbook-`). The directory name equals `name`. The `assistant-`, `core-` and `workflow-` prefixes are all on disk: `assistant-aide` (`type: assistant`), `core-fleet-roster` (`type: core`) and `workflow-content-engine` (`type: workflow`). `scripts/build-manifest.ts` classifies by the explicit `type:` field and falls back to the directory default only when the field is absent; its `VALID_TYPES` list includes `assistant`, `core` and `workflow` (read on `origin/main` at `67cc2db`, 2026-11-09). An unused prefix in this list breaks nothing; a renamed file the builder cannot classify does.
* **`type`** — always set it explicitly. `build-manifest.ts` defaults by directory when it is absent, which is how artefacts have been silently miscategorised; never rely on the default. A **duplicate frontmatter block** is the silent way this happens: a stray `name`/`description` header left above the real one is read as *the* frontmatter, so the real `type:` is never seen and the directory default takes over — the artefact installs cleanly and is miscategorised downstream. **Exactly one frontmatter block per file, `type:` present in it** (`skill-ops-retro` step 4b checks this at package time — worked cases APP-939, APP-903). (The `operator` type is new — `build-manifest.ts` gaining explicit support for it is a repo-native follow-up, tracked in the repo lane, not this convention.) **And a new `type:` value has two mirrors to teach, not one.** The first-sentence rule below already names both — `build-manifest.ts` in `claude-ops` and `build-content.ts` in `agents-site` — so the repo-native follow-up for a new type covers **both in one ticket**, and a ticket that reaches only one leaves the other to classify the value by whatever its own default is. The reported failure mode is the dangerous one: a fallback rather than an error, so the type ships under the wrong heading behind a green build with no warning anywhere. Where the two lists are brought together, an unrecognised `type:` is made to **fail the build naming the file and the value**, not to fall back — the same reason this bullet gives for never relying on the directory default, applied to the mirror instead of the frontmatter. What is **observed** is the pattern in the ticket record: APP-280, APP-303, APP-494, APP-407 and APP-1894 each name `build-manifest.ts` alone, five for five. What is **unverified** is every claim about what either file holds or does — the silent fallback included — because no repo is readable from the refine surface; the bullet above governs, and nothing here is to be restated as mechanism. (APP-2169, 2026-10-08.)
* **`description`** — the key is always `description`, never `summary`. It is what the agents site and the skill loader read. Write it as a folded scalar (`>-`) so long descriptions stay readable; short ones may sit on one line unquoted. Do not wrap it in quotes.
  * **Maximum 1024 characters, enforced at the save button.** A longer one is rejected outright — *"field 'description' in SKILL.md must be at most 1024 characters"* — and the package does not install. (Worked case: the 2026-07-15 drain packaged `skill-task-health.skill` with a 1084-character description; the save failed, and it was only recovered because the operator pasted the error back. Measured the same day, none of the 108 live artefacts exceeded the limit, which is why it had never been written down — but `skill-ops-retro`'s own description measures 1,010 characters / 1,016 bytes — headroom 14, not the 974 this example used to assert, and not the 1,016 an earlier pass reported, which was its byte count — so the headroom is thinner than it looks — APP-554.)
  * **The 1024 is a character count on the parsed YAML scalar — and that is also how to measure it.** The unit is characters: not bytes, and not the length of the line as it reads in the file. Three things therefore do not measure it. **`wc -c` returns bytes**, and an em dash is three of them. **`wc -m` returns bytes too on the surfaces this estate runs on**, because the locale is `LC_CTYPE="POSIX"` — so the obvious character-count flag is not one. And **the raw frontmatter line is not the unit**, because a quoted scalar with doubled apostrophes parses shorter than it reads: `convention-github`'s raw `description:` line is 1037 characters, the raw scalar after the key is exactly 1024 — which a raw-line check reads as at the ceiling with zero headroom — and the parsed scalar is 1019, headroom 5, the five characters being two enclosing quotes and three doubled apostrophes. So **the parsed scalar is the unit, not the raw line**, and the prescribed probe is one line: `python3 -c "import yaml,sys; d=yaml.safe_load(open(sys.argv[1]).read().split('---')[1]); print(len(d['description']))" <path>`. Report the character figure, the byte figure beside it, and the headroom against 1024 **on the character figure**. The error this corrects always ran one way — a byte count is never shorter than a character count — so a byte-based check was conservative and never permissive, and no package was ever rejected because of it; what it did was feed false headroom figures into the very warnings that decide whether a description can be touched at all. (Measured 2026-10-20 across all 174 live artefacts: none exceeds 1024 parsed characters, and the tightest five are `convention-github` 1019, `skill-task-health` 1016, `convention-storybook` 1015, `skill-design-parity` 1014 and `skill-ops-retro` 1010. APP-2414.)
  * **The ceiling is a prompt to tighten, not a wall to build up to.** The description's job is to carry the trigger phrases that make the artefact fire at the right moment, not to summarise the whole body — a description that needs more than 1024 characters is usually describing behaviour that belongs in the body. Cut to the trigger, don't pad to the limit.
  * **No angle-bracket placeholders or XML/HTML tags in the description** — the save validator rejects a `description` containing `<...>` ("SKILL.md description cannot contain XML tags") and the save silently fails. A placeholder like `operator-<venture>` reads as the tag `<venture>` and trips it. Write placeholders in prose or with a concrete example instead ("the lowercase operator-per-venture value, such as `operator-bara`"); angle-bracket placeholders are fine in the *body*, only the `description` field is validated. (Recurring — worked cases: 2026-07-01 and earlier.)
* **The first sentence is the artefact's public summary — write it to survive a naive split.** Both mirrors derive the one-line summary shown on the agents site from the **first sentence** of `description`, cutting at the first full stop. A full stop that is not a sentence end therefore ends the summary early and the page ships a fragment: a dotted product name (`os.Claude`, `bot.Trader`, `a1.OS`, `app.fitness`, `work.Hold`), a filename (`.env.local`), an abbreviation, a decimal or a version (`WCAG 2.2`). Nothing is clipped by a length cap when this happens — the ceilings (117 characters in `build-manifest.ts`, about 220 in `build-content.ts`) are not involved at all, and a reader who assumes a length problem looks in the wrong place. **So write the first sentence to end where its first full stop falls:** keep dotted names, filenames, abbreviations, decimals and versions out of it, and make it a complete, standalone one-line description of what the artefact is. Everything that needs those names goes in the second sentence onward, where the split cannot reach it. The rule is also what makes the description legible to a reader who only ever sees that one line. (Measured 2026-09-11 against the live store: 17 artefacts we own split early — among them `core-fleet-roster` ("Index of the os."), `operator-bottrader` ("The Operator of the bot."), `skill-content-truth-capture` ("Write a truth capture — a traceable tc.") and this convention itself before the fix below. The dominant cause is dotted product names, not abbreviations — APP-1311.)
* **Optional keys** are allowed only where a consumer reads them — `status: proposed` for an artefact not yet adopted (omit when active), and `license` where an artefact carries a licensing marker (see below). Anything else (`domain`, `surface`, `gating`, `downloadable`, `composed_of`) is not part of the schema; carry that information in the body, not the frontmatter. The careerOS-content set (`workflow-content-engine`, `skill-content-*`) predated this convention and carried `domain`, `surface`, `gating`, `downloadable`, `composed_of` and a `summary:` in place of `description:`; it was brought onto the schema by the 2026-07-21 drain (APP-606) and is no longer the standing exception it was.
  * **`license` is an adopted optional key; artefacts we own carry `CC BY-NC-SA 4.0`.** Canon is public-facing — the `claude-ops` mirror and the agents site render it — so a proprietary licence string on published content was incoherent. The standard value for every artefact we author is therefore `CC BY-NC-SA 4.0` (Attribution–NonCommercial–ShareAlike), which supersedes the earlier `Proprietary — Aled Pritchard workspace use.` string that ~20 artefacts still carry; the artefacts still asserting that superseded string are corrected in one bounded drain batch (frontmatter key only, nothing else touched), and from 2026-09-03 **every artefact we own carries the key from the moment it is next touched** — an authoring pass adds `license: CC BY-NC-SA 4.0` to any package it emits that lacks it (`skill-ops-retro` step 4b), so the silent remainder self-heals as it is edited rather than by a further sweep (Owner decision, delivery shape (c), 2026-09-03). The Anthropic-shipped skills (`docx`, `pdf`, `pptx`, `xlsx`, `web-artifacts-builder`) keep their own licence and are never edited. A top-level `LICENSE` (CC BY-NC-SA 4.0) is also declared in the public mirror repo — a repo-lane change, not this convention. (Owner decision 2026-08-12, APP-633; not legal advice — worth a lawyer's eye before it is load-bearing.)

**The three-key order is relative, not contiguous.** `name`, `type` and `description` are required and must appear in that sequence relative to one another; an **optional** key — `license`, `status` — may sit anywhere in the block, including between them. A file reading `name`, `type`, `license`, `description` satisfies the rule exactly as written: the three required keys are still in that order. The position of an optional key is a **consistency preference, never a defect, and never a hold condition** — it is not grounds to withhold a publish, fail a hygiene sweep, or return a package. **Preferred position for anything newly authored:** the three required keys first and in order, then the optional keys after `description`, `license` last, so the schema block above reads the same way in every file. That is a preference and is meant as one: a file carrying `license` before `description` is correct, and rewriting it to satisfy the preference is churn, not a fix. This is written down because the absence of a rule was read as a rule. (Worked case: the ops-sync run of 2026-09-08 withheld 25 of its 33 Claude-ahead publish candidates — 7 new artefacts and 18 edits — as broken frontmatter, on the ground that a set of artefacts carry `license:` before `description:`. Measured against the live store on 2026-09-09, 33 artefacts carry that position and nothing in this convention forbids it: the preference was unmet, the schema was not broken, and a day of drift accrued against the very gap the sweep exists to close — APP-633.)

**The order for anything newly authored, stated as a schema rather than as a preference:** `name`**,** `type`**,** `description`**, then the optional keys —** `status` **where it applies,** `license` **last.** That is the block above, written out, and it is canon for the **writing** side: a pass that authors or re-emits an artefact emits the keys in that sequence, and a pass that adds a missing `license` **appends it after** `description` rather than dropping it in beside `type:` (`skill-ops-retro` step 4b carries the same instruction at the point the package is built). It changes nothing on the **reading** side, and the paragraph above stands in full — a file already carrying `license` before `description` satisfies the schema, is not a defect, is not a hold condition, and is not rewritten for the preference alone. The reason to state the order at all is that leaving it unstated keeps producing the same drift, and the drift is growing: **observed against the live store on 2026-09-12 — 159 artefacts, 112 carrying** `license:`**, 45 of those carrying it before** `description:` (an observed figure from that day's sync, not a target and not a defect count; the 33 recorded above is the same measurement of 2026-09-09, three days and twelve artefacts earlier). Nothing sweeps those 45 and nothing should: an order is a property of what is next written, so the estate converges as each artefact is touched — the same self-healing shape the `license` key itself was given (Owner decision, delivery shape (c), 2026-09-03). What the explicit order buys is that the population stops growing, and that the next hygiene pass reading this section finds a stated rule instead of an absence it has to interpret — which is the misreading that cost a day of publish drift once already (APP-633).

**Why the save-time constraints live here.** Both known validator rules — the length ceiling and the XML-tag rejection — are enforced at the **save button**, which is the one step an authoring run cannot perform itself. A rejected package therefore fails on the *operator's* desk, after the run has already reported the change as made; if he doesn't paste the error back, the package is silently lost. So a constraint that only the save button enforces belongs in the artefact an authoring run reads *before* writing, which is this one. The two rules above are the ones observed; the schema is not published, so treat this list as known-and-growing rather than exhaustive, and add any new rejection here the first time it bites.

## Renaming or deleting an artefact — a canon operation, published second

A rename and a deletion are **content changes to canon**, not repo housekeeping, and they follow the same path as any other content edit: authored Claude-side, saved via the button, published to `claude-ops` afterwards by `skill-ops-sync`. This needs saying because publishing content Claude→repo is well covered while renaming and deleting had no named lane, so they got done wherever it was easiest — in the repo — which inverts the one-way mirror.

The failure it causes is quiet and permanent. A rename made repo-side leaves canon holding the old name and the repo the new one, and every parity run then reports a **phantom pair**: the same artefact once as "only in canon" and once as "only in repo". Nothing reconciles that automatically, and the divergence propagates into content, because artefacts on one side cite a name that does not exist on the other. (Worked case: the `cos-*` / `content-engine` rename, APP-389 commit `19107fd`, 2026-07-16, executed repo-side only; canon caught up on 2026-07-21 — APP-608.)

The sequence, in order:

1. **Rename** — produce the artefact under its new `name`, with the directory inside the package named the same, and save it. The store now holds both; the old-named entry is a separate artefact until removed.
2. **Sweep the cross-references in the same drain** — every artefact citing the old name is updated in the same batch, so nothing is left pointing at a dead name. This is a one-token edit per file, not a rewrite.
3. **Delete the old-named entry.** Deleting from the skills store is the **operator's** action in settings — it is neither a package nor a ticket, so an authoring run names it explicitly in its hand-off rather than assuming the rename replaced anything.
4. **Publish** — the next `skill-ops-sync` run carries the renamed canon to the repo and the phantom pair disappears from both directions.

A deletion follows steps 2–4 without step 1.

## Publishing an artefact a downstream repo reads at run time

A canon publish is not only a content change. Where a downstream repo reads canon from `claude-ops` **at build or test time**, publishing a new artefact mutates that repo's run-time inputs with no commit on the repo's own side. Its CI can therefore turn red on a change that never touched it, and the red presents itself as the current pull request's fault to whoever is standing in front of it — which costs the review leg its turns proving a negative before anyone looks at the real cause.

This convention already carries the shape for one case of it. A new `type:` value has **two mirrors to teach, not one** — `build-manifest.ts` in `claude-ops` and `build-content.ts` in `agents-site` — covered in **one ticket**, because a ticket that reaches only one leaves the other to classify the value by whatever its own default is (*Frontmatter — the schema*, the `type` bullet).

**Extend the same rule to a new `agent-*` publish.** An agent artefact is not only frontmatter the mirrors classify: the agents site expects a **mark**, **card media** and a **named fleet shape** for it. So a drain or publish pass that adds an `agent-*` artefact raises the paired `agents-site` ticket **in the same batch as the publish**, covering the mark generation, the card media and the roster expectation together — one ticket, the way a new type's two mirrors are one ticket. The pairing is the publish pass's to raise, because the publish is the act that changes the downstream inputs; nothing on the repo side can anticipate it.

**Pairing, not markless tolerance.** The alternative was considered and is not taken: letting the site's fleet tests accept a canon agent that has no mark yet, the way an artefact reference degrades to plain text. A roster expectation encodes a **stated fleet shape**, so a test relaxed to tolerate an unexpected agent stops asserting the one thing it exists to assert, and the shape then drifts silently instead of failing loudly. A degraded reference loses a link; a degraded roster loses the assertion. A missing mark is a gap to fill in the same batch, not a condition to design around.

(Worked case: a publish batch of 2026-10-20 added `agent-draft` to `claude-ops` with no paired `agents-site` ticket, and every `agents-site` pull request then failed its test step on agent marks and the roster — present on a pull request's base as well as its head, with a correct and merge-safe pull request sent to Blocked on an unrelated estate red. **Premise unverified — no repo or ref is readable from the authoring surface. Four premises, each flagged on its own and none implying the others:** (a) the count and content of the test failures; (b) the pull request and commit identifiers; (c) that `agents-site` CI reads canon from `claude-ops` `main` at run time; (d) the generator's stated roster-length guard and the fleet count it asserts. All four are the filing leg's report. The rule above rests on **none** of them: it follows from the two-mirrors rule this convention already states, applied to an artefact type whose downstream expectations are media and a roster rather than a classifier. APP-2518.)

## Body — the skeleton per type

The H1 and section set depend on the type. Use only the sections that carry weight; keep the order.

**skill** — a repeatable behaviour.

```
# <slug without prefix>          e.g. "# triage"
short framing line
## Trigger        — when this fires
## Behaviour      — the loop; use ### sub-steps or ### Pass N where multi-stage
## <domain ##s>   — any skill-specific sections, between Behaviour and Guardrails
## Guardrails     — the never/always boundaries
## Setup          — how it is scheduled or invoked, if relevant
```

**routine** — a sequenced execution (driver). Same skeleton as a skill (`# <slug>` → Trigger → Behaviour with numbered legs → any extras → Guardrails → Setup). A routine's instructions live in this `.md` as a `routine-*` canon artefact (saved and read from the skills store like any skill); its Cloud Routine config is a **static loader** that reads and follows it — see the wrapper/loader rules below. This `.md` is the canon and the render source for the agents site; the config holds no behaviour.

**task** — a scheduled job on the Cowork/connector surface. A **second-person prompt** ("You are …"), opening with its write-scope statement (what it may and may not change), then `## Step N` sections. No H1 slug is needed — the frontmatter `name` carries it. A `task-*` is one of two shapes (see the skill-vs-task-only rule below): a **thin loader** over a reusable `skill-*` that holds the behaviour, or a **self-contained** task where the behaviour is inherently the scheduled job. Either way the `.md` is the canon and render source; the Cowork scheduled-task config is a static loader, not the second-person prompt itself.

**agent** — a functional-agent profile. No H1; open with `## <Name> — *role*`, then bold-led fields in this order: **Essence**, **Mission**, **Objectives**, **Goals**, **Remit**, **Boundaries**, **Surface**, **Label**, **Composition**, **Relationships**, **Accountability**. Close with a `---` rule.

**operator** — a vertical-operator profile (the Layer 3 sibling of an agent; see `core-operating-model`). No H1; open with `## <Name> — Operator, <vertical>`, then bold-led fields in this order: **Mission** (the one sentence — you own this vertical to the best outcome within mandate), **Mandate** (the goal source, and the name of the `<vertical>.mandate` document that holds timeframe · envelope · spend-to-date — the profile names the document and never states the figures, APP-1064), **Powers** (what it may direct and spend), **Accountabilities** (the vertical's outcome and KPIs vs target), **Boundaries** (the three hard anchors it escalates to the Owner — strategic pivot, budget-envelope breach, goal-set change — and the three standing grants of `skill-operating-loop` step 5), **Does not** (execute functional work itself; duplicate Atlas or Relay), **Surface**, **State sources** (required: the dashboard artefact id where one exists — or an explicit "none" with the reason, such as a KPI tree still unset — the Linear board scope as team · projects in scope · initiative, the mandate document, and the surface each source is reachable from; `skill-operating-loop` step 1 reads the dashboard where named and the board scope otherwise, so a profile that declares neither fails this checklist — APP-980), **Label** (the lowercase `operator-<venture>` value), **Composition** (the fleet and skills it commands), **Relationships** (the Owner above, peer operators alongside), **Reporting** (the concrete surfaces by id — the initiative that carries the weekly headline, the projects whose daily updates it reads, the `<vertical>.standup` and `<vertical>.owner-session-agenda` documents; this field specialises `skill-operating-loop` step 7 and may never contradict it — APP-1002). Close with a `---` rule. The template lives here as this skeleton — there is no `agent-operator` template artefact.

**convention** — a shared standard. `# <Title>` → prose `##` sections → an optional `## Quick checklist` at the end where a pre-flight list helps. May open with the canonical-copy note (below).

**standard** — a quality bar (a Layer 5 atomic rule you pass or fail, distinct from a convention — see `core-operating-model`). Same skeleton as a convention: `# <Title>` → prose `##` sections. First instances: `standard-prioritisation`, `standard-design-system`. (`build-manifest.ts` gaining explicit support for the type is a repo-native follow-up in the repo lane, not this convention.)

**core / workflow / playbook** — reference and composition docs: `# <Title>` then prose `##` sections. A workflow authors its diagram as Mermaid.

## The wrapper/loader model for routines and tasks

A `routine-*` / `task-*` artefact is the **single source of truth**; the Cloud Routine / Cowork config that runs it is a **static loader** holding no instructions of its own. This is the wrapper model (`core-operating-model`, Layer 2): it removes the second source of truth Claude cannot edit, so canon and config can no longer drift.

* **Loader line.** Every scheduled-task / routine config is reduced to the canonical loader line defined in `core-operating-model` (*The loader line — one form*), pointing at the artefact by path:

  `Read the canon artefact <artefact-name> (the saved skill of that name; locally at .claude/skills/<artefact-name>/SKILL.md) and follow it verbatim.`

  All three surfaces use this one form and resolve the half they can: a local Cowork task resolves either; a **cloud Cowork task** resolves the **name** (its skills are synced by name and it has no `.claude/skills/` at its working directory — it tracks canon live, no publish lag); a **Cloud Routine** reads canon from the cloned `claude-ops` repo (the save → ops-sync publish → clone path) but **does not resolve this line's path there**: the repo's canon source moved out of `.claude/` on 2026-09-14 to `canon/skills/` and, for `task-*`, `canon/tasks/`, so `.claude/skills/` is a dead end on that surface rather than a synonym for it (`skill-ops-sync`, *Placement map*, is the account; repo-side premise **unverified** — no repo is readable from the authoring surface). The path half above is still correct and is **not** rewritten — it resolves on a **local** surface, where the account's skills are synced to that path — but it is **not** what makes a config portable onto a Cloud Routine, and quoting it into a dispatch prompt as a claude-ops repo path is how the stale path has been spreading (three legs in one day, 2026-10-21, reported: APP-2506; the repo `CLAUDE.md` half is APP-2509). Name first is what carries across all three (APP-1101); where a Cloud Routine genuinely needs a repo path it is `canon/skills/<artefact-name>/SKILL.md`, or `canon/tasks/<artefact-name>/SKILL.md` for a `task-*`. `core-operating-model` (*The loader line — one form*) remains the one place the form is stated, and carries the same correction. The loader is frozen after a one-time edit; all behaviour changes are made in the artefact. Where the two documents ever disagree on the wording, `core-operating-model` wins — it is the one place the form is stated.

  **An artefact cites the form; it does not re-type it.** A `task-*` / `routine-*` artefact's § Setup names the loader by reference — "the canonical loader line in `core-operating-model` (*The loader line — one form*)" — and quotes nothing. Where a quote genuinely helps a reader who is about to paste into a settings box, it is the dual form verbatim with only the artefact name substituted, both standing clauses included, and never a shortened variant. The reason is the same one that puts the form in `core-operating-model` in the first place: a form copied into thirty artefacts drifts thirty ways, and a wrong copy fails **silently at config time** — the schedule reads nothing, the job never runs, and every other check stays green because the artefact is present and valid at its real path. (Worked case: APP-721 recorded this class on 2026-07-29, naming `task-cycle-planning` and `task-daily-report`, and was closed Done on 2026-08-10 with neither corrected. Measured against the live store on 2026-09-09, five `task-*` artefacts quote a loader line in their own § Setup and all five carry the retired path-only dialect, none the canonical dual form; `task-owner-standup` — authored *after* APP-721 closed, and due to be scheduled weekdays at 08:30 — reproduced the defect exactly. A note closed without its sweep leaves the class being newly created, not merely lingering — APP-1191.)

  **The same form governs a thin loader's body read.** A thin `task-*` whose body tells the run to read its skill uses the dual form too, not a bare path: `Read the canon artefact <skill-name> (the saved skill of that name; locally at .claude/skills/<skill-name>/SKILL.md) and follow it verbatim.` A bare-path body read has the identical failure as a bare-path config on a cloud Cowork task, which has no `.claude/skills/` at its working directory and resolves only by name (APP-1101) — and since the 2026-09-03 migration that is where the connector-only layer runs (APP-1100). `task-goal-review`, `task-pulse-refine` and `task-pulse-retro` are the form as it should read.

* **Every live schedule has a canon artefact.** There is no "the skill's § Setup names its deployment" shape — see `core-operating-model` (*Every live schedule has a canon artefact*). A schedule whose config points straight at a `skill-*` has no artefact for the agents site to render, nothing for `skill-ops-sync` to diff, and nothing for `skill-task-health` Pass B to enumerate.

* **Skill-vs-task-only rule.** A scheduled job splits into two artefacts **only when its behaviour has genuine independent (ad-hoc) reuse**:
  * `skill-*` **+ thin** `task-*` — the behaviour is reusable / invocable on its own, so it lives in `skill-*` and the `task-*` is a thin loader (triage, plan, coordinate, ops-sync, pipeline-qualify, pulse-retro→skill-ops-retro, operating-loop→task-bara-operator-loop, health→skill-task-health, optimisation-review→skill-optimisation-review). `task-pipeline-sweep` is a variant: a `task-*` orchestrator over the reusable `skill-pipeline-sweep` engine.
  * `task-*` **only (no skill)** — the behaviour is *inherently the scheduled job* with no independent use, so it is self-contained in the `task-*` with no `skill-*` (`task-daily-report`, `task-pipeline-graduation`).
  * The test is on **nature** (`core-operating-model`, Layer 1; Owner decision APP-709, 2026-09-03): a `skill-*` is the ***how*** — a separable, reusable craft a process invokes; a `task-*`/`routine-*` is the ***process*** — "do this", the sequence run on a trigger. Does this job have a separable how? Yes → `skill-*` + thin `task-*`. Is it itself just the sequence? → `task-*` only. ("Would you ever run it ad hoc?" is a useful proxy, no longer the rule.) The test decides *where the behaviour lives*, never *whether a* `task-*` *exists* — a scheduled job always has one. The prefix follows the nature: a `skill-*` that is really a process is re-placed as a task or routine **when it is next touched**, never in a bulk rename.

* **Authoring a thin `task-*` loader.** Its body is a short second-person prompt that names the skill to read and follow, the mode/arguments if any, any extra conventions to load first, the run context (connector, propose-only boundaries), and a one-line "to change behaviour, edit the skill, not this file" note. It carries no behaviour beyond sequencing.

## The canonical-copy note

Where an artefact also has a downstream copy (a Linear doc, the published repo), open the body with one blockquote line stating which copy is canon, so an editor never edits the mirror by mistake. Example:

> *This is the canonical copy. The repo copy is a downstream mirror — edit here, let ops-sync publish.*

## Evidence strings — a phrase cited from canon names its artefact

A pass that proves a canon change by quoting a distinctive new phrase writes that phrase as **`Evidence string in canon: "<phrase>" (<artefact>)`** — the phrase in quotes, then the artefact that carries it, in parentheses. `skill-ops-retro` mandates the line and fixes where it is written; this convention fixes its **form**, because the artefact name is the part that goes missing and the part a later grep needs.

The failure is a bare grep against the wrong file. Where a close names two artefacts and then lists two evidence strings with **no binding between them**, a verification pass has to guess which phrase belongs to which artefact: it greps one against the other, gets **0**, and reports a landed change as unlanded. A zero from the wrong file is indistinguishable from a zero from a missing phrase, which is why the binding is written at the moment the phrase is written rather than inferred afterwards. **One phrase, one artefact, one line** — a phrase that genuinely lands in two artefacts gets two lines, never one line with two names. The parenthesis is already the house form in practice: the closes on APP-2472, APP-2434 and APP-2437's 2026-10-19 close each carry it ad hoc, so this writes down what three closes already do. (Worked case: a step-1a verification pass hit a bare grep **0** on exactly that shape and had to read both files to resolve it — APP-2414, 2026-10-20.)

## Tone

All artefact prose follows `cos.tov`: calm, precise, sentence case, British spelling, no exclamation marks, outcome before adjective.

## Quick checklist before saving an artefact

- [ ] Frontmatter has `name`, `type`, `description` in that **relative** order? (An optional `license:` or `status:` may sit anywhere in the block — its position is a preference, not a defect, and never a reason to hold a publish.)
- [ ] `name` prefix matches `type`, and the directory name equals `name`?
- [ ] `type` set explicitly (not relying on the directory default)?
- [ ] Exactly one frontmatter block — no stray duplicate `name`/`description` header above the real one?
- [ ] Description key is `description` (not `summary`), folded, unquoted, sentence case?
- [ ] Description **at most 1024 characters**? (Counted, not eyeballed — the save is rejected outright, and the failure lands on the operator after the run has reported the change made.)
- [ ] Description free of angle-bracket placeholders / XML tags (`<...>`)? (The save validator rejects them — use a concrete example, not a `<placeholder>`.)
- [ ] Does the **first sentence** of the description stand alone and end at its own first full stop — no dotted product name (`os.Claude`, `bot.Trader`), filename, abbreviation, decimal or version inside it? (It is what the agents site publishes as the artefact's one-line summary; a stray full stop ships a fragment — APP-1311.)
- [ ] No off-schema frontmatter keys (info that belongs in the body)?
- [ ] Body skeleton matches the type, in the right order? (agent vs operator — pick the right L3 skeleton.)
- [ ] For a `routine-*` / `task-*`: behaviour lives in the artefact, config is the one-line loader, the artefact exists at all, and the skill-vs-task-only split is right?
- [ ] Canonical-copy note present where a downstream mirror exists?
- [ ] Renaming or deleting? (Saved canon-side first, cross-references swept in the same batch, the old-named entry named for the operator to delete — never done repo-side.)
- [ ] Tone clean per `cos.tov`?
