feat(gemini): update skill files to use YAML frontmatter format

Author: Akagi201

pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.10.2,<0.11.1"]
+requires = ["uv-build>=0.10.2,<0.11.2"]
 build-backend = "uv_build"
 
 [project]
 name = "pb-spec"
-version = "0.8.8"
+version = "0.8.9"
 description = "Plan-Build Spec (pb-spec): A CLI tool for managing AI coding assistant skills"
 readme = "README.md"
 license = "Apache-2.0"

src/pb_spec/platforms/gemini.py

@@ -2,25 +2,22 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
 
-from pb_spec.platforms.base import SKILL_METADATA, PromptOnlyPlatform
+from pb_spec.platforms.base import SKILL_METADATA, Platform
 
 
-class GeminiPlatform(PromptOnlyPlatform):
-    """Gemini CLI — custom commands in .gemini/commands/<name>.toml."""
+class GeminiPlatform(Platform):
+    """Gemini CLI — skills as .gemini/skills/<name>/SKILL.md."""
 
     name = "gemini"
 
     def get_skill_path(self, cwd: Path, skill_name: str, global_install: bool = False) -> Path:
         if global_install:
-            return Path.home() / ".gemini" / "commands" / f"{skill_name}.toml"
-        return cwd / ".gemini" / "commands" / f"{skill_name}.toml"
+            return Path.home() / ".gemini" / "skills" / skill_name / "SKILL.md"
+        return cwd / ".gemini" / "skills" / skill_name / "SKILL.md"
 
     def render_skill(self, skill_name: str, template_content: str) -> str:
-        description = SKILL_METADATA.get(skill_name, "")
-        desc_value = json.dumps(description, ensure_ascii=False)
-        escaped = template_content.rstrip().replace("\\", "\\\\").replace('"', '\\"')
-        prompt_value = '"""\n' + escaped + '\n"""'
-        return f"description = {desc_value}\nprompt = {prompt_value}\n"
+        description = SKILL_METADATA.get(skill_name, "").replace('"', '\\"')
+        frontmatter = f'---\nname: {skill_name}\ndescription: "{description}"\n---\n\n'
+        return frontmatter + template_content

tests/test_e2e.py

@@ -72,10 +72,19 @@ def test_e2e_init_all_creates_complete_structure(tmp_path, monkeypatch, runner):
     ).exists()
 
     # Gemini files
-    assert (tmp_path / ".gemini" / "commands" / "pb-init.toml").exists()
-    assert (tmp_path / ".gemini" / "commands" / "pb-plan.toml").exists()
-    assert (tmp_path / ".gemini" / "commands" / "pb-refine.toml").exists()
-    assert (tmp_path / ".gemini" / "commands" / "pb-build.toml").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-init" / "SKILL.md").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-plan" / "SKILL.md").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-refine" / "SKILL.md").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-build" / "SKILL.md").exists()
+    assert (
+        tmp_path / ".gemini" / "skills" / "pb-plan" / "references" / "design_template.md"
+    ).exists()
+    assert (
+        tmp_path / ".gemini" / "skills" / "pb-plan" / "references" / "tasks_template.md"
+    ).exists()
+    assert (
+        tmp_path / ".gemini" / "skills" / "pb-build" / "references" / "implementer_prompt.md"
+    ).exists()
 
     # Codex files
     assert (tmp_path / ".codex" / "prompts" / "pb-init.md").exists()
@@ -118,15 +127,16 @@ def test_e2e_copilot_no_frontmatter(tmp_path, monkeypatch, runner):
         assert not content.startswith("---"), f"Copilot {prompt} should not have frontmatter"
 
 
-def test_e2e_gemini_toml_format(tmp_path, monkeypatch, runner):
-    """Verify Gemini command files are TOML with description and prompt fields."""
+def test_e2e_gemini_frontmatter(tmp_path, monkeypatch, runner):
+    """Verify Gemini SKILL.md files have YAML frontmatter."""
     monkeypatch.chdir(tmp_path)
     runner.invoke(main, ["init", "--ai", "gemini"])
 
