flowbook 0.1.6 → 0.2.1

package/README.md

@@ -30,6 +30,7 @@ npm run build-flowbook
 flowbook init                Set up Flowbook in your project
 flowbook dev  [--port 6200]  Start the dev server
 flowbook build [--out-dir d] Build a static site
+flowbook skill <agent> [-g]  Install AI agent skill & /flowbook command
 ```
 
 ### `flowbook init`
@@ -91,7 +92,7 @@ Ignores `node_modules/`, `.git/`, and `dist/`.
 
 ## AI Agent Skill
 
-`flowbook init` automatically installs AI agent skills to all supported coding agent directories.
+Use `flowbook skill` to install AI agent skills and `/flowbook` slash commands for your coding agents.
 When a coding agent (Claude Code, OpenAI Codex, VS Code Copilot, Cursor, Gemini CLI, etc.) detects the keyword **"flowbook"** in your prompt, it will:
 
 1. Analyze your codebase for logical flows (API routes, auth, state management, business logic, etc.)
@@ -99,56 +100,77 @@ When a coding agent (Claude Code, OpenAI Codex, VS Code Copilot, Cursor, Gemini
 3. Generate `.flow.md` files with Mermaid diagrams for every significant flow
 4. Verify the build
 
-### Install Skill via CLI
+### `flowbook skill`
 
-You can also install the skill standalone using [skills.sh](https://skills.sh):
+Install skills and `/flowbook` slash commands for specific agents:
 
 ```bash
-npx skills add Epsilondelta-ai/flowbook
+# Install for a specific agent (project-level)
+flowbook skill opencode
+flowbook skill claude
+flowbook skill cursor
+
+# Install for all agents
+flowbook skill all
+
+# Install globally (available across all projects)
+flowbook skill opencode -g
+flowbook skill all --global
 ```
 
-This auto-detects your installed coding agents and installs the skill to the correct directories.
+**What gets installed:**
+
+| Component | Description |
+|-----------|-------------|
+| **Skill** (`SKILL.md`) | Auto-triggers when you mention "flowbook" in prompts |
+| **Slash command** (`/flowbook`) | Explicit trigger — type `/flowbook` to generate flowcharts |
 
-### Global Installation
+Slash commands are installed for agents that support them: **Claude Code**, **Cursor**, **Windsurf**, **OpenCode**.
 
-To install the skill globally (available across all projects):
+### Install via skills.sh
+
+You can also install the skill standalone using [skills.sh](https://skills.sh):
 
 ```bash
+# Project-level
+npx skills add Epsilondelta-ai/flowbook
+
+# Global
 npx skills add -g Epsilondelta-ai/flowbook
 ```
 
-This installs the skill to each agent's global directory (e.g., `~/.claude/skills/`, `~/.config/opencode/skills/`, etc.).
+> **Note:** `npx skills add` installs skills only (SKILL.md). Use `flowbook skill` to also install `/flowbook` slash commands.
 
-### Compatible Agents
+### Supported Agents
 
-| Agent | Skill Location |
-|-------|---------------|
-| Claude Code | `.claude/skills/flowbook/SKILL.md` |
-| OpenAI Codex | `.agents/skills/flowbook/SKILL.md` |
-| VS Code / GitHub Copilot | `.github/skills/flowbook/SKILL.md` |
-| Google Antigravity | `.agent/skills/flowbook/SKILL.md` |
-| Gemini CLI | `.gemini/skills/flowbook/SKILL.md` |
-| Cursor | `.cursor/skills/flowbook/SKILL.md` |
-| Windsurf (Codeium) | `.windsurf/skills/flowbook/SKILL.md` |
-| AmpCode | `.amp/skills/flowbook/SKILL.md` |
-| OpenCode / oh-my-opencode | `.opencode/skills/flowbook/SKILL.md` |
+| Agent | Skill | Slash Command |
+|-------|-------|---------------|
+| Claude Code | `.claude/skills/flowbook/SKILL.md` | `.claude/commands/flowbook.md` |
+| OpenAI Codex | `.agents/skills/flowbook/SKILL.md` | — |
+| VS Code / GitHub Copilot | `.github/skills/flowbook/SKILL.md` | — |
+| Google Antigravity | `.agent/skills/flowbook/SKILL.md` | — |
+| Gemini CLI | `.gemini/skills/flowbook/SKILL.md` | — |
+| Cursor | `.cursor/skills/flowbook/SKILL.md` | `.cursor/commands/flowbook.md` |
+| Windsurf (Codeium) | `.windsurf/skills/flowbook/SKILL.md` | `.windsurf/workflows/flowbook.md` |
+| AmpCode | `.amp/skills/flowbook/SKILL.md` | — |
+| OpenCode / oh-my-opencode | `.opencode/skills/flowbook/SKILL.md` | `.opencode/command/flowbook.md` |
 
 <details>
-<summary>Manual Skill Installation</summary>
+<summary>Manual Installation</summary>
 
-If you didn't use `flowbook init` or `npx skills add`, copy the skill manually:
+If you didn't use `flowbook skill` or `npx skills add`, copy files manually:
 
 ```bash
