Merge branch 'main' into feature/add-forgecode-agent-support

src/specify_cli/agents.py

@@ -15,6 +15,18 @@ from copy import deepcopy
 import yaml
 
 
+def _build_agent_configs() -> dict[str, Any]:
+    """Derive CommandRegistrar.AGENT_CONFIGS from INTEGRATION_REGISTRY."""
+    from specify_cli.integrations import INTEGRATION_REGISTRY
+    configs: dict[str, dict[str, Any]] = {}
+    for key, integration in INTEGRATION_REGISTRY.items():
+        if key == "generic":
+            continue
+        if integration.registrar_config:
+            configs[key] = dict(integration.registrar_config)
+    return configs
+
+
 class CommandRegistrar:
     """Handles registration of commands with AI agents.
 
@@ -23,161 +35,26 @@ class CommandRegistrar:
     and companion files (e.g. Copilot .prompt.md).
     """
 
-    # Agent configurations with directory, format, and argument placeholder
-    AGENT_CONFIGS = {
-        "claude": {
-            "dir": ".claude/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "gemini": {
-            "dir": ".gemini/commands",
-            "format": "toml",
-            "args": "{{args}}",
-            "extension": ".toml"
-        },
-        "copilot": {
-            "dir": ".github/agents",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".agent.md"
-        },
-        "cursor-agent": {
-            "dir": ".cursor/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "qwen": {
-            "dir": ".qwen/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "opencode": {
-            "dir": ".opencode/command",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "codex": {
-            "dir": ".agents/skills",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": "/SKILL.md",
-        },
-        "windsurf": {
-            "dir": ".windsurf/workflows",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "junie": {
-            "dir": ".junie/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "kilocode": {
-            "dir": ".kilocode/workflows",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "auggie": {
-            "dir": ".augment/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "roo": {
-            "dir": ".roo/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "codebuddy": {
-            "dir": ".codebuddy/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "qodercli": {
-            "dir": ".qoder/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "kiro-cli": {
-            "dir": ".kiro/prompts",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "pi": {
-            "dir": ".pi/prompts",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "amp": {
-            "dir": ".agents/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "shai": {
-            "dir": ".shai/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "tabnine": {
-            "dir": ".tabnine/agent/commands",
-            "format": "toml",
-            "args": "{{args}}",
-            "extension": ".toml"
-        },
-        "bob": {
-            "dir": ".bob/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "kimi": {
-            "dir": ".kimi/skills",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": "/SKILL.md",
-        },
-        "trae": {
-            "dir": ".trae/rules",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "iflow": {
-            "dir": ".iflow/commands",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        },
-        "forge": {
-            "dir": ".forge/commands",
-            "format": "markdown",
-            "args": "{{parameters}}",
-            "extension": ".md",
-            "strip_frontmatter_keys": ["handoffs"],
-            "inject_name": True,
-        },
-        "vibe": {
-            "dir": ".vibe/prompts",
-            "format": "markdown",
-            "args": "$ARGUMENTS",
-            "extension": ".md"
-        }
-    }
+    # Derived from INTEGRATION_REGISTRY — single source of truth.
+    # Populated lazily via _ensure_configs() on first use.
+    AGENT_CONFIGS: dict[str, dict[str, Any]] = {}
+    _configs_loaded: bool = False
+
+    def __init__(self) -> None:
+        self._ensure_configs()
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._ensure_configs()
+
+    @classmethod
+    def _ensure_configs(cls) -> None:
+        if not cls._configs_loaded:
+            try:
+                cls.AGENT_CONFIGS = _build_agent_configs()
+                cls._configs_loaded = True
+            except ImportError:
+                pass  # Circular import during module init; retry on next access
 
     @staticmethod
     def parse_frontmatter(content: str) -> tuple[dict, str]:
@@ -372,16 +249,35 @@ class CommandRegistrar:
             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:
@@ -489,6 +385,7 @@ class CommandRegistrar:
         Raises:
             ValueError: If agent is not supported
         """
+        self._ensure_configs()
         if agent_name not in self.AGENT_CONFIGS:
             raise ValueError(f"Unsupported agent: {agent_name}")
 
@@ -545,12 +442,12 @@ class CommandRegistrar:
 
             for alias in cmd_info.get("aliases", []):
                 alias_output_name = self._compute_output_name(agent_name, alias, agent_config)
-                
+
                 # For agents with inject_name, render with alias-specific frontmatter
                 if agent_config.get("inject_name"):
                     alias_frontmatter = deepcopy(frontmatter)
                     alias_frontmatter["name"] = alias
-                    
+
                     if agent_config["extension"] == "/SKILL.md":
                         alias_output = self.render_skill_command(
                             agent_name, alias_output_name, alias_frontmatter, body, source_id, cmd_file, project_root
@@ -568,7 +465,7 @@ class CommandRegistrar:
                         alias_output = self.render_skill_command(
                             agent_name, alias_output_name, frontmatter, body, source_id, cmd_file, project_root
                         )
-                
+
                 alias_file = commands_dir / f"{alias_output_name}{agent_config['extension']}"
                 alias_file.parent.mkdir(parents=True, exist_ok=True)
                 alias_file.write_text(alias_output, encoding="utf-8")
@@ -613,6 +510,7 @@ class CommandRegistrar:
         """
         results = {}
 
+        self._ensure_configs()
         for agent_name, agent_config in self.AGENT_CONFIGS.items():
             agent_dir = project_root / agent_config["dir"]
 
@@ -640,6 +538,7 @@ class CommandRegistrar:
             registered_commands: Dict mapping agent names to command name lists
             project_root: Path to project root
         """
+        self._ensure_configs()
         for agent_name, cmd_names in registered_commands.items():
             if agent_name not in self.AGENT_CONFIGS:
                 continue
@@ -657,3 +556,12 @@ class CommandRegistrar:
                     prompt_file = project_root / ".github" / "prompts" / f"{cmd_name}.prompt.md"
                     if prompt_file.exists():
                         prompt_file.unlink()
+
+
+# Populate AGENT_CONFIGS after class definition.
+# Catches ImportError from circular imports during module loading;
+# _configs_loaded stays False so the next explicit access retries.
+try:
+    CommandRegistrar._ensure_configs()
+except ImportError:
+    pass

src/specify_cli/extensions.py

@@ -801,15 +801,12 @@ class ExtensionManager:
             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
@@ -2138,11 +2135,14 @@ class HookExecutor:
         init_options = self._load_init_options()
         selected_ai = init_options.get("ai")
         codex_skill_mode = selected_ai == "codex" and bool(init_options.get("ai_skills"))
+        claude_skill_mode = selected_ai == "claude" and bool(init_options.get("ai_skills"))
         kimi_skill_mode = selected_ai == "kimi"
 
         skill_name = self._skill_name_from_command(command_id)
         if codex_skill_mode and skill_name:
             return f"${skill_name}"
+        if claude_skill_mode and skill_name:
+            return f"/{skill_name}"
         if kimi_skill_mode and skill_name:
             return f"/skill:{skill_name}"
 

src/specify_cli/integrations/__init__.py

@@ -46,18 +46,22 @@ def _register_builtins() -> None:
     users install and invoke.
     """
     # -- Imports (alphabetical) -------------------------------------------
+    from .agy import AgyIntegration
     from .amp import AmpIntegration
     from .auggie import AuggieIntegration
     from .bob import BobIntegration
     from .claude import ClaudeIntegration
+    from .codex import CodexIntegration
     from .codebuddy import CodebuddyIntegration
     from .copilot import CopilotIntegration
     from .cursor_agent import CursorAgentIntegration
     from .forge import ForgeIntegration
     from .gemini import GeminiIntegration
+    from .generic import GenericIntegration
     from .iflow import IflowIntegration
     from .junie import JunieIntegration
     from .kilocode import KilocodeIntegration
+    from .kimi import KimiIntegration
     from .kiro_cli import KiroCliIntegration
     from .opencode import OpencodeIntegration
     from .pi import PiIntegration
@@ -71,18 +75,22 @@ def _register_builtins() -> None:
     from .windsurf import WindsurfIntegration
 
     # -- Registration (alphabetical) --------------------------------------
+    _register(AgyIntegration())
     _register(AmpIntegration())
     _register(AuggieIntegration())
     _register(BobIntegration())
     _register(ClaudeIntegration())
+    _register(CodexIntegration())
     _register(CodebuddyIntegration())
     _register(CopilotIntegration())
     _register(CursorAgentIntegration())
     _register(ForgeIntegration())
     _register(GeminiIntegration())
+    _register(GenericIntegration())
     _register(IflowIntegration())
     _register(JunieIntegration())
     _register(KilocodeIntegration())
+    _register(KimiIntegration())
     _register(KiroCliIntegration())
     _register(OpencodeIntegration())
     _register(PiIntegration())

src/specify_cli/integrations/agy/__init__.py

@@ -0,0 +1,41 @@
+"""Antigravity (agy) integration — skills-based agent.
+
+Antigravity uses ``.agent/skills/speckit-<name>/SKILL.md`` layout.
+Explicit command support was deprecated in version 1.20.5;
+``--skills`` defaults to ``True``.
+"""
+
+from __future__ import annotations
+
+from ..base import IntegrationOption, SkillsIntegration
+
+
+class AgyIntegration(SkillsIntegration):
+    """Integration for Antigravity IDE."""
+
+    key = "agy"
+    config = {
+        "name": "Antigravity",
+        "folder": ".agent/",
+        "commands_subdir": "skills",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": ".agent/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = "AGENTS.md"
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=True,
+                help="Install as agent skills (default for Antigravity since v1.20.5)",
+            ),
+        ]

src/specify_cli/integrations/agy/scripts/update-context.ps1

@@ -0,0 +1,17 @@
+# update-context.ps1 — Antigravity (agy) integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
+if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+    $repoRoot = $scriptDir
+    $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot)
+    while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+        $repoRoot = Split-Path -Parent $repoRoot
+    }
+}
+
+& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType agy

src/specify_cli/integrations/agy/scripts/update-context.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# update-context.sh — Antigravity (agy) integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+set -euo pipefail
+
+_script_dir="$(cd "$(dirname "$0")" && pwd)"
+_root="$_script_dir"
+while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done
+if [ -z "${REPO_ROOT:-}" ]; then
+  if [ -d "$_root/.specify" ]; then
+    REPO_ROOT="$_root"
+  else
+    git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then
+      REPO_ROOT="$git_root"
+    else
+      REPO_ROOT="$_root"
+    fi
+  fi
+fi
+
+exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" agy

src/specify_cli/integrations/base.py

@@ -7,6 +7,8 @@ Provides:
   integrations (the common case — subclass, set three class attrs, done).
 - ``TomlIntegration`` — concrete base for TOML-format integrations
   (Gemini, Tabnine — subclass, set three class attrs, done).
+- ``SkillsIntegration`` — concrete base for integrations that install
+  commands as agent skills (``speckit-<name>/SKILL.md`` layout).
 """
 
 from __future__ import annotations
@@ -200,10 +202,14 @@ class IntegrationBase(ABC):
     ) -> Path:
         """Write *content* to *dest*, hash it, and record in *manifest*.
 
-        Creates parent directories as needed.  Returns *dest*.
+        Creates parent directories as needed.  Writes bytes directly to
+        avoid platform newline translation (CRLF on Windows).  Any
+        ``\r\n`` sequences in *content* are normalised to ``\n`` before
+        writing.  Returns *dest*.
         """
         dest.parent.mkdir(parents=True, exist_ok=True)
-        dest.write_text(content, encoding="utf-8")
+        normalized = content.replace("\r\n", "\n")
+        dest.write_bytes(normalized.encode("utf-8"))
         rel = dest.resolve().relative_to(project_root.resolve())
         manifest.record_existing(rel)
         return dest
@@ -633,3 +639,155 @@ class TomlIntegration(IntegrationBase):
 
         created.extend(self.install_scripts(project_root, manifest))
         return created
+
+
+# ---------------------------------------------------------------------------
+# SkillsIntegration — skills-format agents (Codex, Kimi, Agy)
+# ---------------------------------------------------------------------------
+
+
+class SkillsIntegration(IntegrationBase):
+    """Concrete base for integrations that install commands as agent skills.
+
+    Skills use the ``speckit-<name>/SKILL.md`` directory layout following
+    the `agentskills.io <https://agentskills.io/specification>`_ spec.
+
+    Subclasses set ``key``, ``config``, ``registrar_config`` (and
+    optionally ``context_file``) like any integration.  They may also
+    override ``options()`` to declare additional CLI flags (e.g.
+    ``--skills``, ``--migrate-legacy``).
+
+    ``setup()`` processes each shared command template into a
+    ``speckit-<name>/SKILL.md`` file with skills-oriented frontmatter.
+    """
+
+    def skills_dest(self, project_root: Path) -> Path:
+        """Return the absolute path to the skills output directory.
+
+        Derived from ``config["folder"]`` and the configured
+        ``commands_subdir`` (defaults to ``"skills"``).
+
+        Raises ``ValueError`` when ``config`` or ``folder`` is missing.
+        """
+        if not self.config:
+            raise ValueError(
+                f"{type(self).__name__}.config is not set."
+            )
+        folder = self.config.get("folder")
+        if not folder:
+            raise ValueError(
+                f"{type(self).__name__}.config is missing required 'folder' entry."
+            )
+        subdir = self.config.get("commands_subdir", "skills")
+        return project_root / folder / subdir
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install command templates as agent skills.
+
+        Creates ``speckit-<name>/SKILL.md`` for each shared command
+        template.  Each SKILL.md has normalised frontmatter containing
+        ``name``, ``description``, ``compatibility``, and ``metadata``.
+        """
+        import yaml
+
+        templates = self.list_command_templates()
+        if not templates:
+            return []
+
+        project_root_resolved = project_root.resolve()
+        if manifest.project_root != project_root_resolved:
+            raise ValueError(
+                f"manifest.project_root ({manifest.project_root}) does not match "
+                f"project_root ({project_root_resolved})"
+            )
+
+        skills_dir = self.skills_dest(project_root).resolve()
+        try:
+            skills_dir.relative_to(project_root_resolved)
+        except ValueError as exc:
+            raise ValueError(
+                f"Skills destination {skills_dir} escapes "
+                f"project root {project_root_resolved}"
+            ) from exc
+
+        script_type = opts.get("script_type", "sh")
+        arg_placeholder = (
+            self.registrar_config.get("args", "$ARGUMENTS")
+            if self.registrar_config
+            else "$ARGUMENTS"
+        )
+        created: list[Path] = []
+
+        for src_file in templates:
+            raw = src_file.read_text(encoding="utf-8")
+
+            # Derive the skill name from the template stem
+            command_name = src_file.stem  # e.g. "plan"
+            skill_name = f"speckit-{command_name.replace('.', '-')}"
+
+            # Parse frontmatter for description
+            frontmatter: dict[str, Any] = {}
+            if raw.startswith("---"):
+                parts = raw.split("---", 2)
+                if len(parts) >= 3:
+                    try:
+                        fm = yaml.safe_load(parts[1])
+                        if isinstance(fm, dict):
+                            frontmatter = fm
+                    except yaml.YAMLError:
+                        pass
+
+            # Process body through the standard template pipeline
+            processed_body = self.process_template(
+                raw, self.key, script_type, arg_placeholder
+            )
+            # Strip the processed frontmatter — we rebuild it for skills.
+            # Preserve leading whitespace in the body to match release ZIP
+            # output byte-for-byte (the template body starts with \n after
+            # the closing ---).
+            if processed_body.startswith("---"):
+                parts = processed_body.split("---", 2)
+                if len(parts) >= 3:
+                    processed_body = parts[2]
+
+            # Select description — use the original template description
+            # to stay byte-for-byte identical with release ZIP output.
+            description = frontmatter.get("description", "")
+            if not description:
+                description = f"Spec Kit: {command_name} workflow"
+
+            # Build SKILL.md with manually formatted frontmatter to match
+            # the release packaging script output exactly (double-quoted
+            # values, no yaml.safe_dump quoting differences).
+            def _quote(v: str) -> str:
+                escaped = v.replace("\\", "\\\\").replace('"', '\\"')
+                return f'"{escaped}"'
+
+            skill_content = (
+                f"---\n"
+                f"name: {_quote(skill_name)}\n"
+                f"description: {_quote(description)}\n"
+                f"compatibility: {_quote('Requires spec-kit project structure with .specify/ directory')}\n"
+                f"metadata:\n"
+                f"  author: {_quote('github-spec-kit')}\n"
+                f"  source: {_quote('templates/commands/' + src_file.name)}\n"
+                f"---\n"
+                f"{processed_body}"
+            )
+
+            # Write speckit-<name>/SKILL.md
+            skill_dir = skills_dir / skill_name
+            skill_file = skill_dir / "SKILL.md"
+            dst = self.write_file_and_record(
+                skill_content, skill_file, project_root, manifest
+            )
+            created.append(dst)
+
+        created.extend(self.install_scripts(project_root, manifest))
+        return created

src/specify_cli/integrations/claude/__init__.py

@@ -1,21 +1,109 @@
 """Claude Code integration."""
 
-from ..base import MarkdownIntegration
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ..base import SkillsIntegration
+from ..manifest import IntegrationManifest
 
 
-class ClaudeIntegration(MarkdownIntegration):
+class ClaudeIntegration(SkillsIntegration):
+    """Integration for Claude Code skills."""
+
     key = "claude"
     config = {
         "name": "Claude Code",
         "folder": ".claude/",
-        "commands_subdir": "commands",
+        "commands_subdir": "skills",
         "install_url": "https://docs.anthropic.com/en/docs/claude-code/setup",
         "requires_cli": True,
     }
     registrar_config = {
-        "dir": ".claude/commands",
+        "dir": ".claude/skills",
         "format": "markdown",
         "args": "$ARGUMENTS",
-        "extension": ".md",
+        "extension": "/SKILL.md",
     }
     context_file = "CLAUDE.md"
+
+    def command_filename(self, template_name: str) -> str:
+        """Claude skills live at .claude/skills/<name>/SKILL.md."""
+        skill_name = f"speckit-{template_name.replace('.', '-')}"
+        return f"{skill_name}/SKILL.md"
+
+    def _render_skill(self, template_name: str, frontmatter: dict[str, Any], body: str) -> str:
+        """Render a processed command template as a Claude skill."""
+        skill_name = f"speckit-{template_name.replace('.', '-')}"
+        description = frontmatter.get(
+            "description",
+            f"Spec-kit workflow command: {template_name}",
+        )
+        skill_frontmatter = self._build_skill_fm(
+            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"
+
+    def _build_skill_fm(self, name: str, description: str, source: str) -> dict:
+        from specify_cli.agents import CommandRegistrar
+        return CommandRegistrar.build_skill_frontmatter(
+            self.key, name, description, source
+        )
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install Claude skills into .claude/skills."""
+        templates = self.list_command_templates()
+        if not templates:
+            return []
+
+        project_root_resolved = project_root.resolve()
+        if manifest.project_root != project_root_resolved:
+            raise ValueError(
+                f"manifest.project_root ({manifest.project_root}) does not match "
+                f"project_root ({project_root_resolved})"
+            )
+
+        dest = self.skills_dest(project_root).resolve()
+        try:
+            dest.relative_to(project_root_resolved)
+        except ValueError as exc:
+            raise ValueError(
+                f"Integration destination {dest} escapes "
+                f"project root {project_root_resolved}"
+            ) from exc
+        dest.mkdir(parents=True, exist_ok=True)
+
+        script_type = opts.get("script_type", "sh")
+        arg_placeholder = self.registrar_config.get("args", "$ARGUMENTS")
+        from specify_cli.agents import CommandRegistrar
+        registrar = CommandRegistrar()
+        created: list[Path] = []
+
+        for src_file in templates:
+            raw = src_file.read_text(encoding="utf-8")
+            processed = self.process_template(raw, self.key, script_type, arg_placeholder)
+            frontmatter, body = registrar.parse_frontmatter(processed)
+            if not isinstance(frontmatter, dict):
+                frontmatter = {}
+
+            rendered = self._render_skill(src_file.stem, frontmatter, body)
+            dst_file = self.write_file_and_record(
+                rendered,
+                dest / self.command_filename(src_file.stem),
+                project_root,
+                manifest,
+            )
+            created.append(dst_file)
+
+        created.extend(self.install_scripts(project_root, manifest))
+        return created

src/specify_cli/integrations/codex/__init__.py

@@ -0,0 +1,40 @@
+"""Codex CLI integration — skills-based agent.
+
+Codex uses the ``.agents/skills/speckit-<name>/SKILL.md`` layout.
+Commands are deprecated; ``--skills`` defaults to ``True``.
+"""
+
+from __future__ import annotations
+
+from ..base import IntegrationOption, SkillsIntegration
+
+
+class CodexIntegration(SkillsIntegration):
+    """Integration for OpenAI Codex CLI."""
+
+    key = "codex"
+    config = {
+        "name": "Codex CLI",
+        "folder": ".agents/",
+        "commands_subdir": "skills",
+        "install_url": "https://github.com/openai/codex",
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".agents/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = "AGENTS.md"
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=True,
+                help="Install as agent skills (default for Codex)",
+            ),
+        ]

src/specify_cli/integrations/codex/scripts/update-context.ps1

@@ -0,0 +1,17 @@
+# update-context.ps1 — Codex CLI integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
+if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+    $repoRoot = $scriptDir
+    $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot)
+    while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+        $repoRoot = Split-Path -Parent $repoRoot
+    }
+}
+
+& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType codex

src/specify_cli/integrations/codex/scripts/update-context.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# update-context.sh — Codex CLI integration: create/update AGENTS.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+set -euo pipefail
+
+_script_dir="$(cd "$(dirname "$0")" && pwd)"
+_root="$_script_dir"
+while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done
+if [ -z "${REPO_ROOT:-}" ]; then
+  if [ -d "$_root/.specify" ]; then
+    REPO_ROOT="$_root"
+  else
+    git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then
+      REPO_ROOT="$git_root"
+    else
+      REPO_ROOT="$_root"
+    fi
+  fi
+fi
+
+exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" codex

src/specify_cli/integrations/generic/__init__.py

@@ -0,0 +1,133 @@
+"""Generic integration — bring your own agent.
+
+Requires ``--commands-dir`` to specify the output directory for command
+files.  No longer special-cased in the core CLI — just another
+integration with its own required option.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from ..base import IntegrationOption, MarkdownIntegration
+from ..manifest import IntegrationManifest
+
+
+class GenericIntegration(MarkdownIntegration):
+    """Integration for user-specified (generic) agents."""
+
+    key = "generic"
+    config = {
+        "name": "Generic (bring your own agent)",
+        "folder": None,  # Set dynamically from --commands-dir
+        "commands_subdir": "commands",
+        "install_url": None,
+        "requires_cli": False,
+    }
+    registrar_config = {
+        "dir": "",  # Set dynamically from --commands-dir
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": ".md",
+    }
+    context_file = None
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--commands-dir",
+                required=True,
+                help="Directory for command files (e.g. .myagent/commands/)",
+            ),
+        ]
+
+    @staticmethod
+    def _resolve_commands_dir(
+        parsed_options: dict[str, Any] | None,
+        opts: dict[str, Any],
+    ) -> str:
+        """Extract ``--commands-dir`` from parsed options or raw_options.
+
+        Returns the directory string or raises ``ValueError``.
+        """
+        parsed_options = parsed_options or {}
+
+        commands_dir = parsed_options.get("commands_dir")
+        if commands_dir:
+            return commands_dir
+
+        # Fall back to raw_options (--integration-options="--commands-dir ...")
+        raw = opts.get("raw_options")
+        if raw:
+            import shlex
+            tokens = shlex.split(raw)
+            for i, token in enumerate(tokens):
+                if token == "--commands-dir" and i + 1 < len(tokens):
+                    return tokens[i + 1]
+                if token.startswith("--commands-dir="):
+                    return token.split("=", 1)[1]
+
+        raise ValueError(
+            "--commands-dir is required for the generic integration"
+        )
+
+    def commands_dest(self, project_root: Path) -> Path:
+        """Not supported for GenericIntegration — use setup() directly.
+
+        GenericIntegration is stateless; the output directory comes from
+        ``parsed_options`` or ``raw_options`` at call time, not from
+        instance state.
+        """
+        raise ValueError(
+            "GenericIntegration.commands_dest() cannot be called directly; "
+            "the output directory is resolved from parsed_options in setup()"
+        )
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install commands to the user-provided commands directory."""
+        commands_dir = self._resolve_commands_dir(parsed_options, opts)
+
+        templates = self.list_command_templates()
+        if not templates:
+            return []
+
+        project_root_resolved = project_root.resolve()
+        if manifest.project_root != project_root_resolved:
+            raise ValueError(
+                f"manifest.project_root ({manifest.project_root}) does not match "
+                f"project_root ({project_root_resolved})"
+            )
+
+        dest = (project_root / commands_dir).resolve()
+        try:
+            dest.relative_to(project_root_resolved)
+        except ValueError as exc:
+            raise ValueError(
+                f"Integration destination {dest} escapes "
+                f"project root {project_root_resolved}"
+            ) from exc
+        dest.mkdir(parents=True, exist_ok=True)
+
+        script_type = opts.get("script_type", "sh")
+        arg_placeholder = "$ARGUMENTS"
+        created: list[Path] = []
+
+        for src_file in templates:
+            raw = src_file.read_text(encoding="utf-8")
+            processed = self.process_template(raw, self.key, script_type, arg_placeholder)
+            dst_name = self.command_filename(src_file.stem)
+            dst_file = self.write_file_and_record(
+                processed, dest / dst_name, project_root, manifest
+            )
+            created.append(dst_file)
+
+        created.extend(self.install_scripts(project_root, manifest))
+        return created

src/specify_cli/integrations/generic/scripts/update-context.ps1

@@ -0,0 +1,17 @@
+# update-context.ps1 — Generic integration: create/update context file
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
+if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+    $repoRoot = $scriptDir
+    $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot)
+    while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+        $repoRoot = Split-Path -Parent $repoRoot
+    }
+}
+
+& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType generic

src/specify_cli/integrations/generic/scripts/update-context.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# update-context.sh — Generic integration: create/update context file
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+set -euo pipefail
+
+_script_dir="$(cd "$(dirname "$0")" && pwd)"
+_root="$_script_dir"
+while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done
+if [ -z "${REPO_ROOT:-}" ]; then
+  if [ -d "$_root/.specify" ]; then
+    REPO_ROOT="$_root"
+  else
+    git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then
+      REPO_ROOT="$git_root"
+    else
+      REPO_ROOT="$_root"
+    fi
+  fi
+fi
+
+exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" generic

src/specify_cli/integrations/kimi/__init__.py

@@ -0,0 +1,124 @@
+"""Kimi Code integration — skills-based agent (Moonshot AI).
+
+Kimi uses the ``.kimi/skills/speckit-<name>/SKILL.md`` layout with
+``/skill:speckit-<name>`` invocation syntax.
+
+Includes legacy migration logic for projects initialised before Kimi
+moved from dotted skill directories (``speckit.xxx``) to hyphenated
+(``speckit-xxx``).
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from ..base import IntegrationOption, SkillsIntegration
+from ..manifest import IntegrationManifest
+
+
+class KimiIntegration(SkillsIntegration):
+    """Integration for Kimi Code CLI (Moonshot AI)."""
+
+    key = "kimi"
+    config = {
+        "name": "Kimi Code",
+        "folder": ".kimi/",
+        "commands_subdir": "skills",
+        "install_url": "https://code.kimi.com/",
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".kimi/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = "KIMI.md"
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=True,
+                help="Install as agent skills (default for Kimi)",
+            ),
+            IntegrationOption(
+                "--migrate-legacy",
+                is_flag=True,
+                default=False,
+                help="Migrate legacy dotted skill dirs (speckit.xxx → speckit-xxx)",
+            ),
+        ]
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        """Install skills with optional legacy dotted-name migration."""
+        parsed_options = parsed_options or {}
+
+        # Run base setup first so hyphenated targets (speckit-*) exist,
+        # then migrate/clean legacy dotted dirs without risking user content loss.
+        created = super().setup(
+            project_root, manifest, parsed_options=parsed_options, **opts
+        )
+
+        if parsed_options.get("migrate_legacy", False):
+            skills_dir = self.skills_dest(project_root)
+            if skills_dir.is_dir():
+                _migrate_legacy_kimi_dotted_skills(skills_dir)
+
+        return created
+
+
+def _migrate_legacy_kimi_dotted_skills(skills_dir: Path) -> tuple[int, int]:
+    """Migrate legacy Kimi dotted skill dirs (speckit.xxx) to hyphenated format.
+
+    Returns ``(migrated_count, removed_count)``.
+    """
+    if not skills_dir.is_dir():
+        return (0, 0)
+
+    migrated_count = 0
+    removed_count = 0
+
+    for legacy_dir in sorted(skills_dir.glob("speckit.*")):
+        if not legacy_dir.is_dir():
+            continue
+        if not (legacy_dir / "SKILL.md").exists():
+            continue
+
+        suffix = legacy_dir.name[len("speckit."):]
+        if not suffix:
+            continue
+
+        target_dir = skills_dir / f"speckit-{suffix.replace('.', '-')}"
+
+        if not target_dir.exists():
+            shutil.move(str(legacy_dir), str(target_dir))
+            migrated_count += 1
+            continue
+
+        # Target exists — only remove legacy if SKILL.md is identical
+        target_skill = target_dir / "SKILL.md"
+        legacy_skill = legacy_dir / "SKILL.md"
+        if target_skill.is_file():
+            try:
+                if target_skill.read_bytes() == legacy_skill.read_bytes():
+                    has_extra = any(
+                        child.name != "SKILL.md" for child in legacy_dir.iterdir()
+                    )
+                    if not has_extra:
+                        shutil.rmtree(legacy_dir)
+                        removed_count += 1
+            except OSError:
+                pass
+
+    return (migrated_count, removed_count)

