decide: per-skill metadata.version has no owning rule #127

New Issue

Claude · 2026-08-31T08:08:20Z

Claude commented

2026-08-31 08:08:20 +00:00

Found during the #99 ADR-0020 retrofit and the follow-up audit pass on refactor/adr0020-skill-retrofit. Not fixed there, because there is nothing to fix until the convention exists — any edit would be one agent's guess overwriting another's.

The measurement

Counted just now against the working tree, over all 39 skills, distinguishing metadata.version (nested) from a top-level version::

plugin	skills carrying `metadata.version`
`core`	3 / 3
`lint`	2 / 2
`gitea`	6 / 7 — all but `gitea-files`
`bin`	0 / 11
`git`	0 / 9
`kyberforge`	0 / 7
total	11 / 39

The split is per-plugin, not per-skill: three plugins use it near-universally, three not at all. gitea-files is the single intra-plugin exception.

One skill, bin/write-docs, carries a top-level version: "1.0" alongside a metadata: block that holds only category. That is a different field in a different position, and it is the only instance of it in the corpus — worth resolving in the same pass, since "does a skill carry a version" and "where does it live" are the same question.

Why nothing settles it

No rubric states a rule. skill-audit's reference files do not mention the field. skill-author/references/create.md:104 mentions it once, permissively, in a list of optional frontmatter: - `metadata` — key-value map; use `author`, `version`, `category`. That is an invitation, not a convention — it says nothing about whether it is required, what the format is, or when it gets bumped.
No gate checks it. Nothing in scripts/ or in agent-audit/skill-audit's validate.sh reads it.
ADR-0006 does not cover it. It governs plugin manifest versions (plugin.json / apm.yml parity) and its first line reads "Moot as of ADR-0015." — the invariant it protected is deleted, not adapted.

Why it surfaced

Two agents on this branch reached opposite conclusions in good faith, both locally correct:

one deleted git-commits' lone metadata.version as drift, reasoning that no other git skill has one and an unmaintained version string is worse than none;
one bumped both lint skills' versions as part of editing them, reasoning that lint is 2/2 and a changed skill with a stale version is a lie.

Neither can be called wrong against the current state of the repo, which is the tell that the rule is missing rather than misapplied. The same disagreement will recur on every future edit that touches a skill in core, lint, or gitea.

The decision

Pick one and write it into skill-audit's rubric (and, if it becomes a requirement, into skill-author's create flow):

Corpus-wide required. Every skill carries metadata.version; define the bump rule (what counts as a bump-worthy change) and add a gate. Costs 28 backfills and a maintenance obligation on every edit.
Corpus-wide dropped. No skill carries it; git history and the plugin version are the record. Costs 11 deletions, and loses per-skill version signal for consumers.
Deliberately per-plugin. State it explicitly in the rubric as a plugin-owner's choice, so a future agent reads a decision instead of inferring a convention from a majority. Cheapest, but only works if it is written down — the current state is indistinguishable from drift.

Whichever is chosen, decide gitea-files and write-docs in the same pass, and re-measure first: the counts above are from refactor/adr0020-skill-retrofit and skills are being edited on it.

Files

plugins/kyberforge/.apm/skills/skill-audit/references/ — where the rule belongs
plugins/kyberforge/.apm/skills/skill-author/references/create.md:104 — the one permissive mention
docs/adr/0006-plugin-version-parity.md — moot, but the nearest prior art
plugins/bin/.apm/skills/write-docs/SKILL.md — the top-level version: outlier
plugins/gitea/.apm/skills/gitea-files/SKILL.md �� the intra-plugin exception

#99 — the retrofit during which this surfaced
#101 — the other open skill-audit / skill-author structural question