-# Example: Claude Code
+# Skill
 mkdir -p .claude/skills/flowbook
 cp node_modules/flowbook/src/skills/flowbook/SKILL.md .claude/skills/flowbook/
 
-# Example: Cursor
-mkdir -p .cursor/skills/flowbook
-cp node_modules/flowbook/src/skills/flowbook/SKILL.md .cursor/skills/flowbook/
+# Slash command (Claude Code)
+mkdir -p .claude/commands
+cp node_modules/flowbook/src/commands/flowbook.md .claude/commands/
 ```
 
-Replace the directory with the appropriate path from the Compatible Agents table above.
+Replace directories with the appropriate paths from the table above.
 
 </details>
 ## How It Works
@@ -175,12 +197,19 @@ Replace the directory with the appropriate path from the Compatible Agents table
 src/
 ├── types.ts                    # Shared types (FlowEntry, FlowbookData)
 ├── node/
-│   ├── cli.ts                  # CLI entry point (init, dev, build)
+│   ├── cli.ts                  # CLI entry point (init, dev, build, skill)
 │   ├── server.ts               # Programmatic Vite server & build
 │   ├── init.ts                 # Project initialization logic
+│   ├── skill.ts                # AI agent skill & command installer
 │   ├── discovery.ts            # File scanner (fast-glob)
 │   ├── parser.ts               # Frontmatter + mermaid extraction
 │   └── plugin.ts               # Vite virtual module plugin
+├── skills/
+│   └── flowbook/
+│       └── SKILL.md            # AI agent skill definition
+├── commands/
+│   ├── flowbook.md             # Slash command (frontmatter format)
+│   └── flowbook.plain.md       # Slash command (plain markdown format)
 └── client/
     ├── index.html              # Entry HTML
     ├── main.tsx                # React entry
@@ -193,7 +222,6 @@ src/
         ├── MermaidRenderer.tsx # Mermaid diagram rendering
         ├── FlowView.tsx        # Single flow detail view
         └── EmptyState.tsx      # Empty state with guide
-```
 
 ## Development (Contributing)
 

package/dist/cli.js

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 
 // src/node/init.ts
-import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "fs";
-import { resolve, dirname } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { resolve } from "path";
 import { execSync } from "child_process";
