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

Only 12 of 39 skills carried metadata.version, and adoption tracked
which plugin a skill lived in rather than any stated rule: core,
gitea and lint were consistent adopters, bin and kyberforge were
consistent non-adopters, git was split with one outlier. There was
no documented convention, and skill-author's own bump logic was
already written as if presence were conditional.

metadata.version is now required on every skill. The 19 skills here
that never carried one (bin, kyberforge, gitea-files) are seeded at
1.0.0, not 0.1.0 -- that value stays reserved for a skill's actual
creation point under skill-author's existing convention. The
skill-frontmatter pre-commit hook now fails a SKILL.md missing the
field, the same class of failure as a missing name/description.

Full rationale in the new ADR. The git-plugin skills that also need
this field follow in the next commit, bundled with issue #113's rtk
normalization since both touch the same files.

Refs: #127
ADR: 0022
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP

plugins/bin/.apm/skills/caveman/SKILL.md

@@ -4,6 +4,8 @@ disable-model-invocation: true
 description: >
   Ultra-compressed output mode that drops articles, filler and pleasantries while
   keeping technical substance exact, cutting token usage by roughly 75%.
+metadata:
+  version: "1.0.0"
 ---
 
 Respond terse like smart caveman. All technical substance stay. Only fluff die.

plugins/bin/.apm/skills/diagnose/SKILL.md

@@ -4,6 +4,8 @@ description: >
   Use when the user says "diagnose this" or "debug this", reports something
   broken, throwing, or failing, or says something got slow. Not filing or
   triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Diagnose

plugins/bin/.apm/skills/grill-me/SKILL.md

@@ -5,6 +5,8 @@ description: >
   relentless interview — one question at a time, down each branch of the
   decision tree. Not a plan to challenge against `CONTEXT.md` and ADRs ->
   `grill-with-docs`.
+metadata:
+  version: "1.0.0"
 ---
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.

plugins/bin/.apm/skills/grill-with-docs/SKILL.md

@@ -4,6 +4,8 @@ description: >
   Use when a plan should be stress-tested against the project's domain model —
   the interview challenges terms against `CONTEXT.md` and writes decisions into
   it and into ADRs as they land. Not a plain interview -> `grill-me`.
+metadata:
+  version: "1.0.0"
 ---
 
 <what-to-do>

plugins/bin/.apm/skills/improve-codebase-architecture/SKILL.md

@@ -6,6 +6,8 @@ description: >
   testable and AI-navigable — deepening opportunities that turn shallow modules
   into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a
   failure -> `diagnose`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Improve Codebase Architecture

plugins/bin/.apm/skills/prototype/SKILL.md

@@ -5,6 +5,8 @@ description: >
   a data model, state machine or business logic, or to mock up a UI in several
   variations. Not production code -> `tdd`. Not talking a design through ->
   `grill-me`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Prototype

plugins/bin/.apm/skills/research/SKILL.md

@@ -6,6 +6,7 @@ description: >-
   documentation written from existing code or specs -> `write-docs`. Not a bug
   or incident -> `diagnose`.
 metadata:
+  version: "1.0.0"
   category: research
 allowed-tools:
   - Grep

plugins/bin/.apm/skills/tdd/SKILL.md

@@ -4,6 +4,8 @@ description: >
   Use when the user wants a feature built or a bug fixed test-first, in a strict
   red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
   bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Test-Driven Development

plugins/bin/.apm/skills/triage/SKILL.md

@@ -4,6 +4,8 @@ description: >
   Use when the user wants an issue created, triaged, or moved through the
   tracker's triage states, or an issue prepared for an AFK agent. Not debugging
   the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
+metadata:
+  version: "1.0.0"
 ---
 
 # Triage

plugins/bin/.apm/skills/write-docs/SKILL.md

@@ -6,10 +6,10 @@ description: >
   module", "create docs for this feature", "write a README for this". Not an ADR
   or other decision record -> `grill-with-docs`. Not an external tool researched
   from its docs -> `research`.
-version: "1.0"
 updated: 2026-05-17
 when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
 metadata:
+  version: "1.0"
   category: implement
 source:
   - repo: anthropics/skills

plugins/bin/.apm/skills/zoom-out/SKILL.md

@@ -2,6 +2,8 @@
 name: zoom-out
 description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
 disable-model-invocation: true
+metadata:
+  version: "1.0.0"
 ---
 
 I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.

plugins/gitea/.apm/skills/gitea-files/SKILL.md

@@ -11,6 +11,7 @@ compatibility: Requires the Gitea MCP server configured with a token scoped to a
   is not actually required for any of this domain's five tools.
 
 metadata:
+  version: "1.0.0"
   category: gitea
   source_keys:
     - gitea-mcp-repo

plugins/kyberforge/.apm/skills/agent-audit/SKILL.md

@@ -7,6 +7,7 @@ description: >
   directory -> skill-audit.
 allowed-tools: Bash Read
 metadata:
+  version: "1.0.0"
   category: factory
   source_keys:
     - context7-websites-code-claude

plugins/kyberforge/.apm/skills/agent-author/SKILL.md

@@ -6,6 +6,7 @@ description: >
   Not read-only review -> `agent-audit`. Not skills -> `skill-author`.
 allowed-tools: Bash Read Write Edit
 metadata:
+  version: "1.0.0"
   category: factory
   source_keys:
     - context7-websites-code-claude

plugins/kyberforge/.apm/skills/apm-install/SKILL.md

@@ -6,6 +6,7 @@ description: >
   authoring, publishing, auditing, or dependency installation for an apm
   package -> `apm-workflow`.
 metadata:
+  version: "1.0.0"
   category: apm
   source_keys:
     - context7-microsoft-apm

plugins/kyberforge/.apm/skills/apm-workflow/SKILL.md

@@ -5,6 +5,7 @@ description: >
   the dependencies it declares, or an apm marketplace — even when the user does
   not say "apm". Not the apm binary or an agent runtime -> `apm-install`.
 metadata:
+  version: "1.0.0"
   category: apm
   source_keys:
     - context7-microsoft-apm

plugins/kyberforge/.apm/skills/forge/SKILL.md

@@ -8,6 +8,7 @@ description: >
   already named — invoke `skill-author`, `agent-author` or `apm-workflow`
   directly.
 metadata:
+  version: "1.0.0"
   category: factory
   source_keys:
     - claude-code-subagents-docs

plugins/kyberforge/.apm/skills/skill-audit/SKILL.md

@@ -7,6 +7,7 @@ description: >
   skill-author.
 allowed-tools: Bash Read
 metadata:
+  version: "1.0.0"
   category: factory
   source_keys:
     - agentskills-home

plugins/kyberforge/.apm/skills/skill-author/SKILL.md

@@ -6,6 +6,7 @@ description: >
   Not read-only review -> `skill-audit`. Not agent files -> `agent-author`.
 allowed-tools: Bash Read Write Edit
 metadata:
+  version: "1.0.0"
   category: factory
   source_keys:
     - agentskills-home
@@ -56,6 +57,6 @@ Gates `/skill-audit` enforces in both flows:
 
 Run `/skill-audit` on the resolved skill directory; resolve every FAIL before reporting done. It checks name-to-directory match, placeholders, both size budgets, boundary-target resolution and script hygiene — do not hand-check those. Hand-check the one thing it misses: an empty body reports `PASS  SKILL.md body word count 0 (ADR-0020 target: 600)`, so confirm at least one non-empty section exists.
 
-With `metadata.version` present, bump the **minor** version on create (new skills start at `0.1.0`) and the **patch** version on improve.
+Bump `metadata.version`: the **minor** version on create (new skills start at `0.1.0`) and the **patch** version on improve.
 
 **Commit verification.** Inside a git worktree: once the audit is clean, run `git add` and `git commit` — do not stop at staging. Re-run `git log --oneline -1` and confirm the hash changed from Step 1's. A non-empty `git diff --stat` is not proof: staged-but-uncommitted work is part of no commit and is silently lost if the tree is cleaned up. Report done only once the hash has changed. Outside a worktree (a skill under `~/.claude/skills/`, say) nothing is committable — report done on a clean audit, naming that as the reason.

plugins/kyberforge/.apm/skills/skill-author/references/create.md

@@ -101,8 +101,10 @@ plain sentence and `disable-model-invocation: true` instead.
 - `license` — include when distributing the skill externally
 - `compatibility` — include if the skill requires specific tools, runtimes, or network access
   (max 500 characters)
-- `metadata` — key-value map; use `author`, `version`, `category`; add `source_keys` now (Step 6)
-  if research sources are in context
+- `metadata` — key-value map. `version` is **required** on every skill (ADR-0022), seeded at
+  `"1.0.0"` for a retrofitted skill with no prior version and at `"0.1.0"` for a newly created
+  skill; `author` and `category` stay optional; add `source_keys` now (Step 6) if research sources
+  are in context
 - `allowed-tools` — space-separated pre-approved tools; reduces permission prompts (experimental —
   support varies by client)
 - `disable-model-invocation` — hand-invoked skills only