💫 Toolkit to help you get started with SDD or any other process!
fix: Align native skills frontmatter with install_ai_skills (#1920)
Hamilton Snow191f33213c4b
diff --git a/.github/workflows/scripts/create-release-packages.ps1 b/.github/workflows/scripts/create-release-packages.ps1index 80c2ef021..8f3cfec36 100644--- a/.github/workflows/scripts/create-release-packages.ps1+++ b/.github/workflows/scripts/create-release-packages.ps1@@ -204,6 +204,10 @@ agent: $basename# Create skills in <skills_dir>\<name>\SKILL.md format.# Most agents use hyphenated names (e.g. speckit-plan); Kimi is the# current dotted-name exception (e.g. speckit.plan).+#+# Technical debt note:+# Keep SKILL.md frontmatter aligned with `install_ai_skills()` and extension+# overrides (at minimum: name/description/compatibility/metadata.{author,source}).function New-Skills {param([string]$SkillsDir,@@ -285,7 +289,7 @@ function New-Skills {if ($inBody) { $templateBody += "$line`n" }}- $skillContent = "---`nname: `"$skillName`"`ndescription: `"$description`"`n---`n`n$templateBody"+ $skillContent = "---`nname: `"$skillName`"`ndescription: `"$description`"`ncompatibility: `"Requires spec-kit project structure with .specify/ directory`"`nmetadata:`n author: `"github-spec-kit`"`n source: `"templates/commands/$name.md`"`n---`n`n$templateBody"Set-Content -Path (Join-Path $skillDir "SKILL.md") -Value $skillContent -NoNewline}}diff --git a/.github/workflows/scripts/create-release-packages.sh b/.github/workflows/scripts/create-release-packages.shindex fedf84147..c2bd792fd 100755--- a/.github/workflows/scripts/create-release-packages.sh+++ b/.github/workflows/scripts/create-release-packages.sh@@ -124,6 +124,10 @@ EOF# Create skills in <skills_dir>/<name>/SKILL.md format.# Most agents use hyphenated names (e.g. speckit-plan); Kimi is the# current dotted-name exception (e.g. speckit.plan).+#+# Technical debt note:+# Keep SKILL.md frontmatter aligned with `install_ai_skills()` and extension+# overrides (at minimum: name/description/compatibility/metadata.{author,source}).create_skills() {local skills_dir="$1"local script_variant="$2"@@ -187,6 +191,10 @@ create_skills() {printf -- '---\n'printf 'name: "%s"\n' "$skill_name"printf 'description: "%s"\n' "$description"+ printf 'compatibility: "%s"\n' "Requires spec-kit project structure with .specify/ directory"+ printf -- 'metadata:\n'+ printf ' author: "%s"\n' "github-spec-kit"+ printf ' source: "%s"\n' "templates/commands/${name}.md"printf -- '---\n\n'printf '%s\n' "$template_body"} > "$skill_dir/SKILL.md"diff --git a/AGENTS.md b/AGENTS.mdindex a48fb15ff..a15e0bc4b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -33,7 +33,7 @@ Specify supports multiple AI agents by generating agent-specific command files a| **Cursor** | `.cursor/commands/` | Markdown | `cursor-agent` | Cursor CLI || **Qwen Code** | `.qwen/commands/` | Markdown | `qwen` | Alibaba's Qwen Code CLI || **opencode** | `.opencode/command/` | Markdown | `opencode` | opencode CLI |-| **Codex CLI** | `.codex/prompts/` | Markdown | `codex` | Codex CLI |+| **Codex CLI** | `.agents/skills/` | Markdown | `codex` | Codex CLI (skills) || **Windsurf** | `.windsurf/workflows/` | Markdown | N/A (IDE-based) | Windsurf IDE workflows || **Junie** | `.junie/commands/` | Markdown | `junie` | Junie by JetBrains || **Kilo Code** | `.kilocode/workflows/` | Markdown | N/A (IDE-based) | Kilo Code IDE |@@ -379,8 +379,9 @@ Command content with {SCRIPT} and {{args}} placeholders.## Directory Conventions- **CLI agents**: Usually `.<agent-name>/commands/`-- **Common prompt-based exceptions**:- - Codex: `.codex/prompts/`+- **Skills-based exceptions**:+ - Codex: `.agents/skills/` (skills, invoked as `$speckit-<command>`)+- **Prompt-based exceptions**:- Kiro CLI: `.kiro/prompts/`- Pi: `.pi/prompts/`- **IDE agents**: Follow IDE-specific patterns:diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex da96c07e8..ae64d19c7 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -1218,6 +1218,15 @@ AGENT_SKILLS_DIR_OVERRIDES = {DEFAULT_SKILLS_DIR = ".agents/skills"# Agents whose downloaded template already contains skills in the final layout.+#+# Technical debt note:+# - Spec-kit currently has multiple SKILL.md generators:+# 1) release packaging scripts that build the template zip (native skills),+# 2) `install_ai_skills()` which converts extracted command templates to skills,+# 3) extension/preset overrides via `agents.CommandRegistrar.render_skill_command()`.+# - Keep the skills frontmatter schema aligned across all generators+# (at minimum: name/description/compatibility/metadata.{author,source}).+# - When adding fields here, update the release scripts and override writers too.NATIVE_SKILLS_AGENTS = {"codex", "kimi"}# Enhanced descriptions for each spec-kit command skilldiff --git a/src/specify_cli/agents.py b/src/specify_cli/agents.pyindex 10b2c7484..4f1ab728f 100644--- a/src/specify_cli/agents.py+++ b/src/specify_cli/agents.py@@ -298,6 +298,12 @@ class CommandRegistrar:SKILL-target agents should receive the same skills-orientedfrontmatter shape used elsewhere in the project instead of theoriginal command frontmatter.++ Technical debt note:+ Spec-kit currently has multiple SKILL.md generators (template packaging,+ init-time conversion, and extension/preset overrides). Keep the skill+ frontmatter keys aligned (name/description/compatibility/metadata, with+ metadata.author and metadata.source subkeys) to avoid drift across agents."""if not isinstance(frontmatter, dict):frontmatter = {}