-import { fileURLToPath } from "url";
-var __dirname = dirname(fileURLToPath(import.meta.url));
 var EXAMPLE_FLOW = `---
 title: Example Flow
 category: Getting Started
@@ -74,48 +72,12 @@ async function initFlowbook() {
       console.log("  \u2713 Added flowbook-static to .gitignore");
     }
   }
-  const skillSrc = resolve(__dirname, "..", "src", "skills", "flowbook", "SKILL.md");
-  const skillDirs = [
-    resolve(cwd, ".claude", "skills", "flowbook"),
-    // Claude Code
-    resolve(cwd, ".agents", "skills", "flowbook"),
-    // OpenAI Codex / cross-tool alias
-    resolve(cwd, ".github", "skills", "flowbook"),
-    // VS Code / GitHub Copilot
-    resolve(cwd, ".agent", "skills", "flowbook"),
-    // Google Antigravity
-    resolve(cwd, ".gemini", "skills", "flowbook"),
-    // Gemini CLI
-    resolve(cwd, ".cursor", "skills", "flowbook"),
-    // Cursor
-    resolve(cwd, ".windsurf", "skills", "flowbook"),
-    // Windsurf (Codeium)
-    resolve(cwd, ".amp", "skills", "flowbook"),
-    // AmpCode
-    resolve(cwd, ".opencode", "skills", "flowbook")
-    // OpenCode / oh-my-opencode
-  ];
-  if (existsSync(skillSrc)) {
-    let installed = 0;
-    for (const dir of skillDirs) {
-      const dest = resolve(dir, "SKILL.md");
-      if (!existsSync(dest)) {
-        mkdirSync(dir, { recursive: true });
-        copyFileSync(skillSrc, dest);
-        installed++;
-      }
-    }
-    if (installed > 0) {
-      console.log(`  \u2713 Installed AI agent skill to ${installed} agent directories`);
-    } else {
-      console.log("  \u2713 AI agent skills already installed");
-    }
-  }
   const run = pm === "yarn" ? "yarn" : `${pm} run`;
   console.log("");
   console.log("  Next steps:");
-  console.log(`    ${run} flowbook       Start the dev server`);
-  console.log(`    ${run} build-flowbook  Build static site`);
+  console.log(`    ${run} flowbook              Start the dev server`);
+  console.log(`    ${run} build-flowbook         Build static site`);
+  console.log(`    flowbook skill <agent> [-g]   Install AI skill & /flowbook command`);
   console.log("");
 }
 function detectPackageManager(cwd) {
@@ -228,11 +190,11 @@ function flowbookPlugin(options = {}) {
 }
 
 // src/node/server.ts
-import { resolve as resolve2, dirname as dirname2 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
-var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
+import { resolve as resolve2, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
 function getClientDir() {
-  return resolve2(__dirname2, "..", "src", "client");
+  return resolve2(__dirname, "..", "src", "client");
 }
 function createConfig(options) {
   const cwd = options.cwd ?? process.cwd();
@@ -272,6 +234,196 @@ async function buildStatic(options) {
 `);
 }
 
