Skill Versioning

PM Skills tracks versions at two levels: the repo version (the release package) and individual skill versions (each skill’s contract). These are intentionally decoupled.

Two Version Levels

Level	Example	Where it lives
Repo version	v2.8.1	Git tags, CHANGELOG.md, plugin.json
Skill version	2.0.0	`version` field in each SKILL.md frontmatter

A repo release packages many skills. A skill can iterate across multiple repo releases. For example, repo v2.8.0 contains deliver-prd at version 2.0.0 and utility-pm-skill-validate at version 1.0.0.

How Skill Versions Work

Each skill follows Semantic Versioning 2.0.0. The “public API” of a skill is its shipped contract . the command name, required output sections, interaction pattern, and output guarantees.

What triggers each bump

Bump	When	Examples
Major (X.0.0)	Required contract changed . existing usage breaks	Command renamed, required section removed, interaction pattern changed
Minor (x.Y.0)	New optional capability . existing usage still works	New optional output section, handles more scenarios
Patch (x.y.Z)	Clarification only . same requirements, better expression	Wording improved, example rewritten, checklist item rephrased

The tie-breaker rule

When a change doesn’t clearly fit one category:

If a user must do something new to stay compliant with the skill’s required contract, classify as major. If the new behavior is additive or optional, classify as minor. If the required behavior is unchanged and only clarified, classify as patch.

HISTORY.md

When a skill ships its second version, a HISTORY.md file is created in the skill directory connecting versions to efforts and releases:

skills/deliver-prd/
  SKILL.md
  HISTORY.md          ← created at second version
  references/
    TEMPLATE.md
    EXAMPLE.md

HISTORY.md includes a summary table (newest first) and a section per version describing what changed and why.

Skills on their first version don’t need HISTORY.md . the effort brief and skills manifest cover the initial release.

Skills Manifest

Each repo release includes a skills-manifest.yaml in its release plan folder, listing which skill versions changed:

release: v2.8.0
date: 2026-04-03

skills:
  - name: utility-pm-skill-validate
    version: 1.0.0
    previous_version: null
    change_type: added
    effort: F-10

  - name: utility-pm-skill-iterate
    version: 1.0.0
    previous_version: null
    change_type: added
    effort: F-11

This answers: “Which skill versions shipped in release X?”

How the Lifecycle Tools Handle Versioning

The lifecycle tools integrate with versioning:

/pm-skill-validate . reports the current skill version in the validation report header
/pm-skill-iterate . suggests a version bump class (patch/minor/major) after applying changes, updates the version and updated fields on confirmation, and offers to create or update HISTORY.md

Current Skill Versions

Skill versions are tracked individually in each skills/{name}/SKILL.md frontmatter and aggregated per release in docs/internal/release-plans/vX.Y.Z/skills-manifest.yaml. The frontmatter is the source of truth; this section is summary.

As of v2.15.0 (63 skills total):

24 domain skills at 2.0.0: lifted during the v2.0 flat-structure restructure.
2 domain skills at 1.0.0: deliver-acceptance-criteria (shipped in v2.7.0) and measure-okr-grader (shipped in v2.12.0).
foundation-persona at 2.5.0: evolved through 2.x iterations to the canonical v2.5 output contract.
foundation-meeting-synthesize at 1.0.1: patched in v2.11.1 (description reworded to remove an inline : that was truncating under strict YAML).
6 foundation skills at 1.0.0: foundation-lean-canvas, foundation-meeting-agenda, foundation-meeting-brief, foundation-meeting-recap, foundation-okr-writer, foundation-stakeholder-update.
6 utility skills at 1.0.0: utility-pm-skill-builder, utility-pm-skill-validate, utility-pm-skill-iterate, utility-mermaid-diagrams, utility-slideshow-creator, utility-update-pm-skills.

Most version bumps to date have been the v2.0 flat-structure lift, the v2.5 persona contract evolution, and the v2.11.1 meeting-synthesize description patch. The first quality-driven version bumps will come from the quality convergence effort.

Traceability

Question	Where to look
What’s the current version of a skill?	`skills/{name}/SKILL.md` frontmatter
What changed between skill versions?	`skills/{name}/HISTORY.md`
Which skill versions shipped in a release?	`docs/internal/release-plans/vX.Y.Z/skills-manifest.yaml`
What effort created or changed a skill?	`docs/internal/efforts/`
What files existed at a specific release?	`git show vX.Y.Z:skills/{name}/`