Repository navigation
Description
Problem Statement
A project is initialised once, and its generated skills (.claude/skills/speckit-*/SKILL.md and the equivalents for other agents) can stay there for months while Spec Kit moves on. The agent keeps running them, and nothing in the skill says which Spec Kit, extension or preset version produced it.
specify self checkcovers the CLI, not the files generated in each project..specify/integration.jsonrecords the version, but it's Spec Kit-specific.SKILL.mdis what agents and general-purpose tools read.
Real example: a project generated with 0.13.1.dev0 while the latest release was v1.4.0. The skills gave no sign of it.
Follow-up to discussion #5400, as suggested there.
Proposed Solution
Add an optional version to the metadata built by CommandRegistrar.build_skill_frontmatter:
metadata:
author: "github-spec-kit"
source: "templates/commands/plan.md"
version: "1.4.0"Function change (src/specify_cli/agents.py):
@staticmethod
def build_skill_frontmatter(
agent_name: str,
skill_name: str,
description: str,
source: str,
author: object = "github-spec-kit",
version: object = None,
) -> dict:
...
if version not in (None, "", "unknown"):
skill_frontmatter["metadata"]["version"] = str(version)The parameter is optional and the key is left out when there's no version, so callers that don't pass one produce the same output as today.
What version each kind of skill gets:
| Skill origin | source today |
version |
|---|---|---|
Core command (Claude, Alquimia, Vibe _build_skill_fm; core restore in presets/_manager_skills.py) |
templates/commands/<name>.md |
get_speckit_version() |
Extension command (extensions/__init__.py; extension restore in presets/_manager_skills.py) |
extension:<id> |
the extension's ExtensionManifest.version (extension.version in extension.yml), passed the same way #4458 passes author |
Preset override (presets/_manager_skills.py) |
preset:<id> / override:<cmd> |
the preset's PresetManifest.version |
For the extension restore path, extension_restore would also need to carry the version, next to the source and author it already stores.
version is always quoted, so YAML doesn't read 1.10 as a number.
Alternatives Considered
- Keep relying on
.specify/integration.json. Works for Spec Kit's own tooling, but any other tool or agent has to know Spec Kit's internals to read it, and it doesn't cover extension or preset versions. - Put the version in the body as a comment. Not machine-readable in a standard place.
metadatais the Agent Skills spec's free-form string map for exactly this, and agents that don't use a key ignore it. - Change
sourceto an absolute URL (e.g. pinned to the release tag). Possible later, but it changes the meaning of an existing field.versionis additive and covers the main need.
Component
Agent integrations (command files, workflows)
AI Agent (if applicable)
All agents
Use Cases
- A user opens an old project. A tool (or the agent itself) sees
metadata.version: "0.13.1"inspeckit-plan, compares it with the latest release, and suggestsspecify integration upgrade. - Someone debugging odd agent behaviour can see at a glance which Spec Kit, extension or preset version wrote each skill.
- General skill checkers, such as skill-check (a Claude Code plugin that warns when an outdated skill runs), can handle Spec Kit skills without Spec Kit-specific code. skill-check currently reads
.specify/integration.jsonas a workaround.
Acceptance Criteria
- Core skills generated by
specify initandspecify integration upgradeincludemetadata.versionequal toget_speckit_version(). - Extension skills include the extension's manifest version, including after a preset is removed and the extension skill is restored.
- Preset override skills include the preset's manifest version.
-
metadata.versionis left out when the version is unknown, and existing keys (author,source) are unchanged. - Tests cover each path (e.g. extend
tests/integrations/test_integration_base_skills.pyand the extension/preset skill tests). - Works for every skills-based integration, since they all share
build_skill_frontmatter.
Additional Context
- Discussion: Record the Spec Kit version in generated SKILL.md (metadata.version) #5400
- Function and call sites, as of 2ee2b1e:
src/specify_cli/agents.py(build_skill_frontmatter, and its use in command registration),src/specify_cli/integrations/{claude,alquimia,vibe}/__init__.py,src/specify_cli/extensions/__init__.py,src/specify_cli/presets/_manager_skills.py(four call sites). - A broader convention for
metadata.source/metadata.versionacross skill collections: https://github.com/louis8408/skill-check/blob/main/CONVENTION.md. This request doesn't depend on it.
I'm happy to send the PR if the approach looks right.
AI Disclosure
Drafted with Claude Code (Claude Opus 5.5), human-supervised: the AI read the Spec Kit source to find the call sites and wrote the draft; I reviewed and approved it before posting.
Activity
github-actions commentedon Nov 16, 2026
Feature assessment — skill-metadata-version · Stage 1/5: Intake
Idea Intake: Versioned SKILL.md Metadata
metadata.version#5423Idea (as captured)
Restated
Spec Kit should optionally stamp generated SKILL.md frontmatter with a version identifier so humans and tools can detect stale generated skills without parsing Spec Kit-internal files. The version should reflect the actual generator source (core CLI, extension, or preset) and remain backward compatible when unknown.
Origin & Context
#5400.First-Glance Unknowns
metadata.versionbe emitted as a quoted scalar in every integration path to avoid YAML numeric coercion edge cases?]metadata.versionas "legacy/unknown" and surface upgrade guidance automatically, or only expose raw metadata?]github-actions commentedon Nov 16, 2026
Feature assessment — skill-metadata-version · Stage 2/5: Research
Idea Research: Versioned SKILL.md Metadata
Users & Demand
metadata.version#5423 — [source: https://github.com/[Feature]: Record the generating version in SKILL.mdmetadata.version#5423] (confidence: medium, cited).metadata.version#5423] (confidence: medium, cited).metadata.version#5423 at assessment time) — [source: issue comments on [Feature]: Record the generating version in SKILL.mdmetadata.version#5423] (confidence: medium, cited).Prior Art
speckit_version), showing version provenance is already part of project metadata, but not exposed in every generated skill artifact — [source:src/specify_cli/command_init.py(init_opts["speckit_version"] = get_speckit_version())] (confidence: high, cited).CommandRegistrar.build_skill_frontmatter, currently emittingmetadata.authorandmetadata.sourceonly; this is a direct insertion point for an additive metadata key — [source:src/specify_cli/agents.py] (confidence: high, cited).source,author) for skill restoration, suggesting an established pattern for carrying extra provenance fields in restore records — [source:src/specify_cli/presets/_manager_skills.py_build_extension_skill_restore_index] (confidence: high, cited).tests/integrations/test_integration_base_skills.py,tests/specify_cli/presets/test_manager_skills.py,tests/test_extension_skills.py] (confidence: high, cited).Market & Context
metadata.version#5423] (confidence: medium, cited)..specify/integration.json) requires Spec Kit-specific parsing and does not naturally encode extension/preset provenance per skill — [source: https://github.com/[Feature]: Record the generating version in SKILL.mdmetadata.version#5423] (confidence: medium, cited).Data & Constraints
metadata.version#5423 andsrc/specify_cli/integrations/*/__init__.py,src/specify_cli/extensions/__init__.py,src/specify_cli/presets/_manager_skills.py] (confidence: high, cited).versionfields, making version source data available where those manifests are already loaded — [source:src/specify_cli/extensions/__init__.py(ExtensionManifestvalidation andversionproperty),src/specify_cli/presets/_manifest.py(PresetManifestvalidation andversionproperty)] (confidence: high, cited).metadata.version#5423] (confidence: medium, cited).Evidence Against the Idea
metadata.version#5423 issue/comments only] (confidence: medium, cited).src/specify_cli/presets/_manager_skills.py; ASSUMPTION] (confidence: medium, assumption).Gaps & Open Questions
metadata.version, or only generated ones?]Sources
metadata.version#5423 (host: github.com, policy: allowlisted)github-actions commentedon Nov 16, 2026
Feature assessment — skill-metadata-version · Stage 3/5: Problem
Problem Definition: Missing Version Provenance in Generated Skills
Problem Statement
Spec Kit-generated SKILL.md artifacts do not identify the generator version, so users and tooling cannot reliably detect stale skills or correlate unexpected behavior to the originating core/extension/preset release. This creates avoidable debugging friction and upgrade ambiguity when projects retain skills across long periods of Spec Kit evolution.
Affected Users & Stakeholders
Goals
Non-Goals
metadata.sourcevalues.Success Metrics
metadata.versionmatching the generating Spec Kit version (baseline: currently absent/unknown).author,source) remain unchanged and version is omitted when unknown (baseline: current behavior preserved).Cost of Inaction
Projects continue carrying opaque skills with no visible generation version, increasing support time, making stale-state diagnosis slower, and limiting interoperability with generic skill-check tooling that expects per-skill provenance.
Open Questions
github-actions commentedon Nov 16, 2026
Feature assessment — skill-metadata-version · Stage 4/5: Concept
Concept: Additive
metadata.versionfor Generated SkillsOptions
Option A — Additive metadata.version across shared generation paths
metadata.versiononly when known. Pass core Spec Kit version for built-in commands, extension manifest version for extension-generated skills, and preset manifest version for preset overrides/restores.Option B — Keep SKILL.md unchanged; rely on
.specify/integration.json+ docsOption C — Encode version in
metadata.sourceor body commentssource: extension:x v1.2.3) or markdown comments rather than a dedicated metadata key.source, inconsistent formatting across call paths, ambiguous backwards compatibility.Recommendation
Recommend Option A. It directly solves the reported provenance gap with minimal conceptual scope, aligns with existing centralized frontmatter generation, and preserves backward compatibility via optional emission when version is unknown.
Out of Scope (for the recommended option)
metadata.source.Assumptions to Validate
github-actions commentedon Nov 16, 2026
Feature assessment — skill-metadata-version · Stage 5/5: Decision — verdict go
Decision: Version-Provenance Metadata for Generated Skills
Scorecard
Verdict & Rationale
Go. The problem is real, the solution concept is small and additive, and the expected value (clear per-skill provenance for stale-skill detection/debugging) outweighs implementation risk. Evidence is not broad market telemetry, but it is sufficient and concrete for this scoped infrastructure improvement, and the identified risks are manageable via targeted tests.
If needs-clarification
If go — Handoff to
/speckit-specifymetadata.versionthrough shared skill frontmatter generation and pass version by origin (core/extension/preset).fix(skills): persist generator version in SKILL.md metadata (github#5423