+// src/node/skill.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, copyFileSync } from "fs";
+import { resolve as resolve3, dirname as dirname2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { homedir } from "os";
+var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
+var AGENTS = [
+  {
+    name: "Claude Code",
+    aliases: ["claude"],
+    skill: {
+      project: ".claude/skills/flowbook",
+      global: ".claude/skills/flowbook"
+    },
+    command: {
+      project: ".claude/commands",
+      global: ".claude/commands",
+      format: "frontmatter"
+    }
+  },
+  {
+    name: "OpenAI Codex",
+    aliases: ["codex"],
+    skill: {
+      project: ".agents/skills/flowbook",
+      global: ".codex/skills/flowbook"
+    }
+  },
+  {
+    name: "VS Code / GitHub Copilot",
+    aliases: ["copilot", "vscode"],
+    skill: {
+      project: ".github/skills/flowbook",
+      global: ".copilot/skills/flowbook"
+    }
+  },
+  {
+    name: "Google Antigravity",
+    aliases: ["antigravity"],
+    skill: {
+      project: ".agent/skills/flowbook",
+      global: ".gemini/antigravity/skills/flowbook"
+    }
+  },
+  {
+    name: "Gemini CLI",
+    aliases: ["gemini"],
+    skill: {
+      project: ".gemini/skills/flowbook",
+      global: ".gemini/skills/flowbook"
+    }
+  },
+  {
+    name: "Cursor",
+    aliases: ["cursor"],
+    skill: {
+      project: ".cursor/skills/flowbook",
+      global: ".cursor/skills/flowbook"
+    },
+    command: {
+      project: ".cursor/commands",
+      global: ".cursor/commands",
+      format: "plain"
+    }
+  },
+  {
+    name: "Windsurf",
+    aliases: ["windsurf"],
+    skill: {
+      project: ".windsurf/skills/flowbook",
+      global: ".codeium/windsurf/skills/flowbook"
+    },
+    command: {
+      project: ".windsurf/workflows",
+      global: ".codeium/windsurf/workflows",
+      format: "plain"
+    }
+  },
+  {
+    name: "AmpCode",
+    aliases: ["amp"],
+    skill: {
+      project: ".amp/skills/flowbook",
+      global: ".config/agents/skills/flowbook"
+    }
+  },
+  {
+    name: "OpenCode",
+    aliases: ["opencode"],
+    skill: {
+      project: ".opencode/skills/flowbook",
+      global: ".config/opencode/skills/flowbook"
+    },
+    command: {
+      project: ".opencode/command",
+      global: ".config/opencode/command",
+      format: "frontmatter"
+    }
+  }
+];
+function getSkillSrc() {
+  return resolve3(__dirname2, "..", "src", "skills", "flowbook", "SKILL.md");
+}
+function getCommandSrc(format) {
+  const file = format === "frontmatter" ? "flowbook.md" : "flowbook.plain.md";
+  return resolve3(__dirname2, "..", "src", "commands", file);
+}
+function resolveAgents(agentArg) {
+  if (agentArg === "all") return AGENTS;
+  const lower = agentArg.toLowerCase();
+  const found = AGENTS.filter(
+    (a) => a.aliases.includes(lower) || a.name.toLowerCase().includes(lower)
+  );
+  if (found.length === 0) {
+    console.error(`  Unknown agent: "${agentArg}"`);
+    console.error(`  Available: all, ${AGENTS.flatMap((a) => a.aliases).join(", ")}`);
+    process.exit(1);
+  }
+  return found;
+}
+function installFile(src, destDir, destFilename) {
+  const dest = resolve3(destDir, destFilename);
+  if (existsSync2(dest)) return false;
+  mkdirSync2(destDir, { recursive: true });
+  copyFileSync(src, dest);
+  return true;
+}
+function installSkills(agentArg, global) {
+  const agents = resolveAgents(agentArg);
+  const base = global ? homedir() : process.cwd();
+  const skillSrc = getSkillSrc();
+  if (!existsSync2(skillSrc)) {
+    console.error("  \u2717 Skill source file not found. Reinstall flowbook.");
+    process.exit(1);
+  }
+  let skillCount = 0;
+  let cmdCount = 0;
+  for (const agent of agents) {
+    const skillDir = resolve3(base, global ? agent.skill.global : agent.skill.project);
+    if (installFile(skillSrc, skillDir, "SKILL.md")) {
+      skillCount++;
+    }
+    if (agent.command) {
+      const cmdSrc = getCommandSrc(agent.command.format);
+      if (existsSync2(cmdSrc)) {
+        const cmdDir = resolve3(base, global ? agent.command.global : agent.command.project);
+        if (installFile(cmdSrc, cmdDir, "flowbook.md")) {
+          cmdCount++;
+        }
+      }
+    }
+  }
+  const scope = global ? "global" : "project";
+  const agentNames = agents.map((a) => a.name).join(", ");
+  if (skillCount > 0 || cmdCount > 0) {
+    if (skillCount > 0) console.log(`  \u2713 Installed skill to ${skillCount} ${scope} director${skillCount > 1 ? "ies" : "y"}`);
+    if (cmdCount > 0) console.log(`  \u2713 Installed /flowbook command to ${cmdCount} ${scope} director${cmdCount > 1 ? "ies" : "y"}`);
+    console.log(`  Agents: ${agentNames}`);
+  } else {
+    console.log(`  \u2713 Already installed for: ${agentNames}`);
+  }
+}
+function printSkillUsage() {
+  console.log(`
+  flowbook skill \u2014 Install AI agent skill & /flowbook command
+
+  Usage:
+    flowbook skill <agent>           Install to project
+    flowbook skill <agent> --global  Install globally
+    flowbook skill <agent> -g        Install globally (short)
+
+  Agents:
+    all          All supported agents
+    claude       Claude Code
+    codex        OpenAI Codex
+    copilot      VS Code / GitHub Copilot
+    antigravity  Google Antigravity
+    gemini       Gemini CLI
+    cursor       Cursor
+    windsurf     Windsurf (Codeium)
+    amp          AmpCode
+    opencode     OpenCode / oh-my-opencode
+
+  Examples:
+    flowbook skill all              Install to all agents (project)
+    flowbook skill opencode -g      Install globally for OpenCode
+    flowbook skill claude --global  Install globally for Claude Code
+`);
+}
+
 // src/node/cli.ts
 async function main() {
   const args = process.argv.slice(2);
@@ -290,6 +442,16 @@ async function main() {
       await buildStatic({ outDir });
       break;
     }
+    case "skill": {
+      const agent = args[1];
+      if (!agent) {
+        printSkillUsage();
+        break;
+      }
+      const isGlobal = args.includes("--global") || args.includes("-g");
+      installSkills(agent, isGlobal);
+      break;
+    }
     default:
       printUsage();
       break;
@@ -308,10 +470,13 @@ function printUsage() {
     flowbook init                Set up Flowbook in your project
     flowbook dev  [--port 6200]  Start the dev server
     flowbook build [--out-dir d] Build a static site
+    flowbook skill <agent> [-g]  Install AI agent skill & command
 
   Options:
     --port <number>    Dev server port (default: 6200)
     --out-dir <path>   Build output directory (default: flowbook-static)
+
+  Run 'flowbook skill' for agent-specific options.
 `);
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowbook",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "flowbook": "./dist/cli.js"

package/src/commands/flowbook.md

@@ -0,0 +1,13 @@
+---
+description: Analyze codebase and generate Mermaid flowchart documentation using Flowbook
+---
+
+Load the **flowbook** skill and execute the full flowchart generation workflow.
+
+When prompted with `/flowbook`, you MUST:
+
+1. Load the `flowbook` skill (SKILL.md) for detailed instructions
+2. Analyze the codebase for logical flows (API routes, auth, state management, business logic)
+3. Set up Flowbook if not already initialized (`npx flowbook@latest init`)
+4. Generate `.flow.md` files with Mermaid diagrams for every significant flow
+5. Run `npm run flowbook` to verify the build

package/src/commands/flowbook.plain.md

@@ -0,0 +1,13 @@
+# /flowbook — Flowchart Documentation Generator
+
+Analyze codebase and generate Mermaid flowchart documentation using Flowbook.
+
+Load the **flowbook** skill and execute the full flowchart generation workflow.
+
+When prompted with `/flowbook`, you MUST:
+
+1. Load the `flowbook` skill (SKILL.md) for detailed instructions
+2. Analyze the codebase for logical flows (API routes, auth, state management, business logic)
+3. Set up Flowbook if not already initialized (`npx flowbook@latest init`)
+4. Generate `.flow.md` files with Mermaid diagrams for every significant flow
+5. Run `npm run flowbook` to verify the build

package/src/node/cli.ts

@@ -1,5 +1,6 @@
 import { initFlowbook } from "./init";
 import { startDevServer, buildStatic } from "./server";
+import { installSkills, printSkillUsage } from "./skill";
 
 async function main() {
   const args = process.argv.slice(2);
@@ -22,6 +23,17 @@ async function main() {
       break;
     }
 
+    case "skill": {
+      const agent = args[1];
+      if (!agent) {
+        printSkillUsage();
+        break;
+      }
+      const isGlobal = args.includes("--global") || args.includes("-g");
+      installSkills(agent, isGlobal);
+      break;
+    }
+
     default:
       printUsage();
       break;
@@ -46,10 +58,13 @@ function printUsage() {
     flowbook init                Set up Flowbook in your project
     flowbook dev  [--port 6200]  Start the dev server
     flowbook build [--out-dir d] Build a static site
+    flowbook skill <agent> [-g]  Install AI agent skill & command
 
   Options:
     --port <number>    Dev server port (default: 6200)
     --out-dir <path>   Build output directory (default: flowbook-static)
+
+  Run 'flowbook skill' for agent-specific options.
 `);
 }
 

package/src/node/init.ts

@@ -1,9 +1,7 @@
-import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve } from "node:path";
 import { execSync } from "node:child_process";