-    for command in ["pb-init", "pb-plan", "pb-refine", "pb-build"]:
-        content = (tmp_path / ".gemini" / "commands" / f"{command}.toml").read_text()
-        assert content.startswith('description = "'), f"Gemini {command} missing description field"
-        assert '\nprompt = """\n' in content, f"Gemini {command} missing prompt field"
+    for skill in ["pb-init", "pb-plan", "pb-refine", "pb-build"]:
+        content = (tmp_path / ".gemini" / "skills" / skill / "SKILL.md").read_text()
+        assert content.startswith("---\n"), f"Gemini {skill} missing frontmatter"
+        assert "name:" in content, f"Gemini {skill} missing name: in frontmatter"
+        assert "description:" in content, f"Gemini {skill} missing description: in frontmatter"
 
 
 def test_e2e_codex_frontmatter(tmp_path, monkeypatch, runner):
@@ -152,6 +162,9 @@ def test_e2e_references_exist(tmp_path, monkeypatch, runner):
         ".opencode/skills/pb-plan/references/design_template.md",
         ".opencode/skills/pb-plan/references/tasks_template.md",
         ".opencode/skills/pb-build/references/implementer_prompt.md",
+        ".gemini/skills/pb-plan/references/design_template.md",
+        ".gemini/skills/pb-plan/references/tasks_template.md",
+        ".gemini/skills/pb-build/references/implementer_prompt.md",
     }
     for ref in expected_refs:
         ref_path = tmp_path / ref
@@ -215,18 +228,15 @@ def test_e2e_copilot_no_references_dir(tmp_path, monkeypatch, runner):
         assert child.is_file(), f"Unexpected directory in Copilot prompts: {child}"
 
 
-def test_e2e_gemini_and_codex_no_references_dir(tmp_path, monkeypatch, runner):
-    """Verify Gemini/Codex platforms do not create references directories."""
+def test_e2e_codex_no_references_dir(tmp_path, monkeypatch, runner):
+    """Verify Codex platform does not create references directories."""
     monkeypatch.chdir(tmp_path)
-    runner.invoke(main, ["init", "--ai", "all"])
+    runner.invoke(main, ["init", "--ai", "codex"])
 
-    for directory in [
-        tmp_path / ".gemini" / "commands",
-        tmp_path / ".codex" / "prompts",
-    ]:
-        assert directory.exists()
-        for child in directory.iterdir():
-            assert child.is_file(), f"Unexpected directory in prompt folder: {child}"
+    prompts_dir = tmp_path / ".codex" / "prompts"
+    assert prompts_dir.exists()
+    for child in prompts_dir.iterdir():
+        assert child.is_file(), f"Unexpected directory in Codex prompts: {child}"
 
 
 def test_e2e_rendered_platforms_preserve_workflow_contract_language(tmp_path, monkeypatch, runner):
@@ -252,11 +262,6 @@ def test_e2e_rendered_platforms_preserve_workflow_contract_language(tmp_path, mo
             "pb-build": tmp_path / ".github" / "prompts" / "pb-build.prompt.md",
             "pb-refine": tmp_path / ".github" / "prompts" / "pb-refine.prompt.md",
         },
-        "gemini": {
-            "pb-plan": tmp_path / ".gemini" / "commands" / "pb-plan.toml",
-            "pb-build": tmp_path / ".gemini" / "commands" / "pb-build.toml",
-            "pb-refine": tmp_path / ".gemini" / "commands" / "pb-refine.toml",
-        },
         "codex": {
             "pb-plan": tmp_path / ".codex" / "prompts" / "pb-plan.md",
             "pb-build": tmp_path / ".codex" / "prompts" / "pb-build.md",

tests/test_init.py

@@ -95,16 +95,29 @@ def test_init_opencode(tmp_path, monkeypatch, runner):
 
 
 def test_init_gemini(tmp_path, monkeypatch, runner):
-    """pb-spec init --ai gemini creates .gemini command TOML files."""
+    """pb-spec init --ai gemini creates .gemini/skills/ SKILL.md files with references."""
     monkeypatch.chdir(tmp_path)
     result = runner.invoke(main, ["init", "--ai", "gemini"])
 
     assert result.exit_code == 0, result.output
 
-    assert (tmp_path / ".gemini" / "commands" / "pb-init.toml").exists()
-    assert (tmp_path / ".gemini" / "commands" / "pb-plan.toml").exists()
-    assert (tmp_path / ".gemini" / "commands" / "pb-refine.toml").exists()
-    assert (tmp_path / ".gemini" / "commands" / "pb-build.toml").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-init" / "SKILL.md").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-plan" / "SKILL.md").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-refine" / "SKILL.md").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-build" / "SKILL.md").exists()
+
+    # Reference files for pb-plan
+    assert (
+        tmp_path / ".gemini" / "skills" / "pb-plan" / "references" / "design_template.md"
+    ).exists()
+    assert (
+        tmp_path / ".gemini" / "skills" / "pb-plan" / "references" / "tasks_template.md"
+    ).exists()
+
+    # Reference files for pb-build
+    assert (
+        tmp_path / ".gemini" / "skills" / "pb-build" / "references" / "implementer_prompt.md"
+    ).exists()
 
 
 # --- pb init --ai codex ---
