holocron/docs/adr/0022-skill-metadata-version-is-mandatory.md

# Every skill's `metadata.version` is mandatory, not a per-plugin option

**Status: accepted (2026-09-07).**

## Context

`metadata.version` is optional SKILL.md frontmatter (`create.md`'s "Optional frontmatter" list:
"uncomment and fill in, or remove entirely"). `skill-author`'s own bump logic was written
conditionally — "with `metadata.version` present, bump the minor version on create... and the
patch version on improve" — which only makes sense if presence is a real per-skill choice.

Adoption never followed a rule; it followed the plugin. Of 39 skills, 12 carry a version:

| Plugin | Has it | Total |
|---|---|---|
| `core` | 3 | 3 |
| `gitea` | 6 | 7 |
| `lint` | 2 | 2 |
| `git` | 1 | 9 |
| `bin` | 0 | 11 |
| `kyberforge` | 0 | 7 |

`core`, `gitea` and `lint` are consistent adopters (`gitea-files` the one gap); `bin` and
`kyberforge` are consistent non-adopters; `git` has one outlier (`git-commits`, versioned for no
plugin-specific reason found on inspection — no comment, no cross-reference, nothing distinguishing
it from its eight siblings). Issue #127 raised this as an undocumented split: two house norms
coexisting with no stated rule for which applies where, the same class of defect as an unstated
`rtk`/bare-`git` convention (#113) found in the same audit pass.

## Decision

**Every skill's frontmatter carries `metadata.version`.** It is no longer optional, and no longer a
per-plugin choice.

- **The 27 skills that never carried one are seeded at `1.0.0`**, not `0.1.0`. `0.1.0` is
  `skill-author`'s existing new-skill starting point, chosen for a skill with no revision history to
  its name yet. These 27 have all been through the ADR-0020 retrofit and repeated audit passes
  without ever tracking a version; crediting them with `0.1.0` would understate that, and there is
  no real history to justify seeding higher than a first stable release. `1.0.0` marks "versioned as
  of this retrofit," `0.1.0` keeps meaning "created and never yet revised."
- **New skills still start at `0.1.0`.** `skill-author`'s create/improve bump convention is
  unchanged; only the presence of the field stops being conditional.
- **The one outlier in the other direction, `git-commits`, keeps its existing value** (`0.1.3`) —
  it already had real tracked history under the old conditional rule, and this decision does not
  reset skills that were already compliant.
- **`bin/write-docs`'s top-level `version:` moves into `metadata:`, normalized to `1.0.0`.** It is
  the one skill that carried a version outside the `metadata:` block, which is why the table above
  counts `bin` as 0 — a top-level `version:` is not `metadata.version`, and nothing reads it. #127
  raised it alongside the split because "does a skill carry a version" and "where does it live" are
  the same question. Its value (`1.0`) is not semver and carries no more real history than the 27
  unversioned skills, so it is relocated and reset to the same `1.0.0` seed rather than preserved
  like `git-commits`'s tracked `0.1.3`.
- **`skill-frontmatter`'s pre-commit hook gains the check.** It already fails a SKILL.md missing
  `name:` or `description:`; a missing `metadata.version` is now the same class of failure, not a
  style nit an audit might or might not catch.

## Considered options

**Leave it per-plugin, document the split.** This was the initial framing of #127 and is coherent —
`core`/`gitea`/`lint` keep it, `bin`/`kyberforge` don't, two outliers get normalized to match their
plugin. Rejected on reconsideration: a rule that says "some plugins track this and some don't" is
strictly harder to state, audit and onboard against than "every skill does," for a field whose entire
job is answering "did this change since I last read it" — a question with the same shape everywhere
it's asked, not one that varies by plugin domain.

**Drop the field corpus-wide.** Rejected: `skill-author` already depends on it to decide whether a
create/improve pass owes a bump, so the 12 skills carrying it are not tracking dead weight — removing
it discards real revision signal for no gain.

## Consequences

27 SKILL.md files gain `metadata.version: "1.0.0"`, and a 28th — `bin/write-docs` — reaches the same
value by relocating its top-level `version: "1.0"` into `metadata:`. `skill-author`'s `create.md`
moves the field from "Optional frontmatter" to the required list, citing this ADR. `skill-author`'s
own SKILL.md drops the "with `metadata.version` present" conditional in its bump-rule line, since
presence is no longer in question. `.pre-commit-config.yaml`'s `skill-frontmatter` hook is extended
to require the field, closing the gap #113 and #118 both named in the same audit pass: a stated rule
with nothing enforcing it drifts the same way an unstated one does.

## Amendment (2026-09-16) — the bump is enforced at push, not only required to exist

**Context.** Making the field mandatory did not make it move. The only thing that bumped it was
`skill-author` Step 4, so every hand edit and every trim pass skipped the bump: on
`docs/simplification-audit`, 17 of the 40 skill directories that changed against `main` carried
the same `metadata.version` as `main`, and `gitea` alone sat at six different values. Both
validators checked presence and semver shape, never movement, so the field could not answer the
question this ADR gives it — "did this change since I last read it". (Simplification audit
finding 33.)

**Decision.** `scripts/check-skill-version-bump.sh` runs as a pre-push hook on every push. For each
skill directory under `plugins/*/.apm/skills/` that differs between the pushed ref and its
merge-base with `main`, ignoring `tests/`, the pushed `metadata.version` must be strictly greater
than `main`'s.

- **Baseline is the merge-base with `main`, not the previous commit.** Readers only ever see
  `main` — installs resolve against the default branch (ADR-0018) — so one bump per branch is what
  the field owes them. A per-commit check would bump a skill once per commit and inflate the
  number past meaning.
- **"Greater", not "exactly one patch higher".** A second `skill-author` pass on the same branch
  that bumps again still passes.
- **`tests/` is excluded.** No agent loads it; a fixture-only change does not change the skill.
- **Skills absent from either side are exempt.** New, renamed and merged skills start fresh under
  the rules above; deleted skills have nothing to check.
- **Every plugin is covered, `bin` included,** and the gate is repo-local — it is not exported
  through `.pre-commit-hooks.yaml`.

**Considered options.** *Declare the field advisory* — cheapest, but concedes the field cannot do
its job. *Drop the field* — rejected by this ADR already, and costlier now. *Check at commit
time against `HEAD`* — rejected for the inflation above.

**Consequences.** The 17 unbumped skills took a patch bump in the commit that added the gate.
Like `check-release-needed`, the gate only fires on a local `git push` through pre-commit: a merge
made with Gitea's merge button runs no local hooks and is not checked. A typo fix in a skill now
costs a version bump; that is the rule working, not noise.