src/specify_cli/integrations/kimi/scripts/update-context.ps1

@@ -0,0 +1,17 @@
+# update-context.ps1 — Kimi Code integration: create/update KIMI.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+$ErrorActionPreference = 'Stop'
+
+$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition
+$repoRoot = try { git rev-parse --show-toplevel 2>$null } catch { $null }
+if (-not $repoRoot -or -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+    $repoRoot = $scriptDir
+    $fsRoot = [System.IO.Path]::GetPathRoot($repoRoot)
+    while ($repoRoot -and $repoRoot -ne $fsRoot -and -not (Test-Path (Join-Path $repoRoot '.specify'))) {
+        $repoRoot = Split-Path -Parent $repoRoot
+    }
+}
+
+& "$repoRoot/.specify/scripts/powershell/update-agent-context.ps1" -AgentType kimi

src/specify_cli/integrations/kimi/scripts/update-context.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# update-context.sh — Kimi Code integration: create/update KIMI.md
+#
+# Thin wrapper that delegates to the shared update-agent-context script.
+
+set -euo pipefail
+
+_script_dir="$(cd "$(dirname "$0")" && pwd)"
+_root="$_script_dir"
+while [ "$_root" != "/" ] && [ ! -d "$_root/.specify" ]; do _root="$(dirname "$_root")"; done
+if [ -z "${REPO_ROOT:-}" ]; then
+  if [ -d "$_root/.specify" ]; then
+    REPO_ROOT="$_root"
+  else
+    git_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    if [ -n "$git_root" ] && [ -d "$git_root/.specify" ]; then
+      REPO_ROOT="$git_root"
+    else
+      REPO_ROOT="$_root"
+    fi
+  fi
+fi
+
+exec "$REPO_ROOT/.specify/scripts/bash/update-agent-context.sh" kimi