-import { fileURLToPath } from "node:url";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
 
 const EXAMPLE_FLOW = `---
 title: Example Flow
@@ -88,42 +86,12 @@ export async function initFlowbook() {
     }
   }
 
-  // 5. Install AI agent skill to all supported agent directories
-  const skillSrc = resolve(__dirname, "..", "src", "skills", "flowbook", "SKILL.md");
-  const skillDirs = [
-    resolve(cwd, ".claude", "skills", "flowbook"),     // Claude Code
-    resolve(cwd, ".agents", "skills", "flowbook"),     // OpenAI Codex / cross-tool alias
-    resolve(cwd, ".github", "skills", "flowbook"),     // VS Code / GitHub Copilot
-    resolve(cwd, ".agent", "skills", "flowbook"),      // Google Antigravity
-    resolve(cwd, ".gemini", "skills", "flowbook"),     // Gemini CLI
-    resolve(cwd, ".cursor", "skills", "flowbook"),     // Cursor
-    resolve(cwd, ".windsurf", "skills", "flowbook"),   // Windsurf (Codeium)
-    resolve(cwd, ".amp", "skills", "flowbook"),        // AmpCode
-    resolve(cwd, ".opencode", "skills", "flowbook"),   // OpenCode / oh-my-opencode
-  ];
-
-  if (existsSync(skillSrc)) {
-    let installed = 0;
-    for (const dir of skillDirs) {
-      const dest = resolve(dir, "SKILL.md");
-      if (!existsSync(dest)) {
-        mkdirSync(dir, { recursive: true });
-        copyFileSync(skillSrc, dest);
-        installed++;
-      }
-    }
-    if (installed > 0) {
-      console.log(`  \u2713 Installed AI agent skill to ${installed} agent directories`);
-    } else {
-      console.log("  \u2713 AI agent skills already installed");
-    }
-  }
-
   const run = pm === "yarn" ? "yarn" : `${pm} run`;
   console.log("");
   console.log("  Next steps:");
-  console.log(`    ${run} flowbook       Start the dev server`);
-  console.log(`    ${run} build-flowbook  Build static site`);
+  console.log(`    ${run} flowbook              Start the dev server`);
+  console.log(`    ${run} build-flowbook         Build static site`);
+  console.log(`    flowbook skill <agent> [-g]   Install AI skill & /flowbook command`);
   console.log("");
 }
 

package/src/node/skill.ts

@@ -0,0 +1,230 @@
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface AgentConfig {
+  name: string;
+  aliases: string[];
+  skill: { project: string; global: string };
+  command?: { project: string; global: string; format: "frontmatter" | "plain" };
+}
+
+const AGENTS: AgentConfig[] = [
+  {
+    name: "Claude Code",
+    aliases: ["claude"],
+    skill: {
+      project: ".claude/skills/flowbook",
+      global: ".claude/skills/flowbook",
+    },
+    command: {
+      project: ".claude/commands",
+      global: ".claude/commands",
+      format: "frontmatter",
+    },
+  },
+  {
+    name: "OpenAI Codex",
+    aliases: ["codex"],
+    skill: {
+      project: ".agents/skills/flowbook",
+      global: ".codex/skills/flowbook",
+    },
+  },
+  {
+    name: "VS Code / GitHub Copilot",
+    aliases: ["copilot", "vscode"],
+    skill: {
+      project: ".github/skills/flowbook",
+      global: ".copilot/skills/flowbook",
+    },
+  },
+  {
+    name: "Google Antigravity",
+    aliases: ["antigravity"],
+    skill: {
+      project: ".agent/skills/flowbook",
+      global: ".gemini/antigravity/skills/flowbook",
+    },
+  },
+  {
+    name: "Gemini CLI",
+    aliases: ["gemini"],
+    skill: {
+      project: ".gemini/skills/flowbook",
+      global: ".gemini/skills/flowbook",
+    },
+  },
+  {
+    name: "Cursor",
+    aliases: ["cursor"],
+    skill: {
+      project: ".cursor/skills/flowbook",
+      global: ".cursor/skills/flowbook",
+    },
+    command: {
+      project: ".cursor/commands",
+      global: ".cursor/commands",
+      format: "plain",
+    },
+  },
+  {
+    name: "Windsurf",
+    aliases: ["windsurf"],
+    skill: {
+      project: ".windsurf/skills/flowbook",
+      global: ".codeium/windsurf/skills/flowbook",
+    },
+    command: {
+      project: ".windsurf/workflows",
+      global: ".codeium/windsurf/workflows",
+      format: "plain",
+    },
+  },
+  {
+    name: "AmpCode",
+    aliases: ["amp"],
+    skill: {
+      project: ".amp/skills/flowbook",
+      global: ".config/agents/skills/flowbook",
+    },
+  },
+  {
+    name: "OpenCode",
+    aliases: ["opencode"],
+    skill: {
+      project: ".opencode/skills/flowbook",
+      global: ".config/opencode/skills/flowbook",
+    },
+    command: {
+      project: ".opencode/command",
+      global: ".config/opencode/command",
+      format: "frontmatter",
+    },
+  },
+];
+
+function getSkillSrc(): string {
+  return resolve(__dirname, "..", "src", "skills", "flowbook", "SKILL.md");
+}
+
+function getCommandSrc(format: "frontmatter" | "plain"): string {
+  const file = format === "frontmatter" ? "flowbook.md" : "flowbook.plain.md";
+  return resolve(__dirname, "..", "src", "commands", file);
+}
+
+function resolveAgents(agentArg: string): AgentConfig[] {
+  if (agentArg === "all") return AGENTS;
+
+  const lower = agentArg.toLowerCase();
+  const found = AGENTS.filter(
+    (a) =>
+      a.aliases.includes(lower) ||
+      a.name.toLowerCase().includes(lower),
+  );
+
+  if (found.length === 0) {
+    console.error(`  Unknown agent: "${agentArg}"`);
+    console.error(`  Available: all, ${AGENTS.flatMap((a) => a.aliases).join(", ")}`);
+    process.exit(1);
+  }
+
+  return found;
+}
+
+function installFile(src: string, destDir: string, destFilename: string): boolean {
+  const dest = resolve(destDir, destFilename);
+  if (existsSync(dest)) return false;
+  mkdirSync(destDir, { recursive: true });
+  copyFileSync(src, dest);
+  return true;
+}
+
+export function installSkills(agentArg: string, global: boolean): void {
+  const agents = resolveAgents(agentArg);
+  const base = global ? homedir() : process.cwd();
+  const skillSrc = getSkillSrc();
+
+  if (!existsSync(skillSrc)) {
+    console.error("  ✗ Skill source file not found. Reinstall flowbook.");
+    process.exit(1);
+  }
+
+  let skillCount = 0;
+  let cmdCount = 0;
+
+  for (const agent of agents) {
+    const skillDir = resolve(base, global ? agent.skill.global : agent.skill.project);
+    if (installFile(skillSrc, skillDir, "SKILL.md")) {
+      skillCount++;
+    }
+
+    if (agent.command) {
+      const cmdSrc = getCommandSrc(agent.command.format);
+      if (existsSync(cmdSrc)) {
+        const cmdDir = resolve(base, global ? agent.command.global : agent.command.project);
+        if (installFile(cmdSrc, cmdDir, "flowbook.md")) {
+          cmdCount++;
+        }
+      }
+    }
+  }
+
+  const scope = global ? "global" : "project";
+  const agentNames = agents.map((a) => a.name).join(", ");
+
+  if (skillCount > 0 || cmdCount > 0) {
+    if (skillCount > 0) console.log(`  ✓ Installed skill to ${skillCount} ${scope} director${skillCount > 1 ? "ies" : "y"}`);
+    if (cmdCount > 0) console.log(`  ✓ Installed /flowbook command to ${cmdCount} ${scope} director${cmdCount > 1 ? "ies" : "y"}`);
+    console.log(`  Agents: ${agentNames}`);
+  } else {
+    console.log(`  ✓ Already installed for: ${agentNames}`);
+  }
+}
+
+/** Used by init.ts — installs skills only (no commands) to all agents at project level */
+export function installAllProjectSkills(): number {
+  const cwd = process.cwd();
+  const skillSrc = getSkillSrc();
+  if (!existsSync(skillSrc)) return 0;
+
+  let installed = 0;
+  for (const agent of AGENTS) {
+    const dir = resolve(cwd, agent.skill.project);
+    if (installFile(skillSrc, dir, "SKILL.md")) {
+      installed++;
+    }
+  }
+  return installed;
+}
+
+export function printSkillUsage(): void {
+  console.log(`
+  flowbook skill — Install AI agent skill & /flowbook command
+
+  Usage:
+    flowbook skill <agent>           Install to project
+    flowbook skill <agent> --global  Install globally
+    flowbook skill <agent> -g        Install globally (short)
+
+  Agents:
+    all          All supported agents
+    claude       Claude Code
+    codex        OpenAI Codex
+    copilot      VS Code / GitHub Copilot
+    antigravity  Google Antigravity
+    gemini       Gemini CLI
+    cursor       Cursor
+    windsurf     Windsurf (Codeium)
+    amp          AmpCode
+    opencode     OpenCode / oh-my-opencode
+
+  Examples:
+    flowbook skill all              Install to all agents (project)
+    flowbook skill opencode -g      Install globally for OpenCode
+    flowbook skill claude --global  Install globally for Claude Code
+`);
+}