Found during the #99 ADR-0020 retrofit and the follow-up audit pass on `refactor/adr0020-skill-retrofit`. Not fixed there, because there is nothing to fix until the convention exists — any edit would be one agent's guess overwriting another's. ## The measurement Counted just now against the working tree, over all 39 skills, distinguishing `metadata.version` (nested) from a top-level `version:`: | plugin | skills carrying `metadata.version` | |---|---| | `core` | 3 / 3 | | `lint` | 2 / 2 | | `gitea` | 6 / 7 — all but `gitea-files` | | `bin` | 0 / 11 | | `git` | 0 / 9 | | `kyberforge` | 0 / 7 | | **total** | **11 / 39** | The split is per-plugin, not per-skill: three plugins use it near-universally, three not at all. `gitea-files` is the single intra-plugin exception. One skill, `bin/write-docs`, carries a **top-level** `version: "1.0"` alongside a `metadata:` block that holds only `category`. That is a different field in a different position, and it is the only instance of it in the corpus — worth resolving in the same pass, since "does a skill carry a version" and "where does it live" are the same question. ## Why nothing settles it - **No rubric states a rule.** `skill-audit`'s reference files do not mention the field. `skill-author/references/create.md:104` mentions it once, permissively, in a list of optional frontmatter: `` - `metadata` — key-value map; use `author`, `version`, `category` ``. That is an invitation, not a convention — it says nothing about whether it is required, what the format is, or when it gets bumped. - **No gate checks it.** Nothing in `scripts/` or in `agent-audit`/`skill-audit`'s `validate.sh` reads it. - **ADR-0006 does not cover it.** It governs *plugin manifest* versions (`plugin.json` / `apm.yml` parity) and its first line reads "**Moot as of ADR-0015.**" — the invariant it protected is deleted, not adapted. ## Why it surfaced Two agents on this branch reached opposite conclusions in good faith, both locally correct: - one deleted `git-commits`' lone `metadata.version` as drift, reasoning that no other git skill has one and an unmaintained version string is worse than none; - one bumped both `lint` skills' versions as part of editing them, reasoning that lint is 2/2 and a changed skill with a stale version is a lie. Neither can be called wrong against the current state of the repo, which is the tell that the rule is missing rather than misapplied. The same disagreement will recur on every future edit that touches a skill in `core`, `lint`, or `gitea`. ## The decision Pick one and write it into `skill-audit`'s rubric (and, if it becomes a requirement, into `skill-author`'s create flow): 1. **Corpus-wide required.** Every skill carries `metadata.version`; define the bump rule (what counts as a bump-worthy change) and add a gate. Costs 28 backfills and a maintenance obligation on every edit. 2. **Corpus-wide dropped.** No skill carries it; git history and the plugin version are the record. Costs 11 deletions, and loses per-skill version signal for consumers. 3. **Deliberately per-plugin.** State it explicitly in the rubric as a plugin-owner's choice, so a future agent reads a decision instead of inferring a convention from a majority. Cheapest, but only works if it is written down — the current state is indistinguishable from drift. Whichever is chosen, decide `gitea-files` and `write-docs` in the same pass, and re-measure first: the counts above are from `refactor/adr0020-skill-retrofit` and skills are being edited on it. ## Files - `plugins/kyberforge/.apm/skills/skill-audit/references/` — where the rule belongs - `plugins/kyberforge/.apm/skills/skill-author/references/create.md:104` — the one permissive mention - `docs/adr/0006-plugin-version-parity.md` — moot, but the nearest prior art - `plugins/bin/.apm/skills/write-docs/SKILL.md` — the top-level `version:` outlier - `plugins/gitea/.apm/skills/gitea-files/SKILL.md` �� the intra-plugin exception ## Related - #99 — the retrofit during which this surfaced - #101 — the other open `skill-audit` / `skill-author` structural question

Claude added this to the Skills & Agents milestone 2026-08-31 08:08:20 +00:00

Claude added the Kind/Enhancement

labels 2026-08-31 08:08:20 +00:00

Claude commented

2026-09-07 20:17:14 +00:00

Implementation note

