vitya
e1e5bd1309
Six infra skills carry `version: 1.0.0` in frontmatter: project-bootstrap, setup-context7, task-status-wiki, using-context7, using-markitdown, wiki-maintainer. Bumped manually on SKILL.md edits; semver — MAJOR breaks contract, MINOR adds, PATCH wording. project-bootstrap gets a new Step 5.5 that writes .wiki/concepts/bootstrap-manifest.md per project — skill + version + role table read live from each delegated skill's frontmatter, not hardcoded. The file is overwritten on re-bootstrap; for history, git log. Why: when canonical layout for .wiki/ or .tasks/ changes, projects bootstrapped under the old version drift silently. The per-project manifest makes that drift debuggable instead of guesswork. Communication and discovery skills (caveman family, find-skills, active-platform) aren't versioned — their content is "good copy-paste" and snapshot mismatch isn't a layout problem. Wiki: .wiki/concepts/skill-versioning.md documents the convention; index.md and log.md updated. .tasks/STATUS.md tracks (a/b/c) progress. Setup/using split for wiki and tasks (commits b and c) follows. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
49 lines
2.3 KiB
Markdown
49 lines
2.3 KiB
Markdown
---
|
|
title: Skill versioning + bootstrap manifest
|
|
type: concept
|
|
updated: 2026-04-28
|
|
---
|
|
|
|
# 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
|
|
|
|
Currently 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`) aren't versioned — their content is "good copy-paste" and a snapshot mismatch isn't a layout problem.
|
|
|
|
If we ever start packaging or marketplace-publishing the rest, we'll version them too.
|
|
|
|
## 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.
|