@botdocs/cli 0.9.0 → 0.9.1

package/dist/commands/ingest.js

@@ -280,12 +280,26 @@ export const DETECTORS = {
         scanPaths: () => [],
     },
     codex: {
+        // Codex skills are nested SKILL.md directories, mirroring claude:
+        // ~/.codex/skills/<slug>/SKILL.md (developers.openai.com/codex/skills).
         pathPrefix: 'codex/',
-        extensions: ['.md'],
-        nested: false,
-        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
-        canonicalFilename: (slug) => `codex/${slug}.md`,
-        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.codex', 'skills')] : [],
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel.endsWith('/SKILL.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `codex/${slug}/SKILL.md`,
+        // Global only — Codex skills live under ~/.codex/skills/.
+        scanPaths: (homeDir) => [path.join(homeDir, '.codex', 'skills')],
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `codex/${slug}/${relPath}`,
     },
     copilot: {
         pathPrefix: 'copilot/instructions/',
@@ -297,36 +311,90 @@ export const DETECTORS = {
         scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.github', 'instructions')] : [],
     },
     windsurf: {
+        // Windsurf reads project rules from <proj>/.windsurf/rules/<slug>.md
+        // (docs.windsurf.com). Flat .md rule files, project-scoped (git repo).
         pathPrefix: 'windsurf/rules/',
         extensions: ['.md'],
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `windsurf/rules/${slug}.md`,
-        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.codeium', 'windsurf-rules')] : [],
+        scanPaths: (_homeDir, projectRoot, isGitRepo) => isGitRepo ? [path.join(projectRoot, '.windsurf', 'rules')] : [],
     },
     gemini: {
+        // Gemini CLI has NO per-skill file directory. It uses hierarchical
+        // GEMINI.md context files (~/.gemini/GEMINI.md global, ./GEMINI.md
+        // project) — there's nothing to auto-discover and nowhere to drop a
+        // per-skill file. The entry stays present so the ecosystem still exists
+        // for compile/variants, but discovery returns nothing (like chatgpt) and
+        // install routes it to `manual` (see detectDestination).
         pathPrefix: 'gemini/instructions/',
         extensions: ['.md'],
         nested: false,
         slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
         canonicalFilename: (slug) => `gemini/instructions/${slug}.md`,
-        scanPaths: (homeDir) => [path.join(homeDir, '.gemini', 'instructions')],
+        // No canonical on-disk location — nothing to discover.
+        scanPaths: () => [],
     },
     antigravity: {
+        // Antigravity skills are nested SKILL.md directories, mirroring claude:
+        // ~/.gemini/antigravity/skills/<slug>/SKILL.md (global) and
+        // <proj>/.agent/skills/<slug>/SKILL.md (project)
+        // (antigravity.google/docs/skills + Google Codelabs). Keep the existing
+        // `antigravity/skills/` canonical prefix, now nested-with-SKILL.md.
         pathPrefix: 'antigravity/skills/',
-        extensions: ['.md'],
-        nested: false,
-        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
-        canonicalFilename: (slug) => `antigravity/skills/${slug}.md`,
-        scanPaths: (homeDir) => [path.join(homeDir, '.gemini', 'antigravity', 'skills')],
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel.endsWith('/SKILL.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `antigravity/skills/${slug}/SKILL.md`,
+        // Global ~/.gemini/antigravity/skills always; project <proj>/.agent/skills
+        // only inside a git repo.
+        scanPaths: (homeDir, projectRoot, isGitRepo) => {
+            const paths = [path.join(homeDir, '.gemini', 'antigravity', 'skills')];
+            if (isGitRepo)
+                paths.push(path.join(projectRoot, '.agent', 'skills'));
+            return paths;
+        },
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `antigravity/skills/${slug}/${relPath}`,
     },
     opencode: {
-        pathPrefix: 'opencode/instructions/',
-        extensions: ['.md'],
-        nested: false,
-        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
-        canonicalFilename: (slug) => `opencode/instructions/${slug}.md`,
-        scanPaths: (homeDir) => [path.join(homeDir, '.config', 'opencode', 'instructions')],
+        // OpenCode skills are nested SKILL.md directories, mirroring claude:
+        // ~/.config/opencode/skills/<slug>/SKILL.md (global) and
+        // <proj>/.opencode/skills/<slug>/SKILL.md (project)
+        // (opencode.ai/docs/skills).
+        pathPrefix: 'opencode/',
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            if (!rel.endsWith('/SKILL.md'))
+                return null;
+            const parts = rel.split('/');
+            if (parts.length < 2)
+                return null;
+            return parts[parts.length - 2] ?? null;
+        },
+        canonicalFilename: (slug) => `opencode/${slug}/SKILL.md`,
+        // Global ~/.config/opencode/skills always; project <proj>/.opencode/skills
+        // only inside a git repo.
+        scanPaths: (homeDir, projectRoot, isGitRepo) => {
+            const paths = [path.join(homeDir, '.config', 'opencode', 'skills')];
+            if (isGitRepo)
+                paths.push(path.join(projectRoot, '.opencode', 'skills'));
+            return paths;
+        },
+        includeAdjacent: true,
+        skillRoot: (abs) => path.dirname(abs),
+        canonicalAdjacentFilename: (slug, relPath) => `opencode/${slug}/${relPath}`,
     },
 };
 export const SUPPORTED_TOOLS = Object.keys(DETECTORS);

package/dist/index.js

@@ -106,7 +106,7 @@ program
 });
 program
     .command('install <ref>')
