--- name: convention-artefact-format type: convention description: >- The house format for every os.Claude canon artefact — the frontmatter schema and the section skeleton each artefact type follows (skill, task, routine, agent, operator, 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 type is and its naming prefix; this convention defines how the file is written. Grown as the format solidifies. --- # 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: - type: skill | task | routine | agent | operator | convention | 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. --- ``` Rules: * **`name`** — kebab-case, and the prefix must match `type` (`skill-`, `task-`, `routine-`, `agent-`, `operator-`, `convention-`, `core-`, `workflow-`, `playbook-`). The directory name equals `name`. * **`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. (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.) * **`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. **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-` reads as the tag `` 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.) * **Optional keys** are allowed only where a consumer reads them — currently `status: proposed` for an artefact not yet adopted (omit when active). Anything else (`domain`, `surface`, `gating`, `downloadable`, `composed_of`, `license`) is not part of the schema; carry that information in the body, not the frontmatter. The careerOS-content set (`cos-*`, `content-engine`) predates this convention and is the conformance backlog, not the model to copy. ## 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. ``` # e.g. "# triage" short framing line ## Trigger — when this fires ## Behaviour — the loop; use ### sub-steps or ### Pass N where multi-stage ## — 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 (`# ` → 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 `## — *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 `## — Operator, `, then bold-led fields in this order: **Mission** (the one sentence — you own this vertical to the best outcome within mandate), **Mandate** (goal · timeframe · resource/budget envelope, per instance), **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), **Does not** (execute functional work itself; duplicate Atlas or Relay), **Surface**, **Label** (the lowercase `operator-` value), **Composition** (the fleet and skills it commands), **Relationships** (the Owner above, peer operators alongside), **Reporting** (dashboard / status / initiative it reports to). Close with a `---` rule. The template lives here as this skeleton — there is no `agent-operator` template artefact. **convention** — a shared standard. `# ` → prose `##` sections → an optional `## Quick checklist` at the end where a pre-flight list helps. May open with the canonical-copy note (below). **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 one line, pointing at the artefact: `Read .claude/skills/<artefact-name>/SKILL.md and follow it verbatim.` Both surfaces use this form — Cowork tasks resolve it from the skill store at run time (so they track canon live, no publish lag); Cloud Routines resolve it from the cloned `claude-ops` repo (so they flow through the save → ops-sync publish → clone path). The loader is frozen after a one-time edit; all behaviour changes are made in the artefact. * **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). `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: would you ever run this behaviour ad hoc, outside the schedule? Yes → `skill-*` + thin `task-*`. No → `task-*` only. * **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.* ## 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 order? - [ ] `name` prefix matches `type`, and the directory name equals `name`? - [ ] `type` set explicitly (not relying on the directory default)? - [ ] Description key is `description` (not `summary`), folded, unquoted, sentence case? - [ ] Description free of angle-bracket placeholders / XML tags (`<...>`)? (The save validator rejects them — use a concrete example, not a `<placeholder>`.) - [ ] 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, and the skill-vs-task-only split is right? - [ ] Canonical-copy note present where a downstream mirror exists? - [ ] Tone clean per `cos.tov`?