@botdocs/cli 0.9.0 → 0.10.0

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/commands/install.d.ts

@@ -7,6 +7,11 @@ interface InstallOptions {
      * CI where backups are noise; default behavior backs up untracked or
      * locally-edited files to `.botdocs-backup/<ts>/` before the overwrite. */
     noBackup?: boolean;
+    /** Cross-install the skill into a DIFFERENT agent ecosystem than the one it
+     * was authored in. Comma-separated list of ecosystems, or `all` (every
+     * supported ecosystem except the skill's own source). Deterministic — no LLM.
+     * When absent, install writes the stored canonical files as today. */
+    to?: string;
 }
 export declare function install(rawRef: string, options: InstallOptions): Promise<void>;
 export {};

package/dist/commands/install.js

@@ -3,9 +3,19 @@ import os from 'node:os';
 import path from 'node:path';
 import { ApiError, apiFetch, fetchRawContent } from '../lib/api.js';
 import { detectDestination } from '../lib/auto-detect.js';
+import { SUPPORTED_ECOSYSTEMS } from '../lib/canonical.js';
+import { convertSkillToEcosystem, parseFrontmatter, stripFrontmatter, } from '../lib/convert.js';
 import { fingerprintContent, fingerprintFile, loadLockfile, upsertInstall, } from '../lib/lockfile.js';
 import { backupFile, isLockfileOwnedAndUnchanged } from '../lib/backup.js';
 import { syncLibrary } from '../lib/library-sync.js';
