---
issue_key: SKILL-22
feature_name: collapse-skill-md-to-shared-ceremony
feature_size: LARGE
status: In Progress
created: 2026-04-19
depends_on: SKILL-21 (shell+content split — open at PR #60)
---

# SKILL-22 — Collapse SKILL.md to the minimum shape via a shared ceremony sibling

## Problem

After SKILL-21 split `content.md` out of `SKILL.md`, a structural analysis of the 26
governed `SKILL.md` files in the repo showed that ~70% of each platform-pack
`SKILL.md` is still framework-generated boilerplate, not author knowledge:

- **~39% is byte-identical across all 11 platform-pack code-review
  specialists.** The four H2 sections `## Execution`, `## Execution Mode Reporting`,
  `## Telemetry Ceremony Hooks`, and `## Inputs` have exactly one unique hash
  each across the 11 files. They are pure template with zero per-skill
  variation.
- **~18% is parameterized boilerplate.** `## Project Overrides` is structurally
  identical across all 26 `SKILL.md` files (13 platform-pack + 13 horizontal)
  modulo a single slug reference: `## bill-<skill-slug>`.
- **~23% is shape-descriptor prose.** `## Description`, `## Specialist Scope`,
  and `## Outputs Contract` are each rendered per-skill but the bodies are
  short, template-y, and already produced by the scaffolder's `infer_*`
  helpers. Authors are not expected to write or edit them.

**Observed adoption symptom:** opening any `platform-packs/<slug>/code-review/<skill>/SKILL.md`
after SKILL-21 still drops the reader into 60+ lines of framework ceremony
before they reach anything a skill author would recognise as their own work.
The hygiene test added in SKILL-21 pass 2 demonstrates that `content.md` is
now author-owned end-to-end — but `SKILL.md` is not yet a readable artifact
for a skill author either. It is a machine-generated shell that is generated
over and over in full.

This ticket operationalizes the principle **minimum duplication, maximum
reuse**: every byte that is shared between two governed skills should live
in one place and be referenced, not copy-pasted. Every byte that is per-skill
but mechanically derivable from frontmatter + manifest should be rendered by
the scaffolder, not hand-written.

## Why now

- **SKILL-21 has landed (PR #60 in review).** The file split is stable; the
  scaffolder, validator, loader, migration script, and hygiene test all
  understand the shell/content boundary. Adding the collapse now is cheap
  because every SKILL.md is already being regenerated by `skill-bill upgrade`
  on template drift. There is no additional churn cost.
- **skill-bill has not shipped a real release yet.** There is no external
  caller whose v1.0 packs would break if we reshape the contract freely.
  Treating the SKILL-21+SKILL-22 end state as the actual 1.0 shape — and
  freezing the contract version accordingly — is the cheapest correct
  move. SKILL-21's 1.0→1.1 bump was premature and should be reverted as part
  of this ticket.
- **The maximum-reuse design is obvious once measured.** The structural
  analysis above is concrete: 39% pure dupe, 18% parameterized dupe, 23%
  template-rendered. This ticket turns those percentages into zero.

## Context (what a new-session implementer needs to know)

### What skill-bill is today (post-SKILL-21)

- **Governed shell + content architecture.** Every platform-pack skill
  carries a `SKILL.md` (shell) and a sibling `content.md` (author-owned
  body). `## Execution` in `SKILL.md` points at `content.md`. `content.md`
  has no required structure; hygiene test forbids framework ceremony there.
- **Built-in packs.** Only `kotlin` and `kmp` ship as first-party reference
  packs.
- **Shell contract version.** `SHELL_CONTRACT_VERSION = "1.1"` in
  `skill_bill/constants.py`. Packs declare `contract_version: "1.1"` in
  `platform.yaml`. SKILL-21 shipped the 1.0→1.1 bump and a migration script
  (`scripts/migrate_to_content_md.py`) with a loud-fail message pointing at
  it.
- **Scaffolder.** `skill_bill/scaffold_template.py` renders a SKILL.md body
  composed of: frontmatter + `## Project Overrides` + required H2 sections
  + the new `## Execution`, `## Execution Mode Reporting`, `## Telemetry
  Ceremony Hooks`. All rendered deterministically from
  `ScaffoldTemplateContext` plus per-kind helpers (`infer_skill_description`,
  `render_specialist_scope_section`, etc.).
- **Validator / loader.** `skill_bill/shell_content_contract.py` is the
  authority. `REQUIRED_CONTENT_SECTIONS` for code-review:
  `## Description`, `## Specialist Scope`, `## Inputs`, `## Outputs Contract`,
  `## Execution`, `## Execution Mode Reporting`, `## Telemetry Ceremony Hooks`.
  `REQUIRED_QUALITY_CHECK_SECTIONS` is the same minus Specialist Scope and
  plus `## Execution Steps` + `## Fix Strategy`.
- **Migration script.** `scripts/migrate_to_content_md.py` exists purely to
  migrate v1.0 packs into the v1.1 shape. No external caller has ever used
  it (pre-release). It is effectively dead code.

### The three collapses

**Collapse 1 — shared-ceremony sibling.** The four byte-identical bodies
(`## Execution Mode Reporting`, `## Telemetry Ceremony Hooks`, `## Inputs`,
and `## Project Overrides`) move to one canonical file:
`orchestration/shell-content-contract/shell-ceremony.md`. This file is
symlinked into every governed skill directory. `SKILL.md` replaces all four
sections with a single `## Ceremony` section whose body is byte-identical:
`Follow the shell ceremony in [shell-ceremony.md](shell-ceremony.md).`

`## Project Overrides`'s body is rewritten to remove the per-skill slug:

```markdown
## Project Overrides

If `.agents/skill-overrides.md` exists in the project root and contains a
section whose heading matches this skill's `name` from the frontmatter, read
that section and apply it as the highest-priority instruction for this skill.
The matching section may refine or replace parts of the default workflow.

If an `AGENTS.md` file exists in the project root, apply it as project-wide
guidance.

Precedence: matching `.agents/skill-overrides.md` section > `AGENTS.md` >
built-in defaults.
```

This removes the slug-substitution parameter entirely.

**Collapse 2 — auto-rendered `## Descriptor`.** `## Description`,
`## Specialist Scope`, and `## Outputs Contract` collapse into a single
required `## Descriptor` H2 whose body is rendered fully from:

- Frontmatter `name` + `description`
- A new manifest field `specialist_area` (code-review) or
  `check_area` (quality-check), declared on the skill entry in
  `platform.yaml`.

The scaffolder owns the body completely. Authors never edit it. Example
rendered body for a code-review specialist:

```markdown
## Descriptor

`bill-kotlin-code-review-architecture` is a specialist reviewer in the
`kotlin` platform pack, scoped to the `architecture` area. It reviews Kotlin
changes under this area and returns a structured risk register, action
items, and a verdict. Author knowledge for this specialist lives in
[content.md](content.md).
```

For quality-check skills the template is analogous, substituting the
quality-check shape vocabulary.

**Collapse 3 — freeze contract at 1.0 retroactively.** `SHELL_CONTRACT_VERSION`
returns to `"1.0"`. PR #60's 1.0→1.1 code path (`ContractVersionMismatchError`'s
migration-hint text, loud-fail precedence test pairs, the migration script)
is removed. The reshape is defined as "the 1.0 shape" once. `TEMPLATE_VERSION`
continues to exist and bump per template change; it drives `skill-bill
upgrade`'s drift detection and is orthogonal to the contract version.

### Target SKILL.md shape after SKILL-22

```markdown
---
name: bill-kotlin-code-review-architecture
description: <one-liner>
shell_contract_version: 1.0
template_version: 2026.04.xx
specialist_area: architecture
---

## Descriptor

<auto-rendered body — the ONE unique section per skill>

## Execution

Follow the instructions in [content.md](content.md).

## Ceremony

Follow the shell ceremony in [shell-ceremony.md](shell-ceremony.md).
```

~15 lines. Three H2s. Zero author-written prose.

### What stays the same

- `content.md` remains the author-owned body and retains the hygiene test
  from SKILL-21 pass 2.
- `## Execution` stays as a required H2; points at `content.md`.
- Loud-fail discovery rules and named exceptions remain; precedence order is
  preserved.
- Sidecar symlinks for `stack-routing.md`, `review-orchestrator.md`,
  `review-delegation.md`, `telemetry-contract.md`, etc. continue to work
  unchanged. `shell-ceremony.md` joins them as a new sibling.
- Multi-agent install/sync: `install.sh` symlinks the skill directory, so
  the new `shell-ceremony.md` sibling is auto-visible to every runtime.
- Telemetry schema, MCP event shape, routing playbooks, add-on semantics.
- Horizontal skills in `skills/bill-*` keep their unique structures. They
  adopt `shell-ceremony.md` for `## Project Overrides` dedupe but do not
  adopt the 3-H2 minimum shape.

### What changes

- Shell contract required H2 set shrinks dramatically:
  - Code-review: 7 → 3 (`## Descriptor`, `## Execution`, `## Ceremony`).
  - Quality-check: 5 → 3 (same three).
- `SHELL_CONTRACT_VERSION` returns to `"1.0"`; SKILL-21's 1.1 bump is
  reverted.
- Every governed skill directory gets a new `shell-ceremony.md` symlink.
- Manifest schema adds optional `specialist_area` / `check_area` per skill
  entry.
- Scaffolder's section-renderer set changes: `render_descriptor` replaces
  three renderers; `render_ceremony` is new; three renderers
  (`render_execution_mode_reporting`, `render_telemetry_ceremony_hooks`,
  `render_inputs`) are deleted (their bodies move to `shell-ceremony.md`).
- `scripts/migrate_to_content_md.py` is deleted.
- `ContractVersionMismatchError`'s migration-hint text is removed. The
  exception survives as a generic loud-fail guard.

## Acceptance criteria

1. **Shell contract stays at 1.0.** `SHELL_CONTRACT_VERSION` in
   `skill_bill/constants.py` is `"1.0"`. Every in-repo `platform.yaml`
   declares `contract_version: "1.0"`. `orchestration/shell-content-contract/PLAYBOOK.md`
   documents the 1.0 shape as the stable pre-release shape. `ContractVersionMismatchError`
   exists but no longer mentions the migration script in its message.

2. **Required H2 set collapses.** `REQUIRED_CONTENT_SECTIONS` and
   `REQUIRED_QUALITY_CHECK_SECTIONS` in `skill_bill/shell_content_contract.py`
   become `("## Descriptor", "## Execution", "## Ceremony")`. The tuple is
   byte-identical between the two families (code-review and quality-check
   now share the same H2 set; specialization happens inside the Descriptor
   body).

3. **Canonical `## Execution` body** (byte-identical, from a stored
   constant):
   ```
   ## Execution

   Follow the instructions in [content.md](content.md).
   ```

4. **Canonical `## Ceremony` body** (byte-identical, from a stored
   constant):
   ```
   ## Ceremony

   Follow the shell ceremony in [shell-ceremony.md](shell-ceremony.md).
   ```

5. **`## Descriptor` is fully auto-rendered.** `skill_bill/scaffold_template.py`
   exposes `render_descriptor(ctx)` that produces the body from:
   - `ctx.name` (frontmatter `name`)
   - `ctx.description` (frontmatter `description`)
   - `ctx.specialist_area` or `ctx.check_area` (from manifest)
   - The pack slug (derived from the skill's path)
   Output is deterministic. No author-edited path. `InvalidDescriptorSectionError`
   is raised by the loader if the rendered body does not match what the
   current template would produce.

6. **New sibling file `shell-ceremony.md`.** One canonical source at
   `orchestration/shell-content-contract/shell-ceremony.md`. Contains the
   four section bodies that left `SKILL.md`: `## Project Overrides`,
   `## Inputs`, `## Execution Mode Reporting`, `## Telemetry Ceremony Hooks`.
   `## Project Overrides` body is rewritten generically (reads `name` from
   the reader's own SKILL.md frontmatter; no per-skill slug substitution).

7. **Every governed skill directory symlinks `shell-ceremony.md`.** For
   platform-pack skills under `platform-packs/*/code-review/*/` and
   `platform-packs/*/quality-check/*/`, the loader requires the
   `shell-ceremony.md` sibling. Missing sibling raises a new
   `MissingShellCeremonyFileError`. Sidecar plumbing in
   `scripts/skill_repo_contracts.py` and the scaffolder's
   `_stage_sidecar_symlinks_for_skill` register `shell-ceremony.md` as a
   required supporting file for governed skill kinds that have a SKILL.md.

8. **Horizontal skills (`skills/bill-*`) adopt `shell-ceremony.md` for
   `## Project Overrides` dedupe.** They keep their unique structures but
   their `## Project Overrides` block collapses to the same one-line
   reference: `Follow the shell ceremony in [shell-ceremony.md](shell-ceremony.md).`
   The horizontal-skill SKILL.md template is updated; existing horizontal
   skills are regenerated via `skill-bill upgrade`.

9. **Manifest schema: new `specialist_area` / `check_area` fields.**
   `platform.yaml` schema gains optional per-skill fields:
   - Under `code_review.skills[*]`: `specialist_area: <area-slug>`
   - Under `quality_check.skills[*]`: `check_area: <area-slug>` (or no area
     for the single quality-check skill — then an `infer_check_area` default
     applies).
   `orchestration/shell-content-contract/SCAFFOLD_PAYLOAD.md` documents the
   fields.

10. **Scaffolder writes shell-ceremony.md symlink atomically.** When
    scaffolding any governed skill kind that has a SKILL.md, the
    transaction includes the `shell-ceremony.md` symlink. Rollback removes
    both the SKILL.md, content.md, and shell-ceremony.md symlink.

11. **`skill-bill upgrade` regenerates SKILL.md to the new shape.** Every
    governed skill with stale `template_version` is regenerated. Never
    touches `content.md`. Never touches `shell-ceremony.md` (it is the
    canonical source, symlinked).

12. **Validator precedence order.** The loader's failure-precedence chain
    preserves the SKILL-21 order and extends to cover the new sibling:
    contract-version → manifest-schema → content-file → content-section →
    execution-link → content-sibling → ceremony-sibling → descriptor-body.
    Documented in both `PLAYBOOK.md` and the loader docstring.

13. **Migration script deleted.** `scripts/migrate_to_content_md.py` is
    removed. `tests/test_migration.py` is removed. No pre-release v1.0-to-v1.1
    migration path exists; the 1.0 shape is the only shape. The hygiene test
    (`tests/test_content_md_hygiene.py`) stays.

14. **`CEREMONY_FREE_FORM_H2S` blacklist survives.** The SKILL-21 pass 2
    blacklist in `skill_bill/shell_content_contract.py` continues to gate
    what may appear in `content.md`. The list is extended if the v1.0 shape
    introduces any new framework H2 names that should never be in content.

15. **Tests cover the new surface.**
    - `tests/test_scaffold.py` — scaffolder writes SKILL.md with only the
      three required H2s; scaffold also stages `shell-ceremony.md` symlink;
      rollback removes all three files; `render_descriptor` is deterministic
      for fixed inputs.
    - `tests/test_shell_content_contract.py` — loader accepts the new
      required H2 set; missing `shell-ceremony.md` sibling raises
      `MissingShellCeremonyFileError`; malformed `## Descriptor` body raises
      `InvalidDescriptorSectionError`; precedence is enforced in the
      documented order.
    - `tests/test_content_md_hygiene.py` — continues to pass (the blacklist
      still rejects any ceremony H2 in `content.md`).
    - `tests/test_cli.py` — `skill-bill upgrade` regenerates SKILL.md to the
      3-H2 shape; never touches `content.md` or `shell-ceremony.md`.
    - `tests/test_install_script.py` — `install.sh` symlinks the directory,
      so `shell-ceremony.md` is auto-synced (no per-file install change
      needed).

16. **Full repo reshape in the same PR.** Every governed SKILL.md in-repo
    is regenerated to the 3-H2 shape. Every governed skill directory gets
    a `shell-ceremony.md` symlink. Every `platform.yaml` declares
    `contract_version: "1.0"` and, where applicable,
    `specialist_area` / `check_area` per skill entry. Horizontal skills'
    SKILL.md files are also regenerated for the new `## Project Overrides`
    line.

17. **Docs updated.**
    - `orchestration/shell-content-contract/PLAYBOOK.md` rewrites the v1.0
      section to describe the 3-H2 shape, the `shell-ceremony.md` sibling,
      and the `## Descriptor` auto-render contract. The v1.1 narrative is
      removed or clearly marked "pre-release historical".
    - `orchestration/shell-content-contract/SCAFFOLD_PAYLOAD.md` documents
      the new `specialist_area` / `check_area` manifest fields.
    - `README.md` "Authoring a skill" updates the before/after example to
      show the 3-H2 shape and the generic `## Project Overrides`.
    - `AGENTS.md` / `CLAUDE.md` note the final shape.
    - `docs/getting-started-for-teams.md` walkthrough matches the reshape.

18. **MCP tool surface unchanged.** `skill_bill/mcp_server.py` is not
    touched. Telemetry schema, event shape, and learnings pipeline are
    unchanged.

19. **Validation commands pass.**
    `.venv/bin/python3 -m unittest discover -s tests`,
    `npx --yes agnix --strict .`, and
    `.venv/bin/python3 scripts/validate_agent_configs.py` all pass post-reshape.

20. **No agent behavior change.** A controlled `/bill-kotlin-code-review`
    diff run produces materially identical specialist selection, risk
    register shape, and findings compared to pre-SKILL-22 output. The PR
    description captures the comparison (same structure as SKILL-21 AC 20).

## Non-goals

- **Shipping a 1.1 or 2.0 contract.** Pre-release the contract stays at
  1.0 through this reshape. Post-release future reshapes will bump.
- **Changing `content.md` semantics.** Author-owned body, hygiene-guarded,
  free-form. This ticket does not re-enter the content.md design.
- **MCP / telemetry / learnings / routing / add-on changes.** Out of scope.
- **New skill kinds.** The four kinds from SKILL-15 are unchanged.
- **Renaming or deleting built-in skills.** The kotlin + kmp built-in set is
  unchanged in count and slug.
- **Introducing per-skill template overrides.** The Descriptor template is
  family-wide; authors who want a bespoke description put it in `content.md`,
  not the SKILL.md shell.
- **A `content.md` linter.** Still out of scope.
- **A new contract-migration script.** Since v1.0 is the only shape pre-release,
  the migration script is deleted, not rewritten.

## Open questions to resolve in planning

1. **`## Ceremony` vs keeping the old section names.** Option (a): replace
   all four with one `## Ceremony` H2 pointing at `shell-ceremony.md`. Option
   (b): keep the four H2 names in `SKILL.md` with each body a one-line
   pointer at `shell-ceremony.md`. Recommend (a) — fewer required H2s is
   cleaner; the four old names survive inside `shell-ceremony.md`.

2. **`specialist_area` vs a single unified `area` field.** Different semantic
   for code-review vs quality-check but the same shape (a slug). Use one
   field `area` on every skill entry, or keep `specialist_area` /
   `check_area` split? Recommend: single unified `area: <slug>` field. Less
   type-gating, easier to teach.

3. **Shared sibling location.** Options: (a)
   `orchestration/shell-content-contract/shell-ceremony.md` as the canonical
   source + one symlink per governed skill directory, or (b) a generated
   file embedded in each directory at scaffold time (no symlink, duplicate
   bytes but no link-traversal for downstream consumers). Recommend (a) —
   this matches the existing `stack-routing.md`, `review-orchestrator.md`,
   `review-delegation.md` sibling pattern SKILL-21 already uses.

4. **Horizontal skill reshape depth.** All 13 horizontal skills have
   `## Project Overrides`. Should they also symlink `shell-ceremony.md` for
   *other* sections they happen to share (`## Setup` in `bill-code-review`
   and `bill-quality-check`, for example)? Recommend: no. Keep the
   horizontal reshape narrow to `## Project Overrides` dedupe only; leave
   other structural choices per-skill.

5. **Descriptor template for non-specialist horizontal skills.** The
   auto-rendered Descriptor works for code-review specialists and
   quality-check leafs but does not fit horizontal skills like
   `bill-feature-implement`. Recommend: horizontal skills are exempt from
   the `## Descriptor` requirement; the required H2 set applies only to
   platform-pack governed skills.

6. **`template_version` semantics post-freeze.** With `SHELL_CONTRACT_VERSION`
   frozen at 1.0, `template_version` bumps are the only upgrade signal. Keep
   drift detection and `skill-bill upgrade` behavior unchanged? Recommend:
   yes, the split is already correct.

7. **Deletion of `ContractVersionMismatchError`'s migration-hint text.** The
   exception survives as a loud-fail guard for future post-release bumps.
   Should the exception message stay generic ("declared contract version
   does not match shell version") or add a dev-time pointer at
   `skill-bill upgrade`? Recommend: dev-time pointer at `skill-bill
   upgrade`, not the deleted migration script.

8. **Validator ordering refresh.** Should the failure precedence change, or
   stay as a minor extension of the SKILL-21 order? Recommend: extension,
   not change. New links at the end: ceremony-sibling → descriptor-body.

9. **Migration script deletion vs archive.** The script is pre-release dead
   code but contains reference patterns for anyone authoring a future
   migrator. Recommend: delete; the patterns are already in the scaffolder
   + upgrade flow.

10. **Hygiene test scope.** The hygiene test currently blacklists ceremony
    H2s in `content.md`. Should it also whitelist the 3 required H2s in
    SKILL.md (i.e., any extra H2 in SKILL.md is rejected)? Recommend: yes.
    Symmetric hygiene: SKILL.md must contain only the 3 required H2s;
    anything else is a loud-fail.

## Scenario mock-ups (for context)

### Scenario A — authoring a new code-review specialist (post-SKILL-22)

```
User: /bill-skill-scaffold
Claude: What kind of skill?
  3. code-review specialist area
User: 3

Claude: Which platform? kmp | kotlin | new
User: kotlin
Claude: Which area? (already-declared: architecture, performance,
        platform-correctness, security, testing, api-contracts,
        persistence, reliability)
User: concurrency (new)

Claude: Paste your draft — free-form. This goes directly into content.md.
User: <50 lines of concurrency review heuristics>

Claude → skill-bill new-skill --payload <tempfile>

✅ Scaffolded:
   - platform-packs/kotlin/code-review/bill-kotlin-code-review-concurrency/SKILL.md (15 lines)
   - platform-packs/kotlin/code-review/bill-kotlin-code-review-concurrency/content.md
   - shell-ceremony.md (symlinked)
   - platform.yaml: added concurrency to declared_code_review_areas;
     code_review.skills[*].area: concurrency
✅ Validator passed
✅ Tests pass
```

### Scenario B — reading a skill

```
User: cat platform-packs/kotlin/code-review/bill-kotlin-code-review-architecture/SKILL.md
---
name: bill-kotlin-code-review-architecture
description: Reviews shared Kotlin architecture concerns…
shell_contract_version: 1.0
template_version: 2026.04.xx
area: architecture
---

## Descriptor
`bill-kotlin-code-review-architecture` is a specialist reviewer in the
`kotlin` platform pack, scoped to the `architecture` area. …

## Execution
Follow the instructions in [content.md](content.md).

## Ceremony
Follow the shell ceremony in [shell-ceremony.md](shell-ceremony.md).
```

### Scenario C — upgrade after a template change

```
[maintainer bumps TEMPLATE_VERSION in constants.py]

User: skill-bill doctor
⚠ 13 skills have outdated template_version (current: 2026.04.xx, skills at 2026.04.xx-1).

User: skill-bill upgrade
✅ Regenerated 13 SKILL.md files to the 3-H2 shape
✅ Validator passed
✅ content.md files untouched
✅ shell-ceremony.md untouched (canonical source unchanged)
```

## Files expected to change

Created:
- `orchestration/shell-content-contract/shell-ceremony.md` — canonical
  source for the four shared sections.
- `tests/test_shell_ceremony.py` — coverage for `MissingShellCeremonyFileError`,
  sibling presence, canonical body integrity.
- `.feature-specs/SKILL-22-collapse-skill-md-to-shared-ceremony/spec.md`
  (this file).

Modified:
- `skill_bill/constants.py` — revert `SHELL_CONTRACT_VERSION` to `"1.0"`;
  bump `TEMPLATE_VERSION`.
- `skill_bill/shell_content_contract.py` — new required H2 tuples; new
  canonical bodies; new `MissingShellCeremonyFileError` and
  `InvalidDescriptorSectionError`; updated precedence; removed
  migration-hint text from `ContractVersionMismatchError`; extended
  `CEREMONY_FREE_FORM_H2S` where needed.
- `skill_bill/scaffold_template.py` — drop three renderers; add
  `render_descriptor` and `render_ceremony`; update
  `ScaffoldTemplateContext`.
- `skill_bill/scaffold.py` — stage `shell-ceremony.md` symlink per governed
  skill; extend rollback; extend payload schema to accept `area`.
- `skill_bill/cli.py` — upgrade paths the 3-H2 shape; doctor extended to
  include `shell_ceremony_missing` ERROR.
- `scripts/skill_repo_contracts.py` — register `shell-ceremony.md` as a
  required supporting file for governed skill kinds.
- `scripts/validate_agent_configs.py` — recognize the new required H2 set
  and the ceremony sibling.
- `orchestration/shell-content-contract/PLAYBOOK.md` — rewrite v1.0 section;
  remove v1.1 narrative; document the 3-H2 shape + sibling.
- `orchestration/shell-content-contract/SCAFFOLD_PAYLOAD.md` — add `area`
  manifest field.
- `README.md` — update "Authoring a skill" to the 3-H2 shape.
- `AGENTS.md` / `CLAUDE.md` — short note on the final shape.
- `docs/getting-started-for-teams.md` — walkthrough updates.
- All `platform-packs/*/code-review/*/SKILL.md` — regenerated.
- All `platform-packs/*/quality-check/*/SKILL.md` — regenerated.
- All `skills/bill-*/SKILL.md` — Project Overrides collapsed to the shared
  reference line.
- `platform-packs/kotlin/platform.yaml`,
  `platform-packs/kmp/platform.yaml` — contract_version back to 1.0; add
  `area` per skill entry.
- Fixture `platform.yaml` and `SKILL.md` under
  `tests/fixtures/shell_content_contract/` — rebuilt to the 3-H2 shape.
- `tests/test_scaffold.py`, `tests/test_shell_content_contract.py`,
  `tests/test_cli.py`, `tests/test_validate_agent_configs_e2e.py`,
  `tests/test_feature_implement_routing_contract.py` — updated to match
  the reshape.

Removed:
- `scripts/migrate_to_content_md.py` — pre-release dead code.
- `tests/test_migration.py` — covered the removed script.
- Any `contract_version: "1.1"` references in fixtures, docs, or tests.

Not modified:
- `skill_bill/mcp_server.py` — MCP surface unchanged (AC 18).
- `install.sh` / `uninstall.sh` — directory-symlink install already
  covers the new `shell-ceremony.md` sibling (same property SKILL-21
  relied on for `content.md`).
- `skill_bill/stats.py`, `skill_bill/learnings.py`, `skill_bill/triage.py`
  — telemetry/learnings pipelines unchanged.

## Feature flag

N/A. Pre-release structural reshape. No runtime user-facing flag.

## Backup / destructive operations

Reshape rewrites every governed SKILL.md in the repo and adds a new
sibling symlink per governed skill directory. Precautions:

- **Per-skill upgrade atomicity.** The existing `skill-bill upgrade`
  rollback behavior from SKILL-21 is reused. On validator failure, the
  offending SKILL.md is reverted from in-memory snapshot; other skills
  continue.
- **Pre-release context.** There are no external v1.0 packs to migrate;
  no external backups needed. Git is the rollback mechanism.
- **Per-commit discipline.** Each of the phases lands as a separate commit
  on the feature branch so regressions can be bisected cleanly.

No destructive git operations are required.

## Validation strategy

Route via `bill-quality-check` (auto-routes to agent-config for this repo):

```bash
.venv/bin/python3 -m unittest discover -s tests
npx --yes agnix --strict .
.venv/bin/python3 scripts/validate_agent_configs.py
```

All three must pass after the reshape runs.

Additionally, before committing the repo-wide reshape:

1. Run `/bill-kotlin-code-review` against a small fixture diff on the
   pre-reshape branch; capture the output.
2. Run the same command against the post-reshape branch; diff the output.
3. Confirm the outputs are materially identical (same specialists selected,
   same risk register shape, findings consistent within LLM variance).
   Document the comparison in the PR description. Same methodology as
   SKILL-21 AC 20.

## References

- SKILL-14 spec: `.feature-specs/SKILL-14-code-review-shell-pilot/spec.md`
  — parent shell+content architecture.
- SKILL-15 spec: `.feature-specs/SKILL-15-new-skill-scaffolder/spec.md` —
  band distinction SKILL-22 finishes.
- SKILL-16 spec: `.feature-specs/SKILL-16-quality-check-shell-pilot/spec.md`
  — quality-check contract that collapses in this ticket.
- SKILL-19 spec: `.feature-specs/SKILL-19-first-class-platform-scaffolding/spec.md`
  — platform authoring flow.
- SKILL-20 spec: `.feature-specs/SKILL-20-narrow-built-in-packs-to-kotlin-and-kmp/spec.md`
  — narrows the reshape surface to kotlin + kmp.
- SKILL-21 spec: `.feature-specs/SKILL-21-split-shell-from-content/spec.md`
  — immediate parent; this ticket finishes what SKILL-21 started.
- Shell+content contract: `orchestration/shell-content-contract/PLAYBOOK.md`.
- Scaffolder payload contract:
  `orchestration/shell-content-contract/SCAFFOLD_PAYLOAD.md`.
- Scaffolder: `skill_bill/scaffold.py`, `skill_bill/scaffold_template.py`.
- Contract loader: `skill_bill/shell_content_contract.py`.
- Validator: `scripts/validate_agent_configs.py`.
- CLI: `skill_bill/cli.py`.
- Motivation: structural analysis of 26 SKILL.md files showing ~70%
  boilerplate per platform-pack shell; user directive "minimum
  duplication, maximum reuse" (2026-04-19 session).
