Align Claude skill frontmatter across generators

Author: afurm

src/specify_cli/__init__.py

@@ -1640,6 +1640,8 @@ def install_ai_skills(
         ``True`` if at least one skill was installed or all skills were
         already present (idempotent re-run), ``False`` otherwise.
     """
+    from .agents import CommandRegistrar
+
     # Locate command templates in the agent's extracted commands directory.
     # download_and_extract_template() already placed the .md files here.
     agent_config = AGENT_CONFIG.get(selected_ai, {})
@@ -1741,15 +1743,12 @@ def install_ai_skills(
             if source_name.endswith(".agent.md"):
                 source_name = source_name[:-len(".agent.md")] + ".md"
 
-            frontmatter_data = {
-                "name": skill_name,
-                "description": enhanced_desc,
-                "compatibility": "Requires spec-kit project structure with .specify/ directory",
-                "metadata": {
-                    "author": "github-spec-kit",
-                    "source": f"templates/commands/{source_name}",
-                },
-            }
+            frontmatter_data = CommandRegistrar.build_skill_frontmatter(
+                selected_ai,
+                skill_name,
+                enhanced_desc,
+                f"templates/commands/{source_name}",
+            )
             frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
             skill_content = (
                 f"---\n"

src/specify_cli/agents.py

@@ -364,16 +364,35 @@ def render_skill_command(
             body = self.resolve_skill_placeholders(agent_name, frontmatter, body, project_root)
 
         description = frontmatter.get("description", f"Spec-kit workflow command: {skill_name}")
+        skill_frontmatter = self.build_skill_frontmatter(
+            agent_name,
+            skill_name,
+            description,
+            f"{source_id}:{source_file}",
+        )
+        return self.render_frontmatter(skill_frontmatter) + "\n" + body
+
+    @staticmethod
+    def build_skill_frontmatter(
+        agent_name: str,
+        skill_name: str,
+        description: str,
+        source: str,
+    ) -> dict:
+        """Build consistent SKILL.md frontmatter across all skill generators."""
         skill_frontmatter = {
             "name": skill_name,
             "description": description,
             "compatibility": "Requires spec-kit project structure with .specify/ directory",
             "metadata": {
                 "author": "github-spec-kit",
-                "source": f"{source_id}:{source_file}",
+                "source": source,
             },
         }
-        return self.render_frontmatter(skill_frontmatter) + "\n" + body
+        if agent_name == "claude":
+            # Claude skills should only run when explicitly invoked.
+            skill_frontmatter["disable-model-invocation"] = True
+        return skill_frontmatter
 
     @staticmethod
     def resolve_skill_placeholders(agent_name: str, frontmatter: dict, body: str, project_root: Path) -> str:

src/specify_cli/extensions.py

@@ -801,15 +801,12 @@ def _register_extension_skills(
             original_desc = frontmatter.get("description", "")
             description = original_desc or f"Extension command: {cmd_name}"
 
-            frontmatter_data = {
-                "name": skill_name,
-                "description": description,
-                "compatibility": "Requires spec-kit project structure with .specify/ directory",
-                "metadata": {
-                    "author": "github-spec-kit",
-                    "source": f"extension:{manifest.id}",
-                },
-            }
+            frontmatter_data = registrar.build_skill_frontmatter(
+                selected_ai,
+                skill_name,
+                description,
+                f"extension:{manifest.id}",
+            )
             frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
 
             # Derive a human-friendly title from the command name

src/specify_cli/integrations/claude/__init__.py

@@ -43,17 +43,12 @@ def _render_skill(self, template_name: str, frontmatter: dict[str, Any], body: s
             "description",
             f"Spec-kit workflow command: {template_name}",
         )
-        skill_frontmatter = {
-            "name": skill_name,
-            "description": description,
-            # Spec-kit workflows should only run when explicitly invoked.
-            "disable-model-invocation": True,
-            "compatibility": "Requires spec-kit project structure with .specify/ directory",
-            "metadata": {
-                "author": "github-spec-kit",
-                "source": f"templates/commands/{template_name}.md",
-            },
-        }
+        skill_frontmatter = CommandRegistrar.build_skill_frontmatter(
+            self.key,
+            skill_name,
+            description,
+            f"templates/commands/{template_name}.md",
+        )
         frontmatter_text = yaml.safe_dump(skill_frontmatter, sort_keys=False).strip()
         return f"---\n{frontmatter_text}\n---\n\n{body.strip()}\n"
 

src/specify_cli/presets.py

@@ -771,15 +771,12 @@ def _register_skills(
                 if skill_subdir.exists() and not skill_subdir.is_dir():
                     continue
                 skill_subdir.mkdir(parents=True, exist_ok=True)
-                frontmatter_data = {
-                    "name": target_skill_name,
-                    "description": enhanced_desc,
-                    "compatibility": "Requires spec-kit project structure with .specify/ directory",
-                    "metadata": {
-                        "author": "github-spec-kit",
-                        "source": f"preset:{manifest.id}",
-                    },
-                }
+                frontmatter_data = registrar.build_skill_frontmatter(
+                    selected_ai,
+                    target_skill_name,
+                    enhanced_desc,
+                    f"preset:{manifest.id}",
+                )
                 frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
                 skill_content = (
                     f"---\n"
@@ -861,15 +858,12 @@ def _unregister_skills(self, skill_names: List[str], preset_dir: Path) -> None:
                     original_desc or f"Spec-kit workflow command: {short_name}",
                 )
 
-                frontmatter_data = {
-                    "name": skill_name,
-                    "description": enhanced_desc,
-                    "compatibility": "Requires spec-kit project structure with .specify/ directory",
-                    "metadata": {
-                        "author": "github-spec-kit",
-                        "source": f"templates/commands/{short_name}.md",
-                    },
-                }
+                frontmatter_data = registrar.build_skill_frontmatter(
+                    selected_ai if isinstance(selected_ai, str) else "",
+                    skill_name,
+                    enhanced_desc,
+                    f"templates/commands/{short_name}.md",
+                )
                 frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
                 skill_title = self._skill_title_from_command(short_name)
                 skill_content = (
@@ -894,15 +888,12 @@ def _unregister_skills(self, skill_names: List[str], preset_dir: Path) -> None:
                 command_name = extension_restore["command_name"]
                 title_name = self._skill_title_from_command(command_name)
 
-                frontmatter_data = {
-                    "name": skill_name,
-                    "description": frontmatter.get("description", f"Extension command: {command_name}"),
-                    "compatibility": "Requires spec-kit project structure with .specify/ directory",
-                    "metadata": {
-                        "author": "github-spec-kit",
-                        "source": extension_restore["source"],
-                    },
-                }
+                frontmatter_data = registrar.build_skill_frontmatter(
+                    selected_ai if isinstance(selected_ai, str) else "",
+                    skill_name,
+                    frontmatter.get("description", f"Extension command: {command_name}"),
+                    extension_restore["source"],
+                )
                 frontmatter_text = yaml.safe_dump(frontmatter_data, sort_keys=False).strip()
                 skill_content = (
                     f"---\n"

tests/integrations/test_integration_claude.py

@@ -284,6 +284,7 @@ def test_claude_preset_creates_new_skill_without_commands_dir(self, tmp_path):
         content = skill_file.read_text(encoding="utf-8")
         assert "preset:claude-skill-command" in content
         assert "name: speckit-research" in content
+        assert "disable-model-invocation: true" in content
 
         metadata = manager.registry.get("claude-skill-command")
         assert "speckit-research" in metadata.get("registered_skills", [])

tests/test_extension_skills.py

@@ -269,6 +269,7 @@ def test_skill_md_has_parseable_yaml(self, skills_project, extension_dir):
         assert isinstance(parsed, dict)
         assert parsed["name"] == "speckit-test-ext-hello"
         assert "description" in parsed
+        assert parsed["disable-model-invocation"] is True
 
     def test_no_skills_when_ai_skills_disabled(self, no_skills_project, extension_dir):
         """No skills should be created when ai_skills is false."""

tests/test_presets.py

@@ -1974,6 +1974,7 @@ def test_skill_overridden_on_preset_install(self, project_dir, temp_dir):
         assert skill_file.exists()
         content = skill_file.read_text()
         assert "preset:self-test" in content, "Skill should reference preset source"
+        assert "disable-model-invocation: true" in content
 
         # Verify it was recorded in registry
         metadata = manager.registry.get("self-test")
@@ -2059,6 +2060,7 @@ def test_skill_restored_on_preset_remove(self, project_dir, temp_dir):
         content = skill_file.read_text()
         assert "preset:self-test" not in content, "Preset content should be gone"
         assert "templates/commands/specify.md" in content, "Should reference core template"
+        assert "disable-model-invocation: true" in content
 
     def test_skill_restored_on_remove_resolves_script_placeholders(self, project_dir):
         """Core restore should resolve {SCRIPT}/{ARGS} placeholders like other skill paths."""