feat(gemini-cli): switch to native subagents (#565)

Migrates Gemini CLI to native subagents (~/.gemini/agents/) + quotes zk-steward description. Rebased from #472; e2e-verified with real gemini v0.43.0. Closes #473.

Co-Authored-By: Tomo Wang <tomo_wang@163.com>

.gitignore

@@ -69,6 +69,7 @@ NOTES.md
 integrations/antigravity/agency-*/
 integrations/gemini-cli/skills/
 integrations/gemini-cli/gemini-extension.json
+integrations/gemini-cli/agents
 integrations/opencode/agents/
 integrations/cursor/rules/
 integrations/aider/CONVENTIONS.md

README.md

@@ -608,7 +608,7 @@ The installer scans your system for installed tools, shows a checkbox UI, and le
   [x]  1)  [*]  Claude Code     (claude.ai/code)
   [x]  2)  [*]  Copilot         (~/.github + ~/.copilot)
   [x]  3)  [*]  Antigravity     (~/.gemini/antigravity)
-  [ ]  4)  [ ]  Gemini CLI      (gemini extension)
+  [ ]  4)  [ ]  Gemini CLI      (~/.gemini/agents)
   [ ]  5)  [ ]  OpenCode        (opencode.ai)
   [ ]  6)  [ ]  OpenClaw        (~/.openclaw/agency-agents)
   [x]  7)  [*]  Cursor          (.cursor/rules)
@@ -704,8 +704,8 @@ See [integrations/antigravity/README.md](integrations/antigravity/README.md) for
 <details>
 <summary><strong>Gemini CLI</strong></summary>
 
-Installs as a Gemini CLI extension with one skill per agent plus a manifest.
+Installs as Gemini CLI subagents.
-On a fresh clone, generate the Gemini extension files before running the installer.
+On a fresh clone, generate the Gemini agent files before running the installer.
 
 ```bash
 ./scripts/convert.sh --tool gemini-cli

integrations/README.md

@@ -8,7 +8,7 @@ supported agentic coding tools.
 - **[Claude Code](#claude-code)** — `.md` agents, use the repo directly
 - **[GitHub Copilot](#github-copilot)** — `.md` agents, use the repo directly
 - **[Antigravity](#antigravity)** — `SKILL.md` per agent in `antigravity/`
-- **[Gemini CLI](#gemini-cli)** — extension + `SKILL.md` files in `gemini-cli/`
+- **[Gemini CLI](#gemini-cli)** — `.md` agent files in `gemini-cli/agents/`
 - **[OpenCode](#opencode)** — `.md` agent files in `opencode/`
 - **[OpenClaw](#openclaw)** — `SOUL.md` + `AGENTS.md` + `IDENTITY.md` workspaces
 - **[Cursor](#cursor)** — `.mdc` rule files in `cursor/`
@@ -104,9 +104,9 @@ See [antigravity/README.md](antigravity/README.md) for details.
 
 ## Gemini CLI
 
-Agents are packaged as a Gemini CLI extension with individual skill files.
+Agents are packaged as Gemini CLI subagents.
-The extension is installed to `~/.gemini/extensions/agency-agents/`.
+Subagents are installed to `~/.gemini/agents/`.
-Because the Gemini manifest and skill folders are generated artifacts, run
+Because the agent files are generated artifacts, run
 `./scripts/convert.sh --tool gemini-cli` before installing from a fresh clone.
 
 ```bash

integrations/gemini-cli/README.md

@@ -1,35 +1,39 @@
 # Gemini CLI Integration
 
-Packages all Agency agents as a Gemini CLI extension. The extension
+Packages all Agency agents as Gemini CLI subagents. These agents
-installs to `~/.gemini/extensions/agency-agents/`.
+install to `~/.gemini/agents/`.
 
 ## Install
 
 ```bash
-# Generate the Gemini CLI integration files first
+# Generate the Gemini CLI agent files first
 ./scripts/convert.sh --tool gemini-cli
 
-# Then install the extension
+# Then install them to ~/.gemini/agents/
 ./scripts/install.sh --tool gemini-cli
 ```
 
-## Activate a Skill
+## Use an Agent
 
-In Gemini CLI, reference an agent by name:
+In Gemini CLI, reference an agent by name in your prompt:
 
 ```
-Use the frontend-developer skill to help me build this UI.
+Use the frontend-developer agent to help me build this UI.
 ```
 
-## Extension Structure
+Or invoke the agent directly if your version of Gemini CLI supports it:
+
+```bash
+gemini --agent frontend-developer "How should I structure this React component?"
+```
+
+## Structure
 
 ```
-~/.gemini/extensions/agency-agents/
+~/.gemini/agents/
-  gemini-extension.json
+  frontend-developer.md
-  skills/
+  backend-architect.md
-    frontend-developer/SKILL.md
+  reality-checker.md
-    backend-architect/SKILL.md
-    reality-checker/SKILL.md
   ...
 ```
 

scripts/convert.sh

@@ -11,7 +11,7 @@
 #
 # Tools:
 #   antigravity  — Antigravity skill files (~/.gemini/antigravity/skills/)
-#   gemini-cli   — Gemini CLI extension (skills/ + gemini-extension.json)
+#   gemini-cli   — Gemini CLI subagent files (~/.gemini/agents/*.md)
 #   opencode     — OpenCode agent files (.opencode/agents/*.md)
 #   cursor       — Cursor rule files (.cursor/rules/*.mdc)
 #   aider        — Single CONVENTIONS.md for Aider
