feat(opencode): add --skills support to opencode integration

Adds opt-in `--skills` support to OpencodeIntegration, producing `speckit-<name>/SKILL.md` files under `.opencode/skills/` instead of flat `.md` files.
Opencode natively supports this format (https://opencode.ai/docs/skills/).

Activate via: `specify init --integration opencode --integration-options="--skills"`

Author: tinesoft

docs/reference/integrations.md

@@ -28,7 +28,7 @@ The Specify CLI supports a wide range of AI coding agents. When you run `specify
 | [Kiro CLI](https://kiro.dev/docs/cli/)                                               | `kiro-cli`       | Kiro CLI does not substitute `$ARGUMENTS` in file-based prompts, so Spec Kit ships a prose fallback at render time (see [Manage prompts](https://kiro.dev/docs/cli/chat/manage-prompts/) and issue [#1926](https://github.com/github/spec-kit/issues/1926)). Alias: `--integration kiro` |
 | [Lingma](https://lingma.aliyun.com/)                                                 | `lingma`         | Skills-based integration; skills are installed automatically                                                                               |
 | [Mistral Vibe](https://github.com/mistralai/mistral-vibe)                            | `vibe`           |                                                                                                                                           |
-| [opencode](https://opencode.ai/)                                                     | `opencode`       |                                                                                                                                           |
+| [opencode](https://opencode.ai/)                                                     | `opencode`       | Supports `--skills` for agent-skills scaffolding (`speckit-<name>/SKILL.md`)                                                            |
 | [Pi Coding Agent](https://pi.dev)                                                    | `pi`             | Pi doesn't have MCP support out of the box, so `taskstoissues` won't work as intended. MCP support can be added via [extensions](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#extensions) |
 | [Qoder CLI](https://qoder.com/cli)                                                   | `qodercli`       |                                                                                                                                           |
 | [Qwen Code](https://github.com/QwenLM/qwen-code)                                     | `qwen`           |                                                                                                                                           |
@@ -134,6 +134,7 @@ Some integrations accept additional options via `--integration-options`:
 | ----------- | ------------------- | -------------------------------------------------------------- |
 | `generic`   | `--commands-dir`    | Required. Directory for command files                          |
 | `kimi`      | `--migrate-legacy`  | Migrate legacy dotted skill directories to hyphenated format   |
+| `opencode`  | `--skills`          | Scaffold commands as agent skills (`speckit-<name>/SKILL.md`) instead of `.md` command files |
 
 Example:
 

src/specify_cli/__init__.py

@@ -444,7 +444,6 @@ def _print_cli_warning(
 from .commands import init as _init_cmd  # noqa: E402
 _init_cmd.register(app)
 
-
 @app.command()
 def check():
     """Check that all required tools are installed."""

src/specify_cli/commands/init.py

@@ -369,6 +369,26 @@ def init(
 
                 ensure_constitution_from_template(project_path, tracker=tracker)
 
+                # Persist the CLI options so later operations (e.g. extension install, preset add)
+                # can adapt their behaviour without re-scanning the filesystem.
+                # Must be saved BEFORE extension and preset install so _get_skills_dir() works.
+                init_opts = {
+                    "ai": selected_ai,
+                    "integration": resolved_integration.key,
+                    "branch_numbering": branch_numbering or "sequential",
+                    "context_file": resolved_integration.context_file,
+                    "here": here,
+                    "script": selected_script,
+                    "speckit_version": get_speckit_version(),
+                }
+                # Use parsed_options as the source of truth for skills mode, not
+                # _skills_mode (a mutable runtime flag), so the setting persists
+                # correctly even if the integration is restored without setup().
+                from ..integrations.base import SkillsIntegration as _SkillsPersist
+                if isinstance(resolved_integration, _SkillsPersist) or integration_parsed_options.get("skills"):
+                    init_opts["ai_skills"] = True
+                save_init_options(project_path, init_opts)
+
                 if not no_git:
                     tracker.start("git")
                     git_messages = []
@@ -448,19 +468,6 @@ def init(
                     sanitized_wf = str(wf_err).replace('\n', ' ').strip()
                     tracker.error("workflow", f"install failed: {sanitized_wf[:120]}")
 
-                init_opts = {
-                    "ai": selected_ai,
-                    "integration": resolved_integration.key,
-                    "branch_numbering": branch_numbering or "sequential",
-                    "here": here,
-                    "script": selected_script,
-                    "speckit_version": get_speckit_version(),
-                }
-                from ..integrations.base import SkillsIntegration as _SkillsPersist
-                if isinstance(resolved_integration, _SkillsPersist) or getattr(resolved_integration, "_skills_mode", False):
-                    init_opts["ai_skills"] = True
-                save_init_options(project_path, init_opts)
-
                 # --- agent-context extension (bundled, auto-installed) ---
                 # Installed after init-options.json is written so that skill
                 # registration can read ai_skills + integration key.
@@ -627,8 +634,8 @@ def init(
         cursor_agent_skill_mode = selected_ai == "cursor-agent" and _is_skills_integration
         copilot_skill_mode = selected_ai == "copilot" and _is_skills_integration
         devin_skill_mode = selected_ai == "devin"
-        cline_skill_mode = selected_ai == "cline"
-        native_skill_mode = codex_skill_mode or claude_skill_mode or kimi_skill_mode or agy_skill_mode or trae_skill_mode or cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode
+        opencode_skill_mode = selected_ai == "opencode" and _is_skills_integration
+        native_skill_mode = codex_skill_mode or claude_skill_mode or kimi_skill_mode or agy_skill_mode or trae_skill_mode or cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode or opencode_skill_mode
 
         if codex_skill_mode:
             steps_lines.append(f"{step_num}. Start Codex in this project directory; spec-kit skills were installed to [cyan].agents/skills[/cyan]")
@@ -642,6 +649,9 @@ def init(
         if devin_skill_mode:
             steps_lines.append(f"{step_num}. Start Devin in this project directory; spec-kit skills were installed to [cyan].devin/skills[/cyan]")
             step_num += 1
+        if opencode_skill_mode:
+            steps_lines.append(f"{step_num}. Start opencode in this project directory; spec-kit skills were installed to [cyan].opencode/skills[/cyan]")
+            step_num += 1
         usage_label = "skills" if native_skill_mode else "slash commands"
 
         def _display_cmd(name: str) -> str:
@@ -651,7 +661,7 @@ def _display_cmd(name: str) -> str:
                 return f"/speckit-{name}"
             if kimi_skill_mode:
                 return f"/skill:speckit-{name}"
-            if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode or cline_skill_mode:
+            if cursor_agent_skill_mode or copilot_skill_mode or devin_skill_mode or opencode_skill_mode:
                 return f"/speckit-{name}"
             return f"/speckit.{name}"
 

src/specify_cli/extensions.py

@@ -982,6 +982,8 @@ def _register_extension_skills(
             body = registrar.resolve_skill_placeholders(
                 selected_ai, frontmatter, body, self.project_root
             )
+            from .integrations.base import IntegrationBase as _IntegrationBase
+            body = _IntegrationBase.resolve_command_refs(body, "-")
 
             original_desc = frontmatter.get("description", "")
             description = original_desc or f"Extension command: {cmd_name}"

src/specify_cli/integrations/opencode/__init__.py

@@ -1,6 +1,33 @@
 """opencode integration."""
 
-from ..base import MarkdownIntegration
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ..base import IntegrationOption, MarkdownIntegration, SkillsIntegration
+from ..manifest import IntegrationManifest
+
+
+class _OpencodeSkillsHelper(SkillsIntegration):
+    """Internal delegate used by OpencodeIntegration when --skills is active."""
+
+    key = "opencode"
+    config = {
+        "name": "opencode",
+        "folder": ".opencode/",
+        "commands_subdir": "skills",
+        "install_url": "https://opencode.ai",
+        "requires_cli": True,
+    }
+    registrar_config = {
+        "dir": ".opencode/skills",
+        "format": "markdown",
+        "args": "$ARGUMENTS",
+        "extension": "/SKILL.md",
+    }
+    context_file = "AGENTS.md"
 
 
 class OpencodeIntegration(MarkdownIntegration):
@@ -20,6 +47,100 @@ class OpencodeIntegration(MarkdownIntegration):
         "extension": ".md",
     }
     context_file = "AGENTS.md"
+    # Mutable flag set by setup() — indicates the active scaffolding mode.
+    _skills_mode: bool = False
+
+    @classmethod
+    def options(cls) -> list[IntegrationOption]:
+        return [
+            IntegrationOption(
+                "--skills",
+                is_flag=True,
+                default=False,
+                help="Scaffold commands as agent skills (speckit-<name>/SKILL.md) instead of .md files",
+            ),
+        ]
+
+    def effective_invoke_separator(
+        self, parsed_options: dict[str, Any] | None = None
+    ) -> str:
+        if parsed_options and parsed_options.get("skills"):
+            return "-"
+        if self._skills_mode:
+            return "-"
+        return self.invoke_separator  # default: "."
+
+    def build_command_invocation(self, command_name: str, args: str = "") -> str:
+        if not self._skills_mode:
+            return super().build_command_invocation(command_name, args)
+        stem = command_name
+        if stem.startswith("speckit."):
+            stem = stem[len("speckit."):]
+        invocation = "/speckit-" + stem.replace(".", "-")
+        if args:
+            invocation = f"{invocation} {args}"
+        return invocation
+
+    def dispatch_command(
+        self,
+        command_name: str,
+        args: str = "",
+        *,
+        project_root: Path | None = None,
+        model: str | None = None,
+        timeout: int = 600,
+        stream: bool = True,
+    ) -> dict[str, Any]:
+        # Derive skills mode from project layout when project_root is provided;
+        # fall back to _skills_mode only when no root is given. This prevents
+        # stale _skills_mode=True from a prior setup() affecting subsequent
+        # dispatches against non-skills projects.
+        if project_root:
+            skills_dir = project_root / ".opencode" / "skills"
+            skills_mode = skills_dir.is_dir() and any(
+                d.is_dir() and (d / "SKILL.md").is_file()
+                for d in skills_dir.glob("speckit-*")
+            )
+        else:
+            skills_mode = self._skills_mode
+
+        stem = command_name
+        if stem.startswith("speckit."):
+            stem = stem[len("speckit."):]
+        if skills_mode:
+            invocation = "/speckit-" + stem.replace(".", "-")
+        else:
+            invocation = "/speckit." + stem
+        if args:
+            invocation = f"{invocation} {args}"
+
+        exec_args = self.build_exec_args(invocation, model=model, output_json=not stream)
+        cwd = str(project_root) if project_root else None
+
+        if stream:
+            try:
+                result = subprocess.run(exec_args, text=True, cwd=cwd)
+            except KeyboardInterrupt:
+                return {"exit_code": 130, "stdout": "", "stderr": "Interrupted by user"}
+            return {"exit_code": result.returncode, "stdout": "", "stderr": ""}
+
+        result = subprocess.run(
+            exec_args, capture_output=True, text=True, cwd=cwd, timeout=timeout,
+        )
+        return {"exit_code": result.returncode, "stdout": result.stdout, "stderr": result.stderr}
+
+    def setup(
+        self,
+        project_root: Path,
+        manifest: IntegrationManifest,
+        parsed_options: dict[str, Any] | None = None,
+        **opts: Any,
+    ) -> list[Path]:
+        parsed_options = parsed_options or {}
+        self._skills_mode = bool(parsed_options.get("skills"))
+        if self._skills_mode:
+            return _OpencodeSkillsHelper().setup(project_root, manifest, parsed_options, **opts)
+        return super().setup(project_root, manifest, parsed_options, **opts)
 
     def build_exec_args(
         self,