2.8 KiB
title, type, updated
| title | type | updated |
|---|---|---|
| Skill versioning + bootstrap manifest | concept | 2026-05-01 |
Skill versioning + bootstrap manifest
Why version skills
When the canonical layout for .wiki/ or .tasks/ changes (as it has — see wiki-realignment.md and the upcoming task-tracking realignment), projects bootstrapped under the old version drift out of canon silently. Without a record of which version did the bootstrap, debugging that drift is guesswork.
The fix is two-sided: skills carry a version, and project-bootstrap records which versions it used in a per-project manifest.
Frontmatter format
The 6 infra skills (project-bootstrap, setup-context7, setup-wiki, setup-tasks, using-wiki, using-tasks, using-context7, using-markitdown) carry version: <semver> in their frontmatter:
---
name: project-bootstrap
version: 1.0.0
description: …
---
Semver:
- MAJOR — breaks the contract (renames, layout changes, trigger-phrase removals).
- MINOR — adds capability (new triggers, new optional steps).
- PATCH — wording / clarity tweaks; no behavioral change.
Bumped manually when SKILL.md is edited. No CI gate — discipline-based.
What skills are versioned
Originally only the infrastructure skills (the ones bootstrap touches and that govern project layout). Communication-mode skills (caveman, family) and discovery skills (find-skills, active-platform) were left unversioned — their content was "good copy-paste" and a snapshot mismatch wasn't a layout problem.
As of project-discipline v0.1.0 (Rule 3), the requirement extends to all skills in this repo, regardless of category. Communication-mode and discovery skills also need version: in frontmatter; the migration is a separate one-time task tracked in .tasks/. Rationale: discipline-by-default is simpler than maintaining a list of "exempt" skills, and it costs nothing — version: 0.1.0 is added on the next edit per the Rule 3 first-edit-unversioned clause.
If we ever start packaging or marketplace-publishing skills outside this repo, the same rule still applies.
The manifest
project-bootstrap writes .wiki/concepts/bootstrap-manifest.md with a frontmatter block + a small table of skill + version + role. The file is overwritten on re-bootstrap (not appended) — for history, git log shows the changes over time.
Why this matters
Concrete scenario: you discover that some old project's .tasks/STATUS.md doesn't follow the canon (no per-task files, no emoji status). Look at its bootstrap-manifest.md — if it shows setup-tasks: 1.0.0 but the current canon is from 2.0.0, you know exactly what happened and can re-run setup-tasks to migrate.
Without the manifest: git log of the project's .tasks/ folder, guess from filenames, hope.