-    .description('Install a skill or bundle locally (skills go to ~/.claude/skills/, project files to .cursor/rules/, .codex/skills/, .github/instructions/, etc.)')
+    .description('Install a skill or bundle locally (skills go to ~/.claude/skills/, project files to .cursor/rules/, .github/instructions/, .windsurf/rules/, etc.)')
     .option('--project <dir>', 'Override the project root used for project-local files')
     .option('--flat', 'Skip the {scope} subdirectory in install paths (collision-prone, not recommended)')
     .option('--clean', 'Wipe-and-reinstall instead of additive')

package/dist/lib/auto-detect.js

@@ -47,10 +47,24 @@ export function detectDestination(srcRelative, ctx) {
         };
     }
     if (src.startsWith('codex/')) {
-        return {
-            kind: 'project',
-            dest: path.join(ctx.projectDir, '.codex', 'skills', path.basename(src)),
-        };
+        // Codex skills are nested SKILL.md directories at
+        // ~/.codex/skills/<slug>/SKILL.md (developers.openai.com/codex/skills).
+        // New canonical form: codex/<slug>/SKILL.md (+ adjacent files). Strip the
+        // `codex/<slug>/` prefix and keep the relpath under ~/.codex/skills/<slug>/.
+        //
+        // Backward-compat: BotDocs published before this fix stored flat
+        // `codex/<slug>.md`. We detect the flat form (no inner slash) and route it
+        // to the new nested destination ~/.codex/skills/<slug>/SKILL.md so already-
+        // published docs still install where Codex reads them.
+        const remainder = src.slice('codex/'.length);
+        const codexBase = path.join(ctx.homeDir, '.codex', 'skills');
+        if (!remainder.includes('/')) {
+            // Flat legacy form `codex/<slug>.md` → nested SKILL.md.
+            const slug = remainder.replace(/\.md$/, '');
+            return { kind: 'global', dest: path.join(codexBase, slug, 'SKILL.md') };
+        }
+        const finalName = remainder.replace(/^[^/]+\//, '');
+        return { kind: 'global', dest: path.join(codexBase, ctx.slug, finalName) };
     }
     if (src.startsWith('copilot/instructions/')) {
         // GitHub Copilot custom instructions live in .github/instructions/
@@ -61,36 +75,66 @@ export function detectDestination(srcRelative, ctx) {
         };
     }
     if (src.startsWith('windsurf/rules/')) {
-        // Windsurf (Codeium) reads project rules from .codeium/windsurf-rules/
-        // (https://docs.codeium.com/windsurf/cascade#windsurfrules).
+        // Windsurf reads project rules from <proj>/.windsurf/rules/<slug>.md
+        // (docs.windsurf.com). Flat .md rule, project-scoped. The canonical form
+        // is already flat, so basename() is the right leaf either way.
         return {
             kind: 'project',
-            dest: path.join(ctx.projectDir, '.codeium', 'windsurf-rules', path.basename(src)),
+            dest: path.join(ctx.projectDir, '.windsurf', 'rules', path.basename(src)),
         };
     }
-    if (src.startsWith('gemini/instructions/')) {
-        // Gemini CLI reads global instructions from ~/.gemini/instructions/
-        // (https://github.com/google-gemini/gemini-cli).
-        return {
-            kind: 'global',
-            dest: path.join(ctx.homeDir, '.gemini', 'instructions', path.basename(src)),
-        };
+    if (src.startsWith('gemini/')) {
+        // Gemini CLI has NO per-skill file directory — it uses hierarchical
+        // GEMINI.md context files (~/.gemini/GEMINI.md global, ./GEMINI.md
+        // project). There's no real path to write to, so route to `manual` (like
+        // chatgpt): install surfaces the content for the user to paste into their
+        // GEMINI.md or @import it, rather than fabricating ~/.gemini/instructions/.
+        return { kind: 'manual', dest: src };
     }
     if (src.startsWith('antigravity/skills/')) {
-        // Google Antigravity reads skills from ~/.gemini/antigravity/skills/
-        // (shares the gemini config tree).
-        return {
-            kind: 'global',
-            dest: path.join(ctx.homeDir, '.gemini', 'antigravity', 'skills', path.basename(src)),
-        };
+        // Antigravity skills are nested SKILL.md directories
+        // (antigravity.google/docs/skills). Project: <proj>/.agent/skills/<slug>/…
+        // Global mirror: ~/.gemini/antigravity/skills/<slug>/… We prefer the
+        // project destination when a project dir applies (matching cursor/codex-
+        // commands which default to project).
+        //
+        // New canonical form: antigravity/skills/<slug>/SKILL.md (+ adjacent).
+        // Strip the `antigravity/skills/<slug>/` prefix, keep the relpath.
+        //
+        // Backward-compat: docs published before this fix stored flat
+        // `antigravity/skills/<slug>.md`. Detect the flat form and route it to the
+        // new nested destination so already-published docs still install.
+        const remainder = src.slice('antigravity/skills/'.length);
+        const agentBase = path.join(ctx.projectDir, '.agent', 'skills');
+        if (!remainder.includes('/')) {
+            const slug = remainder.replace(/\.md$/, '');
+            return { kind: 'project', dest: path.join(agentBase, slug, 'SKILL.md') };
+        }
+        const finalName = remainder.replace(/^[^/]+\//, '');
+        return { kind: 'project', dest: path.join(agentBase, ctx.slug, finalName) };
     }
-    if (src.startsWith('opencode/instructions/')) {
-        // OpenCode (SST) reads instructions from ~/.config/opencode/instructions/
-        // (https://github.com/sst/opencode).
-        return {
-            kind: 'global',
-            dest: path.join(ctx.homeDir, '.config', 'opencode', 'instructions', path.basename(src)),
-        };
+    if (src.startsWith('opencode/')) {
+        // OpenCode skills are nested SKILL.md directories (opencode.ai/docs/skills).
+        // Project: <proj>/.opencode/skills/<slug>/… Global mirror:
+        // ~/.config/opencode/skills/<slug>/… We prefer the project destination
+        // when a project dir applies (matching cursor/codex-commands).
+        //
+        // New canonical form: opencode/<slug>/SKILL.md (+ adjacent). Strip the
+        // `opencode/<slug>/` prefix, keep the relpath.
+        //
+        // Backward-compat: docs published before this fix stored flat
+        // `opencode/instructions/<slug>.md`. Detect that legacy prefix and route
+        // it to the new nested destination so already-published docs still install.
+        const opencodeBase = path.join(ctx.projectDir, '.opencode', 'skills');
+        if (src.startsWith('opencode/instructions/')) {
+            const slug = path.basename(src).replace(/\.md$/, '');
+            return { kind: 'project', dest: path.join(opencodeBase, slug, 'SKILL.md') };
+        }
+        const remainder = src.slice('opencode/'.length);
+        const finalName = remainder.includes('/')
+            ? remainder.replace(/^[^/]+\//, '')
+            : remainder;
+        return { kind: 'project', dest: path.join(opencodeBase, ctx.slug, finalName) };
     }
     if (src.startsWith('chatgpt/')) {
         return { kind: 'manual', dest: src };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "CLI for BotDocs — author, publish, install, and sync agent skills across Claude, Claude Code, Cursor, Codex, ChatGPT, Windsurf, Copilot, Gemini, Antigravity, and OpenCode.",
   "keywords": [
     "botdocs",