@@ -179,11 +179,11 @@ convert_gemini_cli() {
   slug="$(slugify "$name")"
   body="$(get_body "$file")"
 
-  outdir="$OUT_DIR/gemini-cli/skills/$slug"
+  # Gemini CLI subagent format: .md file in ~/.gemini/agents/
-  outfile="$outdir/SKILL.md"
+  outdir="$OUT_DIR/gemini-cli/agents"
+  outfile="$outdir/${slug}.md"
   mkdir -p "$outdir"
 
-  # Gemini CLI skill format: minimal frontmatter (name + description only)
   cat > "$outfile" <<HEREDOC
 ---
 name: ${slug}
@@ -638,19 +638,6 @@ main() {
       local count
       count="$(run_conversions "$t")"
       total=$(( total + count ))
-
-      # Gemini CLI also needs the extension manifest (written by this process when --tool gemini-cli)
-      if [[ "$t" == "gemini-cli" ]]; then
-        mkdir -p "$OUT_DIR/gemini-cli"
-        cat > "$OUT_DIR/gemini-cli/gemini-extension.json" <<'HEREDOC'
-{
-  "name": "agency-agents",
-  "version": "1.0.0"
-}
-HEREDOC
-        info "Wrote gemini-extension.json"
-      fi
-
       info "Converted $count agents for $t"
     done
   fi

scripts/install.sh

@@ -13,7 +13,7 @@
 #   claude-code  -- Copy agents to ~/.claude/agents/
 #   copilot      -- Copy agents to ~/.github/agents/ and ~/.copilot/agents/
 #   antigravity  -- Copy skills to ~/.gemini/antigravity/skills/
-#   gemini-cli   -- Install extension to ~/.gemini/extensions/agency-agents/
+#   gemini-cli   -- Install agents to ~/.gemini/agents/
 #   opencode     -- Copy agents to .opencode/agents/ in current directory
 #   cursor       -- Copy rules to .cursor/rules/ in current directory
 #   aider        -- Copy CONVENTIONS.md to current directory
@@ -176,7 +176,7 @@ tool_label() {
     claude-code) printf "%-14s  %s" "Claude Code"  "(claude.ai/code)"        ;;
     copilot)     printf "%-14s  %s" "Copilot"      "(~/.github + ~/.copilot)" ;;
     antigravity) printf "%-14s  %s" "Antigravity"  "(~/.gemini/antigravity)" ;;
-    gemini-cli)  printf "%-14s  %s" "Gemini CLI"   "(gemini extension)"      ;;
+    gemini-cli)  printf "%-14s  %s" "Gemini CLI"   "(~/.gemini/agents)"      ;;
     opencode)    printf "%-14s  %s" "OpenCode"     "(opencode.ai)"           ;;
     openclaw)    printf "%-14s  %s" "OpenClaw"     "(~/.openclaw/agency-agents)" ;;
     cursor)      printf "%-14s  %s" "Cursor"       "(.cursor/rules)"         ;;
@@ -362,24 +362,17 @@ install_antigravity() {
 }
 
 install_gemini_cli() {
-  local src="$INTEGRATIONS/gemini-cli"
+  local src="$INTEGRATIONS/gemini-cli/agents"
-  local dest="${HOME}/.gemini/extensions/agency-agents"
+  local dest="${HOME}/.gemini/agents"
   local count=0
-  local manifest="$src/gemini-extension.json"
+  [[ -d "$src" ]] || { err "integrations/gemini-cli/agents missing. Run ./scripts/convert.sh --tool gemini-cli first."; return 1; }
-  local skills_dir="$src/skills"
+  mkdir -p "$dest"
-  [[ -d "$src" ]] || { err "integrations/gemini-cli missing. Run ./scripts/convert.sh --tool gemini-cli first."; return 1; }
+  local f
-  [[ -f "$manifest" ]] || { err "integrations/gemini-cli/gemini-extension.json missing. Run ./scripts/convert.sh --tool gemini-cli first."; return 1; }
+  while IFS= read -r -d '' f; do
-  [[ -d "$skills_dir" ]] || { err "integrations/gemini-cli/skills missing. Run ./scripts/convert.sh --tool gemini-cli first."; return 1; }
+    cp "$f" "$dest/"
-  mkdir -p "$dest/skills"
-  cp "$manifest" "$dest/gemini-extension.json"
-  local d
-  while IFS= read -r -d '' d; do
-    local name; name="$(basename "$d")"
-    mkdir -p "$dest/skills/$name"
-    cp "$d/SKILL.md" "$dest/skills/$name/SKILL.md"
     (( count++ )) || true
-  done < <(find "$skills_dir" -mindepth 1 -maxdepth 1 -type d -print0)
+  done < <(find "$src" -maxdepth 1 -name "*.md" -print0)
-  ok "Gemini CLI: $count skills -> $dest"
+  ok "Gemini CLI: $count agents -> $dest"
 }
 
 install_opencode() {

specialized/zk-steward.md

@@ -1,6 +1,6 @@
 ---
 name: ZK Steward
-description: Knowledge-base steward in the spirit of Niklas Luhmann's Zettelkasten. Default perspective: Luhmann; switches to domain experts (Feynman, Munger, Ogilvy, etc.) by task. Enforces atomic notes, connectivity, and validation loops. Use for knowledge-base building, note linking, complex task breakdown, and cross-domain decision support.
+description: "Knowledge-base steward in the spirit of Niklas Luhmann's Zettelkasten. Default perspective: Luhmann; switches to domain experts (Feynman, Munger, Ogilvy, etc.) by task. Enforces atomic notes, connectivity, and validation loops. Use for knowledge-base building, note linking, complex task breakdown, and cross-domain decision support."
 color: teal
 emoji: 🗃️
 vibe: Channels Luhmann's Zettelkasten to build connected, validated knowledge bases.