+/** Humanize a slug into a Title Case label: `senior-review` → `Senior Review`. */
+function humanizeSlug(slug) {
+    return slug
+        .split(/[-_]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
 function parseRef(raw) {
     const cleaned = raw.startsWith('@') ? raw.slice(1) : raw;
     const parts = cleaned.split('/');
@@ -26,15 +36,20 @@ function buildContext(scope, slug, options) {
 function ensureDir(filePath) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
 }
-async function downloadAndWrite(file, dest, options, projectDir) {
-    const content = await fetchRawContent(file.rawUrl);
+/**
+ * Write a single file's content to `dest`, honoring the additive no-op,
+ * backup-on-overwrite, and mode-restore rules. `src` is the logical source
+ * filename recorded in the lockfile. Shared by the manifest-download path and
+ * the `--to` cross-install path (which already has content in hand).
+ */
+function writeContentToDest(src, content, dest, mode, options, projectDir) {
     if (fs.existsSync(dest) && !options.clean) {
         const existingFp = fingerprintFile(dest);
         const tmpFp = fingerprintContent(content);
         if (existingFp === tmpFp) {
             // Already present at same fingerprint — additive no-op. No backup
             // needed: we're about to write the same bytes anyway.
-            return { src: file.filename, dest, fingerprint: existingFp };
+            return { src, dest, fingerprint: existingFp };
         }
     }
     // About to overwrite. If the existing file isn't something we own and
@@ -60,13 +75,17 @@ async function downloadAndWrite(file, dest, options, projectDir) {
     // explicitly chmod even when the value is 0o644 so a previously-executable
     // file at the dest gets re-normalized to non-executable on update.
     try {
-        fs.chmodSync(dest, file.mode ?? 0o644);
+        fs.chmodSync(dest, mode ?? 0o644);
     }
     catch {
         // chmod can fail on Windows / network mounts. Don't fail the install
         // over a permission cosmetic — the file still got written.
     }
-    return { src: file.filename, dest, fingerprint: fingerprintFile(dest) };
+    return { src, dest, fingerprint: fingerprintFile(dest) };
+}
+async function downloadAndWrite(file, dest, options, projectDir) {
+    const content = await fetchRawContent(file.rawUrl);
+    return writeContentToDest(file.filename, content, dest, file.mode, options, projectDir);
 }
 async function installSkill(ref, manifest, options, scope) {
     const ctx = buildContext(scope, ref.slug, options);
@@ -114,6 +133,213 @@ async function installSkill(ref, manifest, options, scope) {
         files: filesInstalled,
     };
 }
+/** Per-agent paste instructions for Bucket C ecosystems. */
+const MANUAL_INSTRUCTIONS = {
+    gemini: 'Add to ~/.gemini/GEMINI.md (or a project ./GEMINI.md), or @import it from there.',
+    chatgpt: "Paste into the custom GPT's Instructions field.",
+};
+/**
+ * Parse and validate the `--to` value. `all` expands to every supported
+ * ecosystem EXCEPT `sourceEcosystem` (skip re-emitting the source as itself).
+ * A comma-separated list is validated against the known ecosystem set; unknown
+ * entries are a hard error.
+ */
+function resolveTargets(rawTo, sourceEcosystem) {
+    const value = rawTo.trim();
+    if (value.toLowerCase() === 'all') {
+        return SUPPORTED_ECOSYSTEMS.filter((e) => e !== sourceEcosystem);
+    }
+    const requested = value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    const unknown = requested.filter((e) => !SUPPORTED_ECOSYSTEMS.includes(e));
+    if (unknown.length > 0) {
+        console.error(`\n  ✗ Unknown ecosystem(s) for --to: ${unknown.join(', ')}.\n` +
+            `    Supported: ${SUPPORTED_ECOSYSTEMS.join(', ')} (or "all").\n`);
+        process.exit(1);
+    }
+    // De-dup while preserving order.
+    return [...new Set(requested)];
+}
+/** Does this filename look like a primary skill doc? Ordered by priority. */
+function primaryDocRank(filename) {
+    const f = filename.toLowerCase();
+    if (f.endsWith('/skill.md') || f === 'skill.md')
+        return 0;
+    if (f.endsWith('/agent.md') || f === 'agent.md')
+        return 1;
+    if (f.endsWith('.md') || f.endsWith('.mdc'))
+        return 2;
+    return 3;
+}
+/**
+ * Download every file in a skill and distil its essence: the primary doc
+ * (name/description from frontmatter, body with frontmatter stripped) plus the
+ * remaining files as adjacent files keyed by a path relative to the primary
+ * doc's directory.
+ */
+async function extractEssence(skill) {
+    if (skill.files.length === 0)
+        return null;
+    // Pick the primary doc deterministically: best rank, then shortest path
+    // (a top-level SKILL.md beats a nested one), then lexicographic.
+    const sorted = [...skill.files].sort((a, b) => {
+        const ra = primaryDocRank(a.filename);
+        const rb = primaryDocRank(b.filename);
+        if (ra !== rb)
+            return ra - rb;
+        const da = a.filename.split('/').length;
+        const db = b.filename.split('/').length;
+        if (da !== db)
+            return da - db;
+        return a.filename.localeCompare(b.filename);
+    });
+    const primary = sorted[0];
+    if (primaryDocRank(primary.filename) === 3)
+        return null; // no markdown doc at all
+    const primaryRaw = await fetchRawContent(primary.rawUrl);
+    const fm = parseFrontmatter(primaryRaw);
+    // Adjacent files are everything else, made relative to the primary doc's
+    // directory so they re-nest correctly under the target's <slug>/ dir.
+    const primaryDir = primary.filename.includes('/')
+        ? primary.filename.slice(0, primary.filename.lastIndexOf('/') + 1)
+        : '';
+    const adjacentFiles = [];
+    for (const file of skill.files) {
+        if (file.filename === primary.filename)
+            continue;
+        const relPath = file.filename.startsWith(primaryDir)
+            ? file.filename.slice(primaryDir.length)
+            : file.filename;
+        const content = await fetchRawContent(file.rawUrl);
+        adjacentFiles.push({ relPath, content, mode: file.mode ?? 0o644 });
+    }
+    return {
+        slug: skill.ref.slug,
+        primaryBody: stripFrontmatter(primaryRaw),
+        name: fm.name ?? humanizeSlug(skill.ref.slug),
+        description: fm.description ?? '',
+        adjacentFiles,
+    };
+}
+/**
+ * Cross-install one skill into the requested target ecosystems. Each target's
+ * converted files run through the same `detectDestination` + write path as a
+ * normal install; Bucket C (`manual`) files are collected for printing instead
+ * of written.
+ */
+async function crossInstallSkill(skill, targets, options, scope) {
+    const essence = await extractEssence(skill);
+    const ctx = buildContext(scope, skill.ref.slug, options);
+    const filesInstalled = [];
+    const perTarget = [];
+    for (const target of targets) {
+        const result = {
+            ecosystem: target,
+            installed: [],
+            manual: [],
+            droppedAdjacent: [],
+        };
+        perTarget.push(result);
+        if (!essence)
+            continue; // nothing to convert — skill has no markdown doc
+        const converted = convertSkillToEcosystem(target, essence);
+        result.droppedAdjacent = converted.droppedAdjacent;
+        for (const file of converted.files) {
+            const detection = detectDestination(file.filename, ctx);
+            if (detection.kind === 'skip')
+                continue;
+            if (detection.kind === 'manual') {
+                result.manual.push({ ecosystem: target, filename: file.filename, content: file.content });
+                continue;
+            }
+            const installed = writeContentToDest(file.filename, file.content, detection.dest, file.mode, options, ctx.projectDir);
+            result.installed.push(installed);
+            filesInstalled.push(installed);
+        }
+    }
+    const entry = {
+        ref: `@${skill.ref.username}/${skill.ref.slug}`,
+        type: 'SKILL',
+        version: skill.version,
+        installedAt: new Date().toISOString(),
+        files: filesInstalled,
+    };
+    return { entry, perTarget };
+}
+/** Print human-readable cross-install output for one skill (non-JSON mode). */
+function reportCrossInstall(refStr, perTarget) {
+    for (const t of perTarget) {
+        if (t.manual.length > 0) {
+            for (const m of t.manual) {
+                console.log(`\n  ${t.ecosystem}: manual paste required.`);
+                const instr = MANUAL_INSTRUCTIONS[t.ecosystem];
+                if (instr)
+                    console.log(`    ${instr}`);
+                console.log(`\n${m.content}\n`);
+            }
+        }
+        else {
+            console.log(`    ${refStr} → ${t.ecosystem}: ${t.installed.length} file(s)`);
+        }
+        if (t.droppedAdjacent.length > 0) {
+            console.log(`  ⚠ ${t.ecosystem} is single-file — dropped ${t.droppedAdjacent.length} adjacent file(s): ${t.droppedAdjacent.join(', ')}`);
+        }
+    }
+}
+/**
+ * `--to` flow: cross-install a stored skill (or every skill in a bundle) into
+ * one or more DIFFERENT agent ecosystems, deterministically. Mirrors the main
+ * install path's lockfile + library-sync behavior.
+ */
+async function crossInstall(refStr, manifest, options, scope) {
+    const skills = manifest.type === 'SKILL'
+        ? [{ ref: manifest.ref, version: manifest.version, sourceEcosystem: manifest.sourceEcosystem, files: manifest.files }]
+        : manifest.skills.map((s) => ({
+            ref: s.ref,
+            version: s.version,
+            sourceEcosystem: s.sourceEcosystem,
+            files: s.files,
+        }));
+    const summaries = [];
+    const jsonInstalled = [];
+    const jsonManual = [];
+    const jsonDropped = {};
+    if (!options.json)
+        console.log(`\n  ✓ Cross-installing ${refStr} → ${options.to}`);
+    for (const skill of skills) {
+        const targets = resolveTargets(options.to, skill.sourceEcosystem);
+        const { entry, perTarget } = await crossInstallSkill(skill, targets, options, scope);
+        upsertInstall(entry);
+        summaries.push(entry);
+        if (options.json) {
+            for (const t of perTarget) {
+                if (t.installed.length > 0) {
+                    jsonInstalled.push({ ecosystem: t.ecosystem, files: t.installed.map((f) => f.dest) });
+                }
+                jsonManual.push(...t.manual);
+                if (t.droppedAdjacent.length > 0)
+                    jsonDropped[t.ecosystem] = t.droppedAdjacent;
+            }
+        }
+        else {
+            reportCrossInstall(entry.ref, perTarget);
+        }
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            ref: refStr,
+            installed: jsonInstalled,
+            manual: jsonManual.map((m) => ({ ecosystem: m.ecosystem, content: m.content })),
+            dropped: jsonDropped,
+        }));
+        await syncLibrary();
+        return;
+    }
+    console.log('');
+    await syncLibrary();
+}
 export async function install(rawRef, options) {
     const ref = parseRef(rawRef);
     const refStr = `@${ref.username}/${ref.slug}`;
@@ -150,6 +376,11 @@ export async function install(rawRef, options) {
         }
         throw err;
     }
+    // `--to`: cross-install into a different ecosystem (deterministic, no LLM).
+    if (options.to) {
+        await crossInstall(refStr, manifest, options, ref.username);
+        return;
+    }
     const installedSummaries = [];
     if (manifest.type === 'SKILL') {
         const entry = await installSkill(ref, manifest, options, ref.username);

package/dist/index.js

@@ -106,11 +106,12 @@ 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')
     .option('--no-backup', 'Do not back up files that would be overwritten (use in CI where backups are noise)')
+    .option('--to <ecosystems>', 'Install into a DIFFERENT agent ecosystem than the source (comma-separated list, or "all"). Deterministic, no LLM.')
     .action(async (ref, opts) => {
     // Commander's --no-backup convention sets opts.backup = false.
     // Translate to options.noBackup for downstream consumers.

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/dist/lib/canonical.js

@@ -20,11 +20,13 @@ const ECOSYSTEM_FILE_GLOB = {
     'claude-code': ['claude-code/commands'],
     cursor: ['cursor/rules'],
     chatgpt: ['chatgpt'],
+    // Nested SKILL.md ecosystems store under <prefix>/<slug>/SKILL.md — the
+    // detection dir is the ecosystem prefix (post-#99 canonical layout).
     codex: ['codex'],
     copilot: ['copilot/instructions'],
     antigravity: ['antigravity/skills'],
-    gemini: ['gemini/instructions'],
-    opencode: ['opencode/instructions'],
+    gemini: ['gemini'],
+    opencode: ['opencode'],
     windsurf: ['windsurf/rules'],
 };
 function readSize(filePath) {
@@ -34,10 +36,15 @@ function readSize(filePath) {
     if (stat.isFile())
         return stat.size;
     if (stat.isDirectory()) {
+        // Recurse so nested SKILL.md ecosystems (codex/<slug>/SKILL.md, etc.)
+        // contribute their content size, not just direct children.
         let total = 0;
         for (const entry of fs.readdirSync(filePath, { withFileTypes: true })) {
+            const child = path.join(filePath, entry.name);
             if (entry.isFile())
-                total += fs.statSync(path.join(filePath, entry.name)).size;
+                total += fs.statSync(child).size;
+            else if (entry.isDirectory())
+                total += readSize(child);
         }
         return total;
     }
@@ -68,25 +75,30 @@ export function ecosystemDestination(eco, slug) {
         case 'chatgpt':
             return `chatgpt/${slug}.md`;
         case 'codex':
-            return `codex/${slug}.md`;
+            // Codex skills are nested SKILL.md directories at ~/.codex/skills/<slug>/
+            // (developers.openai.com/codex/skills). The canonical source mirror is
+            // codex/<slug>/SKILL.md — matches the ingest DETECTORS layout post-#99.
+            return `codex/${slug}/SKILL.md`;
         case 'copilot':
             // GitHub Copilot custom instructions:
             // https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot
             return `copilot/instructions/${slug}.instructions.md`;
         case 'antigravity':
-            // Google Antigravity skills live under the gemini config tree at
-            // ~/.gemini/antigravity/skills/<slug>.md — see install destination in
-            // `auto-detect.ts`. The source mirror is `antigravity/skills/<slug>.md`.
-            return `antigravity/skills/${slug}.md`;
+            // Google Antigravity skills are nested SKILL.md directories
+            // (antigravity.google/docs/skills): ~/.gemini/antigravity/skills/<slug>/
+            // and <proj>/.agent/skills/<slug>/. Source mirror is the nested form.
+            return `antigravity/skills/${slug}/SKILL.md`;
         case 'gemini':
-            // Gemini CLI reads markdown instructions from ~/.gemini/instructions/
-            // (https://github.com/google-gemini/gemini-cli). Source path mirrors
-            // the install destination.
-            return `gemini/instructions/${slug}.md`;
+            // Gemini CLI has no per-skill file directory — it uses hierarchical
+            // GEMINI.md context files. We keep a sensible flat source mirror at
+            // gemini/<slug>.md, but install routes it to manual paste (no on-disk
+            // skill convention to write to).
+            return `gemini/${slug}.md`;
         case 'opencode':
-            // OpenCode (SST) reads markdown instructions from
-            // ~/.config/opencode/instructions/ (https://github.com/sst/opencode).
-            return `opencode/instructions/${slug}.md`;
+            // OpenCode skills are nested SKILL.md directories (opencode.ai/docs/skills):
+            // ~/.config/opencode/skills/<slug>/ and <proj>/.opencode/skills/<slug>/.
+            // Source mirror is the nested form.
+            return `opencode/${slug}/SKILL.md`;
         case 'windsurf':
             // Windsurf (Codeium) project rules:
             // https://docs.codeium.com/windsurf/cascade#windsurfrules — files live

package/dist/lib/convert.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Deterministic skill → ecosystem converter (consume-time).
+ *
+ * `botdocs install @ref --to <agent>` installs a stored skill into a DIFFERENT
+ * agent ecosystem than the one it was authored in, with no LLM. This module is
+ * the pure, dependency-free core: given the essence of a skill (slug, primary
+ * body, name/description, adjacent files) it re-emits the canonical files for a
+ * target ecosystem, using the SAME target-canonical-prefixed filenames that
+ * `botdocs ingest` would have stored — so the existing install write loop +
+ * `detectDestination` route placement unchanged.
+ *
+ * Targets fall in three buckets (see the README / PR body for the model):
+ *
+ *  - Bucket A — SKILL.md standard (`claude`, `codex`, `antigravity`,
+ *    `opencode`): identical `<slug>/SKILL.md` (+ adjacent files) format; only
+ *    the install dir differs. Re-emit the canonical SKILL.md with name/
+ *    description frontmatter + carry adjacent files under the target's prefix.
+ *  - Bucket B — rule/instruction reshape (`cursor`, `copilot`, `windsurf`,
+ *    `claude-code`): single-file. Take the primary doc body and re-emit it with
+ *    the target's activation frontmatter. Adjacent files are dropped (noted).
+ *  - Bucket C — paste/manual (`gemini`, `chatgpt`): no on-disk skill
+ *    convention. Emit the body at the canonical prefix; install routes these to
+ *    `manual` and prints them for copy-paste.
+ */
+import type { Ecosystem } from './canonical.js';
+export interface Frontmatter {
+    name?: string;
+    description?: string;
+}
+/**
+ * Parse a leading `---\n…\n---` block and return the top-level `name` and
+ * `description` scalars. Returns `{}` when there is no leading block. Only
+ * simple `key: value` lines are honored; the first occurrence of a key wins.
+ */
+export declare function parseFrontmatter(content: string): Frontmatter;
+/**
+ * Remove a leading `---\n…\n---` frontmatter block, returning just the body.
+ * Returns the original (sans BOM) when there is no leading block. Also trims
+ * any blank lines the block left at the very top.
+ */
+export declare function stripFrontmatter(content: string): string;
+/** The essence of a stored skill, distilled from the downloaded manifest files. */
+export interface SkillEssence {
+    /** Skill slug (used in canonical filenames and as a name fallback). */
+    slug: string;
+    /** Primary doc body, with any source frontmatter already stripped. */
+    primaryBody: string;
+    /** Human name for SKILL.md frontmatter (falls back to slug). */
+    name: string;
+    /** One-line description for SKILL.md frontmatter (may be empty). */
+    description: string;
+    /**
+     * Adjacent files (scripts/, templates/, reference docs) relative to the skill
+     * root, with their POSIX mode. Carried into Bucket A targets; dropped (and
+     * noted) for Bucket B/C.
+     */
+    adjacentFiles: Array<{
+        relPath: string;
+        content: string;
+        mode: number;
+    }>;
+}
+/** A single file the converter produced, ready for the install write loop. */
+export interface ConvertedFile {
+    /** Target-canonical-prefixed filename (the shape `ingest` would store). */
+    filename: string;
+    content: string;
+    /** POSIX permission bits to restore on disk. */
+    mode: number;
+}
+export interface ConvertResult {
+    files: ConvertedFile[];
+    /** Adjacent file relPaths that were dropped (Bucket B single-file targets). */
+    droppedAdjacent: string[];
+}
+/**
+ * Convert a stored skill into a target ecosystem's canonical files.
+ *
+ * Produced filenames are TARGET-canonical-prefixed (the same shape `ingest`
+ * would store), so the install write loop + `detectDestination` handle on-disk
+ * placement. Bucket C files route to `manual` at install time and are printed
+ * for copy-paste rather than written.
+ */
+export declare function convertSkillToEcosystem(target: Ecosystem, essence: SkillEssence): ConvertResult;

package/dist/lib/convert.js

@@ -0,0 +1,176 @@
+/**
+ * Deterministic skill → ecosystem converter (consume-time).
+ *
+ * `botdocs install @ref --to <agent>` installs a stored skill into a DIFFERENT
+ * agent ecosystem than the one it was authored in, with no LLM. This module is
+ * the pure, dependency-free core: given the essence of a skill (slug, primary
+ * body, name/description, adjacent files) it re-emits the canonical files for a
+ * target ecosystem, using the SAME target-canonical-prefixed filenames that
+ * `botdocs ingest` would have stored — so the existing install write loop +
+ * `detectDestination` route placement unchanged.
+ *
+ * Targets fall in three buckets (see the README / PR body for the model):
+ *
+ *  - Bucket A — SKILL.md standard (`claude`, `codex`, `antigravity`,
+ *    `opencode`): identical `<slug>/SKILL.md` (+ adjacent files) format; only
+ *    the install dir differs. Re-emit the canonical SKILL.md with name/
+ *    description frontmatter + carry adjacent files under the target's prefix.
+ *  - Bucket B — rule/instruction reshape (`cursor`, `copilot`, `windsurf`,
+ *    `claude-code`): single-file. Take the primary doc body and re-emit it with
+ *    the target's activation frontmatter. Adjacent files are dropped (noted).
+ *  - Bucket C — paste/manual (`gemini`, `chatgpt`): no on-disk skill
+ *    convention. Emit the body at the canonical prefix; install routes these to
+ *    `manual` and prints them for copy-paste.
+ */
+/** Strip a single matching pair of surrounding single/double quotes. */
+function unquote(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+const FRONTMATTER_FENCE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const FRONTMATTER_BLOCK = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+/**
+ * Parse a leading `---\n…\n---` block and return the top-level `name` and
+ * `description` scalars. Returns `{}` when there is no leading block. Only
+ * simple `key: value` lines are honored; the first occurrence of a key wins.
+ */
+export function parseFrontmatter(content) {
+    if (typeof content !== 'string')
+        return {};
+    const text = content.replace(/^\uFEFF/, '');
+    const match = text.match(FRONTMATTER_FENCE);
+    if (!match)
+        return {};
+    const block = match[1] ?? '';
+    const result = {};
+    for (const rawLine of block.split(/\r?\n/)) {
+        const lineMatch = rawLine.match(/^([A-Za-z0-9_-]+)[ \t]*:[ \t]*(.*)$/);
+        if (!lineMatch)
+            continue;
+        const key = lineMatch[1];
+        if (key !== 'name' && key !== 'description')
+            continue;
+        if (result[key] !== undefined)
+            continue; // first occurrence wins
+        const value = unquote(lineMatch[2].trim()).trim();
+        if (value.length > 0)
+            result[key] = value;
+    }
+    return result;
+}
+/**
+ * Remove a leading `---\n…\n---` frontmatter block, returning just the body.
+ * Returns the original (sans BOM) when there is no leading block. Also trims
+ * any blank lines the block left at the very top.
+ */
+export function stripFrontmatter(content) {
+    if (typeof content !== 'string')
+        return '';
+    const text = content.replace(/^\uFEFF/, '');
+    return text.replace(FRONTMATTER_BLOCK, '').replace(/^(?:[ \t]*\r?\n)+/, '');
+}
+/** Default mode for generated markdown files (non-executable). */
+const MD_MODE = 0o644;
+/** SKILL.md-standard targets (Bucket A) and their canonical directory prefix. */
+const BUCKET_A_PREFIX = {
+    claude: 'claude',
+    codex: 'codex',
+    antigravity: 'antigravity/skills',
+    opencode: 'opencode',
+};
+/**
+ * Bucket B single-file targets: the canonical filename for the reshaped doc and
+ * the activation frontmatter the target needs to be ACTIVE (not dormant). A
+ * `null` frontmatter means "no frontmatter" (claude-code commands are a flat
+ * body).
+ */
+const BUCKET_B = {
+    cursor: {
+        filename: (slug) => `cursor/rules/${slug}.mdc`,
+        // Bare .mdc is dormant/Manual; alwaysApply makes the rule active.
+        frontmatter: '---\nalwaysApply: true\n---',
+    },
+    copilot: {
+        filename: (slug) => `copilot/instructions/${slug}.instructions.md`,
+        // applyTo is required for Copilot to apply the instruction file.
+        frontmatter: '---\napplyTo: "**"\n---',
+    },
+    windsurf: {
+        filename: (slug) => `windsurf/rules/${slug}.md`,
+        frontmatter: '---\ntrigger: always_on\n---',
+    },
+    'claude-code': {
+        filename: (slug) => `claude-code/commands/${slug}.md`,
+        // Slash commands are a flat command body — no frontmatter.
+        frontmatter: null,
+    },
+};
+/** Bucket C paste/manual targets: a single body-only file at the canonical prefix. */
+const BUCKET_C = {
+    gemini: (slug) => `gemini/${slug}.md`,
+    chatgpt: (slug) => `chatgpt/${slug}.md`,
+};
+/** Build the canonical SKILL.md content: name/description frontmatter + body. */
+function buildSkillMd(essence) {
+    const name = essence.name || essence.slug;
+    const lines = ['---', `name: ${name}`, `description: ${essence.description}`, '---', '', essence.primaryBody];
+    return lines.join('\n');
+}
+/** Build a Bucket B reshaped file: optional activation frontmatter + body. */
+function buildReshaped(frontmatter, body) {
+    if (frontmatter === null)
+        return body;
+    return `${frontmatter}\n\n${body}`;
+}
+/**
+ * Convert a stored skill into a target ecosystem's canonical files.
+ *
+ * Produced filenames are TARGET-canonical-prefixed (the same shape `ingest`
+ * would store), so the install write loop + `detectDestination` handle on-disk
+ * placement. Bucket C files route to `manual` at install time and are printed
+ * for copy-paste rather than written.
+ */
+export function convertSkillToEcosystem(target, essence) {
+    // Bucket A — SKILL.md standard. Re-emit SKILL.md + carry adjacent files.
+    const aPrefix = BUCKET_A_PREFIX[target];
+    if (aPrefix !== undefined) {
+        const base = `${aPrefix}/${essence.slug}`;
+        const files = [{ filename: `${base}/SKILL.md`, content: buildSkillMd(essence), mode: MD_MODE }];
+        for (const adj of essence.adjacentFiles) {
+            files.push({ filename: `${base}/${adj.relPath}`, content: adj.content, mode: adj.mode });
+        }
+        return { files, droppedAdjacent: [] };
+    }
+    // Bucket B — single-file reshape. Drop (and note) adjacent files.
+    const bSpec = BUCKET_B[target];
+    if (bSpec !== undefined) {
+        return {
+            files: [
+                {
+                    filename: bSpec.filename(essence.slug),
+                    content: buildReshaped(bSpec.frontmatter, essence.primaryBody),
+                    mode: MD_MODE,
+                },
+            ],
+            droppedAdjacent: essence.adjacentFiles.map((f) => f.relPath),
+        };
+    }
+    // Bucket C — paste/manual. Body only; install prints it.
+    const cFilename = BUCKET_C[target];
+    if (cFilename !== undefined) {
+        return {
+            files: [{ filename: cFilename(essence.slug), content: essence.primaryBody, mode: MD_MODE }],
+            // Adjacent files are also dropped for paste targets — note them so the
+            // user knows scripts/templates didn't carry.
+            droppedAdjacent: essence.adjacentFiles.map((f) => f.relPath),
+        };
+    }
+    // Exhaustive: every Ecosystem belongs to exactly one bucket.
+    throw new Error(`convertSkillToEcosystem: unsupported target ecosystem "${target}"`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botdocs/cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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",