Decision (discussed and confirmed in session, recorded in docs/adr/0022-skill-metadata-version-is-mandatory.md): metadata.version moves from a per-plugin, undocumented split to mandatory on every skill. Skills that never carried one are seeded at 1.0.0 (not 0.1.0 — that value stays reserved for a brand-new skill's actual starting point). Skills that already had real tracked history keep their existing value untouched.

Non-git portion done (git-plugin portion is in progress under the same decision, will follow up here):

19 skills seeded with metadata.version: "1.0.0": all 11 bin skills except research (which had a metadata: block but no version — same treatment) and write-docs (special case below), all 7 kyberforge skills, and gitea-files.
write-docs special case: it carried a stray top-level version: "1.0" outside the metadata: block, not a fresh, unversioned skill. Moved that existing value into metadata.version rather than overwriting it with 1.0.0, and removed the top-level field.
plugins/kyberforge/.apm/skills/skill-author/references/create.md — metadata.version moved out of "Optional frontmatter" into the required-fields framing, citing ADR-0022.
plugins/kyberforge/.apm/skills/skill-author/SKILL.md — dropped the "with metadata.version present" conditional in the version-bump rule; it's unconditional now (minor on create from 0.1.0, patch on improve).
.pre-commit-config.yaml's skill-frontmatter hook — extended to fail a SKILL.md missing metadata.version, same class of failure as a missing name:/description:. Verified against a negative-test fixture (stripped-version copy fails; untouched already-versioned skill still passes).

Not yet reset: git-commits keeps its existing 0.1.3 — it already had genuine tracked history under the old conditional rule, and this decision doesn't roll back skills that were already compliant.

## Implementation note Decision (discussed and confirmed in session, recorded in `docs/adr/0022-skill-metadata-version-is-mandatory.md`): `metadata.version` moves from a per-plugin, undocumented split to **mandatory on every skill**. Skills that never carried one are seeded at `1.0.0` (not `0.1.0` — that value stays reserved for a brand-new skill's actual starting point). Skills that already had real tracked history keep their existing value untouched. Non-git portion done (git-plugin portion is in progress under the same decision, will follow up here): - **19 skills seeded with `metadata.version: "1.0.0"`:** all 11 `bin` skills except `research` (which had a `metadata:` block but no version — same treatment) and `write-docs` (special case below), all 7 `kyberforge` skills, and `gitea-files`. - **`write-docs` special case:** it carried a stray **top-level** `version: "1.0"` outside the `metadata:` block, not a fresh, unversioned skill. Moved that existing value into `metadata.version` rather than overwriting it with `1.0.0`, and removed the top-level field. - **`plugins/kyberforge/.apm/skills/skill-author/references/create.md`** — `metadata.version` moved out of "Optional frontmatter" into the required-fields framing, citing ADR-0022. - **`plugins/kyberforge/.apm/skills/skill-author/SKILL.md`** — dropped the "with `metadata.version` present" conditional in the version-bump rule; it's unconditional now (minor on create from `0.1.0`, patch on improve). - **`.pre-commit-config.yaml`'s `skill-frontmatter` hook** — extended to fail a SKILL.md missing `metadata.version`, same class of failure as a missing `name:`/`description:`. Verified against a negative-test fixture (stripped-version copy fails; untouched already-versioned skill still passes). Not yet reset: `git-commits` keeps its existing `0.1.3` — it already had genuine tracked history under the old conditional rule, and this decision doesn't roll back skills that were already compliant.

Claude commented

2026-09-07 20:23:56 +00:00

Implementation note (follow-up — git-plugin portion)

Completed the remaining slice: git-branches, git-history, git-remotes, git-submodules, git-workflow, git-worktrees, pc-author, pc-run all seeded with metadata.version: "1.0.0" as the first key under metadata:, matching git-commits' existing style. git-commits' own "0.1.3" left untouched, per the earlier note in this thread — it already had real tracked history.

All 39 skills now carry metadata.version. This was bundled with #113's implementation pass since both touched the same nine plugins/git/.apm/skills/*/SKILL.md files — see #113 for that half's detail.

## Implementation note (follow-up — git-plugin portion) Completed the remaining slice: `git-branches`, `git-history`, `git-remotes`, `git-submodules`, `git-workflow`, `git-worktrees`, `pc-author`, `pc-run` all seeded with `metadata.version: "1.0.0"` as the first key under `metadata:`, matching `git-commits`' existing style. `git-commits`' own `"0.1.3"` left untouched, per the earlier note in this thread — it already had real tracked history. All 39 skills now carry `metadata.version`. This was bundled with #113's implementation pass since both touched the same nine `plugins/git/.apm/skills/*/SKILL.md` files — see #113 for that half's detail.

Defame1297 referenced this issue from a commit

2026-09-07 20:49:18 +00:00

refactor(skills): mandate metadata.version on every skill's frontmatter

Defame1297 referenced this issue from a commit

2026-09-07 20:49:18 +00:00

refactor(git): normalize rtk-prefix usage, add metadata.version

Defame1297 closed this issue

2026-09-07 20:49:18 +00:00

Claude referenced this issue

2026-09-07 20:49:43 +00:00

Close four small ADR-0020-retrofit follow-ups (#125, #127, #113, #118) #130

Defame1297 referenced this issue from a commit