src/specify_cli/presets.py

@@ -714,7 +714,14 @@ class PresetManager:
         selected_ai = init_opts.get("ai")
         if not isinstance(selected_ai, str):
             return []
+        ai_skills_enabled = bool(init_opts.get("ai_skills"))
         registrar = CommandRegistrar()
+        agent_config = registrar.AGENT_CONFIGS.get(selected_ai, {})
+        # Native skill agents (e.g. codex/kimi/agy) materialize brand-new
+        # preset skills in _register_commands() because their detected agent
+        # directory is already the skills directory. This flag is only for
+        # command-backed agents that also mirror commands into skills.
+        create_missing_skills = ai_skills_enabled and agent_config.get("extension") != "/SKILL.md"
 
         written: List[str] = []
 
@@ -741,6 +748,10 @@ class PresetManager:
                 target_skill_names.append(skill_name)
             if legacy_skill_name != skill_name and (skills_dir / legacy_skill_name).is_dir():
                 target_skill_names.append(legacy_skill_name)
+            if not target_skill_names and create_missing_skills:
+                missing_skill_dir = skills_dir / skill_name
+                if not missing_skill_dir.exists():
+                    target_skill_names.append(skill_name)
             if not target_skill_names:
                 continue
 
@@ -760,15 +771,16 @@ class PresetManager:
             )
 
             for target_skill_name in target_skill_names:
-                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}",
-                    },
-                }
+                skill_subdir = skills_dir / target_skill_name
+                if skill_subdir.exists() and not skill_subdir.is_dir():
+                    continue
+                skill_subdir.mkdir(parents=True, exist_ok=True)
+                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"
@@ -778,7 +790,7 @@ class PresetManager:
                     f"{body}\n"
                 )
 
-                skill_file = skills_dir / target_skill_name / "SKILL.md"
+                skill_file = skill_subdir / "SKILL.md"
                 skill_file.write_text(skill_content, encoding="utf-8")
                 written.append(target_skill_name)
 
@@ -850,15 +862,12 @@ class PresetManager:
                     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 = (
@@ -883,15 +892,12 @@ class PresetManager:
                 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"
@@ -1040,14 +1046,15 @@ class PresetManager:
         if registered_skills:
             self._unregister_skills(registered_skills, pack_dir)
             try:
-                from . import NATIVE_SKILLS_AGENTS
+                from .agents import CommandRegistrar
             except ImportError:
-                NATIVE_SKILLS_AGENTS = set()
-            registered_commands = {
-                agent_name: cmd_names
-                for agent_name, cmd_names in registered_commands.items()
-                if agent_name not in NATIVE_SKILLS_AGENTS
-            }
+                CommandRegistrar = None
+            if CommandRegistrar is not None:
+                registered_commands = {
+                    agent_name: cmd_names
+                    for agent_name, cmd_names in registered_commands.items()
+                    if CommandRegistrar.AGENT_CONFIGS.get(agent_name, {}).get("extension") != "/SKILL.md"
+                }
 
         # Unregister non-skill command files from AI agents.
         if registered_commands: