fix: clarify skills frontmatter contract and AGENTS sections

Author: RbBtSn0w

.github/workflows/scripts/create-release-packages.ps1

@@ -207,7 +207,7 @@ agent: $basename
 #
 # Technical debt note:
 # Keep SKILL.md frontmatter aligned with `install_ai_skills()` and extension
-# overrides (at minimum: name/description/compatibility/metadata.source).
+# overrides (at minimum: name/description/compatibility/metadata.{author,source}).
 function New-Skills {
     param(
         [string]$SkillsDir,

.github/workflows/scripts/create-release-packages.sh

@@ -127,7 +127,7 @@ EOF
 #
 # Technical debt note:
 # Keep SKILL.md frontmatter aligned with `install_ai_skills()` and extension
-# overrides (at minimum: name/description/compatibility/metadata.source).
+# overrides (at minimum: name/description/compatibility/metadata.{author,source}).
 create_skills() {
   local skills_dir="$1"
   local script_variant="$2"

AGENTS.md

@@ -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: `.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

@@ -1225,7 +1225,7 @@ def load_init_options(project_path: Path) -> dict[str, Any]:
 #   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.source).
+#   (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"}
 

src/specify_cli/agents.py

@@ -302,8 +302,8 @@ def render_skill_command(
         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) to
-        avoid drift across agents.
+        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 = {}