51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
---
|
|
title: Skill versioning + bootstrap manifest
|
|
type: concept
|
|
updated: 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](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:
|
|
|
|
```yaml
|
|
---
|
|
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.
|