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

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 = {}