@@ -140,7 +153,7 @@ def test_init_all(tmp_path, monkeypatch, runner):
     # OpenCode
     assert (tmp_path / ".opencode" / "skills" / "pb-init" / "SKILL.md").exists()
     # Gemini
-    assert (tmp_path / ".gemini" / "commands" / "pb-init.toml").exists()
+    assert (tmp_path / ".gemini" / "skills" / "pb-init" / "SKILL.md").exists()
     # Codex
     assert (tmp_path / ".codex" / "prompts" / "pb-init.md").exists()
 
@@ -168,7 +181,7 @@ def test_init_all_global_installs_to_agent_home_dirs(tmp_path, monkeypatch, runn
     # OpenCode
     assert (config_home / "opencode" / "skills" / "pb-init" / "SKILL.md").exists()
     # Gemini
-    assert (home / ".gemini" / "commands" / "pb-init.toml").exists()
+    assert (home / ".gemini" / "skills" / "pb-init" / "SKILL.md").exists()
     # Codex
     assert (home / ".codex" / "prompts" / "pb-init.md").exists()
 
@@ -234,14 +247,13 @@ def test_init_copilot_no_frontmatter(tmp_path, monkeypatch, runner):
     assert not content.startswith("---")
 
 
-def test_init_gemini_toml_shape(tmp_path, monkeypatch, runner):
-    """Gemini command files should be TOML with description and prompt fields."""
+def test_init_gemini_has_frontmatter(tmp_path, monkeypatch, runner):
+    """Gemini SKILL.md files should start with YAML frontmatter."""
     monkeypatch.chdir(tmp_path)
     runner.invoke(main, ["init", "--ai", "gemini"])
 
-    content = (tmp_path / ".gemini" / "commands" / "pb-init.toml").read_text()
-    assert content.startswith('description = "')
-    assert '\nprompt = """\n' in content
+    content = (tmp_path / ".gemini" / "skills" / "pb-init" / "SKILL.md").read_text()
+    assert content.startswith("---")
 
 
 def test_init_codex_has_frontmatter(tmp_path, monkeypatch, runner):
@@ -267,7 +279,6 @@ def test_init_prompt_only_pb_build_contains_shared_implementer_contract(
     ).read_text()
     rendered_prompt_only_outputs = {
         "copilot": (tmp_path / ".github" / "prompts" / "pb-build.prompt.md").read_text(),
-        "gemini": (tmp_path / ".gemini" / "commands" / "pb-build.toml").read_text(),
         "codex": (tmp_path / ".codex" / "prompts" / "pb-build.md").read_text(),
     }
 

tests/test_platforms.py

@@ -49,7 +49,7 @@ def test_opencode_skill_path():
 def test_gemini_skill_path():
     p = GeminiPlatform()
     cwd = Path("/project")
-    assert p.get_skill_path(cwd, "pb-init") == Path("/project/.gemini/commands/pb-init.toml")
+    assert p.get_skill_path(cwd, "pb-init") == Path("/project/.gemini/skills/pb-init/SKILL.md")
 
 
 def test_codex_skill_path():
@@ -94,7 +94,7 @@ def test_gemini_global_skill_path(monkeypatch):
     p = GeminiPlatform()
     cwd = Path("/project")
     assert p.get_skill_path(cwd, "pb-init", global_install=True) == Path(
-        "/users/alice/.gemini/commands/pb-init.toml"
+        "/users/alice/.gemini/skills/pb-init/SKILL.md"
     )
 
 
@@ -133,11 +133,11 @@ def test_opencode_render_has_yaml_frontmatter():
     assert "# Hello" in result
 
 
-def test_gemini_render_toml_prompt():
+def test_gemini_render_has_yaml_frontmatter():
     p = GeminiPlatform()
     result = p.render_skill("pb-init", "# Hello")
-    assert result.startswith('description = "')
-    assert 'prompt = """' in result
+    assert result.startswith("---\n")
+    assert "name: pb-init" in result
     assert "# Hello" in result