Skills generation drift: native skills vs install_ai_skills vs extension overrides (frontmatter + naming)

[RbBtSn0w]

We recently started moving some agents (e.g. Codex) to native skills (.agents/skills/<skill>/SKILL.md) instead of extracting prompt/command templates.

While investigating hooks vs skills invocation (#1918), another issue surfaced: Spec-kit currently has multiple SKILL.md generators, and they can drift.

Current generators

1. Native skills in template zip (release packaging scripts)

   • .github/workflows/scripts/create-release-packages.sh / .ps1
   • Generates SKILL.md during CI packaging.

2. Init-time conversion (install_ai_skills())

   • Converts extracted speckit.*.md command templates into skills/<name>/SKILL.md.
   • Adds skills-oriented frontmatter (compatibility, metadata.source, enhanced descriptions, etc).

3. Extension/preset overrides (agents.CommandRegistrar.render_skill_command())

   • Writes skill overrides for skills-target agents when installing extensions/presets.

Why this matters

If these generators don’t share the same frontmatter schema + naming rules, we get subtle inconsistencies:

• Missing compatibility / metadata.source in some skills
• Different description quality depending on which generator produced the skill
• Naming mismatch between logical command_id (often dotted, e.g. speckit.plan) and runtime skill_name (hyphenated for Codex, dotted for Kimi)

This becomes more important as agents converge on skills, and as hooks/extensions rely on consistent command identifiers.

Suggested direction (discussion)

• Decide what is the canonical identifier:

  • keep dotted speckit.plan as a stable logical command_id, and map to agent-specific skill names/invocation strings
  • or migrate everything to hyphen-only skill names (and define migration + compatibility story)

• Decide how to prevent drift:

  • minimal patch: enforce a required SKILL.md frontmatter contract (name/description/compatibility/metadata.source) across all generators + tests
  • larger refactor: centralize skills generation in Python (used by init conversion, extension overrides, and release packaging)

Linking to the hook/invocation discussion because they’re related: #1918

[mnriem]

PR #1925 is in flight to address how agents install / uinstall themselves and how to use shared functionality among that the skill generation. Please have a look at it to see if it can address this concern.