fix: Align native skills frontmatter with install_ai_skills (#1920)

* docs(sdk): align native skills frontmatter + document multi-generator drift

* fix: clarify skills frontmatter contract and AGENTS sections

.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
     }
 }

.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"

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**:
+- **Skills-based exceptions**:
-  - Codex: `.codex/prompts/`
+  - Codex: `.agents/skills/` (skills, invoked as `$speckit-<command>`)
+- **Prompt-based exceptions**:
   - Kiro CLI: `.kiro/prompts/`
   - Pi: `.pi/prompts/`
 - **IDE agents**: Follow IDE-specific patterns:

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 skill

src/specify_cli/agents.py

@@ -298,6 +298,12 @@ class CommandRegistrar:
         SKILL-target agents should receive the same skills-oriented
         frontmatter shape used elsewhere in the project instead of the
         original 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 = {}