Skip to content

[Feature]: Record the generating version in SKILL.md metadata.version #5423

Backlog

Description

@louis8408

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 check covers the CLI, not the files generated in each project.
  • .specify/integration.json records the version, but it's Spec Kit-specific. SKILL.md is 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. metadata is the Agent Skills spec's free-form string map for exactly this, and agents that don't use a key ignore it.
  • Change source to an absolute URL (e.g. pinned to the release tag). Possible later, but it changes the meaning of an existing field. version is additive and covers the main need.

Component

Agent integrations (command files, workflows)

AI Agent (if applicable)

All agents

Use Cases

  1. A user opens an old project. A tool (or the agent itself) sees metadata.version: "0.13.1" in speckit-plan, compares it with the latest release, and suggests specify integration upgrade.
  2. Someone debugging odd agent behaviour can see at a glance which Spec Kit, extension or preset version wrote each skill.
  3. 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.json as a workaround.

Acceptance Criteria

  • Core skills generated by specify init and specify integration upgrade include metadata.version equal to get_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.version is 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.py and the extension/preset skill tests).
  • Works for every skills-based integration, since they all share build_skill_frontmatter.

Additional Context

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

  1. added
    triage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review
    feature-assessRun the Spec Kit idea-assessment pipeline on this feature request
    on Nov 13, 2026
  2. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — skill-metadata-version · Stage 1/5: Intake

    Idea Intake: Versioned SKILL.md Metadata

    Idea (as captured)

    A project can keep generated SKILL.md files for months while Spec Kit moves on, and the skill file does not show which Spec Kit/extension/preset version generated it.
    Proposal: add optional metadata.version in skill frontmatter (alongside metadata.author and metadata.source) via CommandRegistrar.build_skill_frontmatter, with callers passing:

    • core command skills: get_speckit_version()
    • extension skills: ExtensionManifest.version
    • preset override skills: PresetManifest.version
    • omit key when unknown
      Acceptance criteria include preserving current behavior when version is unknown and adding coverage for core, extension, and preset restore paths.

    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

    • Raised by: @louis8408
    • Trigger: A real stale-skill mismatch (project generated with an older dev build while newer Spec Kit release existed) and follow-up from discussion #5400.

    First-Glance Unknowns

    • [NEEDS CLARIFICATION: Should metadata.version be emitted as a quoted scalar in every integration path to avoid YAML numeric coercion edge cases?]
    • [NEEDS CLARIFICATION: For restore paths, should extension/preset version be persisted in registry provenance or re-derived from currently installed manifest data at restore time?]
    • [NEEDS CLARIFICATION: Should tooling treat missing metadata.version as "legacy/unknown" and surface upgrade guidance automatically, or only expose raw metadata?]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5423 · copilot · gpt53codex · 59.9 AIC · ⌖ 0.763 AIC · ⊞ 26.4K · ◷

  3. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — skill-metadata-version · Stage 2/5: Research

    Idea Research: Versioned SKILL.md Metadata

    • Slug: skill-metadata-version
    • Created: 2026-11-16T14:42:09Z
    • Evidence confidence (overall): medium

    Users & Demand

    Prior Art

    • Core project state already records Spec Kit version in init options (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).
    • Shared skill frontmatter generation is centralized in CommandRegistrar.build_skill_frontmatter, currently emitting metadata.author and metadata.source only; this is a direct insertion point for an additive metadata key — [source: src/specify_cli/agents.py] (confidence: high, cited).
    • Preset extension-restore indexing already persists extension-origin metadata (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).
    • Existing tests enforce metadata structure and source/author presence, indicating test scaffolding exists for extending metadata assertions without inventing a new testing pattern — [source: 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

    Data & Constraints

    • Technical scope is narrowly bounded: one shared frontmatter builder plus known integration/extension/preset call paths named in the request — [source: https://github.com/[Feature]: Record the generating version in SKILL.md metadata.version #5423 and src/specify_cli/integrations/*/__init__.py, src/specify_cli/extensions/__init__.py, src/specify_cli/presets/_manager_skills.py] (confidence: high, cited).
    • Extension and preset manifests both require semantic version fields, making version source data available where those manifests are already loaded — [source: src/specify_cli/extensions/__init__.py (ExtensionManifest validation and version property), src/specify_cli/presets/_manifest.py (PresetManifest validation and version property)] (confidence: high, cited).
    • Backward compatibility constraint: key should be omitted when unknown to avoid breaking callers that assume today's schema — [source: https://github.com/[Feature]: Record the generating version in SKILL.md metadata.version #5423] (confidence: medium, cited).

    Evidence Against the Idea

    • Demand evidence is currently thin (single issue reporter, no corroborating comments or telemetry in this thread), so urgency relative to other work is uncertain — [source: [Feature]: Record the generating version in SKILL.md metadata.version #5423 issue/comments only] (confidence: medium, cited).
    • Additional metadata propagation through preset/extension restore paths can create subtle consistency obligations (e.g., stale persisted provenance vs. current manifests) if not covered comprehensively by tests — [source: restore path behavior in src/specify_cli/presets/_manager_skills.py; ASSUMPTION] (confidence: medium, assumption).

    Gaps & Open Questions

    • [NEEDS CLARIFICATION: Preferred source of truth when restore-time manifest version differs from persisted metadata version (keep original writer version vs. refresh to current installed version)?]
    • [NEEDS CLARIFICATION: Should non-Spec-Kit authored skills that pass through shared utilities ever emit metadata.version, or only generated ones?]
    • [NEEDS CLARIFICATION: Is there any compatibility concern with integrations/consumers that validate a strict metadata key set?]

    Sources

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5423 · copilot · gpt53codex · 59.9 AIC · ⌖ 0.763 AIC · ⊞ 26.4K · ◷

  4. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — skill-metadata-version · Stage 3/5: Problem

    Problem Definition: Missing Version Provenance in Generated Skills

    • Slug: skill-metadata-version
    • Created: 2026-11-16T14:42:09Z
    • Inputs used: intake.md | research.md

    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

    • Users: Maintainers and contributors operating long-lived Spec Kit projects — they cannot quickly tell whether a skill file is outdated or which generator produced it.
    • Users: External tooling/agent ecosystems that consume SKILL.md directly — they need machine-readable provenance without parsing Spec Kit-internal files.
    • Stakeholders: Spec Kit maintainers — they bear support/debug burden when behavior diverges due to stale generated artifacts.

    Goals

    • Provide machine-readable version provenance in generated SKILL.md metadata.
    • Preserve existing generated-skill behavior when a reliable version is unavailable.
    • Keep provenance consistent across core, extension, and preset skill-generation paths.
    • Improve debuggability and upgrade discoverability for long-lived projects.

    Non-Goals

    • Redesigning the entire skill metadata schema beyond additive provenance.
    • Defining a full automatic upgrade policy or enforcement mechanism for stale skills.
    • Introducing architecture/API redesign of assessment or integration systems.
    • Changing the semantic meaning of existing metadata.source values.

    Success Metrics

    • Generated core skills include metadata.version matching the generating Spec Kit version (baseline: currently absent/unknown).
    • Generated extension skills include extension manifest version, including restore paths after preset removal (baseline: currently absent/unknown).
    • Generated preset override skills include preset manifest version (baseline: currently absent/unknown).
    • Existing metadata keys (author, source) remain unchanged and version is omitted when unknown (baseline: current behavior preserved).
    • Regression coverage exists for all major generation paths (baseline: tests currently validate metadata structure but not version key).

    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

    • [NEEDS CLARIFICATION: Canonical behavior when restore-time installed version differs from the version that originally generated a skill.]
    • [NEEDS CLARIFICATION: Whether any consumer currently rejects additional metadata keys and would require compatibility communication.]
    • [NEEDS CLARIFICATION: Minimum required test matrix across integrations to consider provenance behavior complete.]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5423 · copilot · gpt53codex · 59.9 AIC · ⌖ 0.763 AIC · ⊞ 26.4K · ◷

  5. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — skill-metadata-version · Stage 4/5: Concept

    Concept: Additive metadata.version for Generated Skills

    • Slug: skill-metadata-version
    • Created: 2026-11-16T14:42:09Z
    • Recommended option: Option A — Additive metadata.version across shared skill-generation paths

    Options

    Option A — Additive metadata.version across shared generation paths

    • Sketch: Extend shared skill frontmatter generation to accept optional version provenance and emit metadata.version only 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.
    • Appetite: small
    • Trade-offs: High compatibility (additive key, no change to existing key semantics) and strong machine readability; requires careful plumbing through several call sites and restore metadata paths.
    • Rabbit holes: Subtle restore-path provenance consistency (persisted vs. current manifest version), and making sure quoted serialization is stable across integrations.

    Option B — Keep SKILL.md unchanged; rely on .specify/integration.json + docs

    • Sketch: Avoid SKILL.md metadata changes and continue using project-level integration metadata for version visibility, possibly adding docs/tooling guidance for consumers.
    • Appetite: small
    • Trade-offs: Lowest implementation risk; does not satisfy per-skill provenance use cases and keeps external tooling coupled to Spec Kit internals.
    • Rabbit holes: Ongoing support burden and repeated user confusion remain; extension/preset provenance still not represented per skill.

    Option C — Encode version in metadata.source or body comments

    • Sketch: Embed version in existing source text (e.g., source: extension:x v1.2.3) or markdown comments rather than a dedicated metadata key.
    • Appetite: medium
    • Trade-offs: Avoids new metadata key but overloads existing semantics and is less reliable for machine parsing consistency.
    • Rabbit holes: Breaking assumptions for tools that parse 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)

    • Automatic stale-skill upgrade execution.
    • New policy layers beyond emitting provenance metadata.
    • Broad metadata schema redesign or replacing metadata.source.
    • Detailed implementation design/task breakdown (deferred to specification).

    Assumptions to Validate

    • Existing skill consumers tolerate additive metadata keys.
    • Extension/preset version values are reliably available at every generation/restore call site.
    • YAML/frontmatter serialization remains stable and quoted where required.
    • Test coverage can be expanded without cross-integration brittleness.

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5423 · copilot · gpt53codex · 59.9 AIC · ⌖ 0.763 AIC · ⊞ 26.4K · ◷

  6. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — skill-metadata-version · Stage 5/5: Decision — verdict go

    Decision: Version-Provenance Metadata for Generated Skills

    • Slug: skill-metadata-version
    • Decided: 2026-11-16T14:42:09Z
    • Verdict: go
    • Artifacts reviewed: intake.md | research.md | problem.md | concept.md

    Scorecard

    Criterion Rating Justification
    Problem validity strong The issue describes a concrete stale-skill debugging pain and clear operational impact in long-lived projects.
    Evidence strength adequate Evidence is grounded in real issue context plus repository code/test inspection, though user-demand breadth is limited.
    Value vs. inaction strong Additive provenance directly reduces support/debug ambiguity; doing nothing preserves known friction.
    Feasibility / appetite strong Change is narrowly scoped to centralized frontmatter generation and known call paths, with existing test scaffolding.
    Strategic fit adequate Improves reliability/interoperability of generated artifacts and aligns with maintainability goals for multi-agent integrations.
    Risk posture adequate Main risks (restore-path consistency, serialization compatibility) are identifiable and testable with bounded scope.

    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

    • Blocking questions: [NEEDS CLARIFICATION: none]
    • Revisit stage: shape

    If go — Handoff to /speckit-specify

    • Problem: Generated SKILL.md files lack generator-version provenance, making stale-skill detection and debugging difficult.
    • Chosen approach: Add optional metadata.version through shared skill frontmatter generation and pass version by origin (core/extension/preset).
    • In scope / out of scope: In scope is additive metadata emission plus restore-path coverage; out of scope is auto-upgrade orchestration and schema redesign beyond this key.
    • Success metrics: Core/extension/preset generated skills emit correct version metadata when known; key omitted when unknown; existing metadata keys unchanged; tests cover all major paths.
    • Carried-forward open questions:
      • [NEEDS CLARIFICATION: whether restore should preserve original writer version vs. current installed manifest version when they differ]
      • [NEEDS CLARIFICATION: confirm no strict consumer rejects additive metadata keys]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5423 · copilot · gpt53codex · 59.9 AIC · ⌖ 0.763 AIC · ⊞ 26.4K · ◷

  7. added
    feature-goFeature assessment verdict: go — ready to hand off to /speckit.specify
    on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature-assessRun the Spec Kit idea-assessment pipeline on this feature requestfeature-goFeature assessment verdict: go — ready to hand off to /speckit.specifytriage-nice-to-haveVerdict: evidence-backed fix or greenlit feature — land after review

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions