@botdocs/cli 0.4.0 → 0.5.0

package/README.md

@@ -290,8 +290,31 @@ ambiguously (e.g. paths containing `_`).
 
 Authors who want to share their existing collection of skills run
 `botdocs ingest <path>` — the CLI walks the directory, detects each
-skill, and uploads them as drafts in your BotDocs account for review
-before publishing.
+skill across all 10 supported ecosystems (claude, claude-code, cursor,
+chatgpt, codex, copilot, windsurf, gemini, antigravity, opencode), and
+uploads them as drafts in your BotDocs account for review before
+publishing.
+
+By default `ingest` expects the canonical BotDocs layout (e.g.
+`claude-code/commands/<slug>.md`, `cursor/rules/<slug>.mdc`). If your
+files live in real on-disk locations instead, point `--from-tool=<ecosystem>`
+at them and every matching file becomes a draft for that ecosystem:
+
+```bash
+# Ingest all your Claude Code commands directly:
+botdocs ingest --from-tool=claude-code ~/.claude/commands/
+
+# Ingest a project's Cursor rules:
+botdocs ingest --from-tool=cursor .cursor/rules/
+
+# Ingest GitHub Copilot instructions (the .instructions.md extension is
+# stripped from the slug automatically):
+botdocs ingest --from-tool=copilot .github/instructions/
+```
+
+The upload always uses the canonical BotDocs filename, so when someone
+else `botdocs install`s the resulting skill it lands in the right
+on-disk location.
 
 ## Development
 

package/dist/commands/ingest.d.ts

@@ -2,6 +2,8 @@ interface IngestOptions {
     bundle?: string;
     dryRun?: boolean;
     json?: boolean;
+    fromTool?: string;
 }
+export declare const SUPPORTED_TOOLS: readonly string[];
 export declare function ingest(rootPath: string, options: IngestOptions): Promise<void>;
 export {};

package/dist/commands/ingest.js

@@ -1,6 +1,94 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { apiFetch } from '../lib/api.js';
+/**
+ * Single source of truth for ecosystem detection. New ecosystems should be
+ * added here — both auto-detect mode and future `--from-tool` mode consult
+ * this table.
+ */
+const DETECTORS = {
+    claude: {
+        pathPrefix: 'claude/',
+        extensions: ['/SKILL.md'],
+        nested: true,
+        slugFor: (abs, root) => {
+            const rel = path.relative(root, abs).split(path.sep).join('/');
+            // Match `<anything>/<slug>/SKILL.md` — slug is the parent dir of SKILL.md.
+            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) => `claude/${slug}/SKILL.md`,
+    },
+    'claude-code': {
+        pathPrefix: 'claude-code/commands/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `claude-code/commands/${slug}.md`,
+    },
+    cursor: {
+        pathPrefix: 'cursor/rules/',
+        extensions: ['.mdc'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.mdc$/, '') || null,
+        canonicalFilename: (slug) => `cursor/rules/${slug}.mdc`,
+    },
+    chatgpt: {
+        pathPrefix: 'chatgpt/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `chatgpt/${slug}.md`,
+    },
+    codex: {
+        pathPrefix: 'codex/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `codex/${slug}.md`,
+    },
+    copilot: {
+        pathPrefix: 'copilot/instructions/',
+        // IMPORTANT: full multi-dot extension — strip BEFORE the .md to get clean slug.
+        extensions: ['.instructions.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.instructions\.md$/, '') || null,
+        canonicalFilename: (slug) => `copilot/instructions/${slug}.instructions.md`,
+    },
+    windsurf: {
+        pathPrefix: 'windsurf/rules/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `windsurf/rules/${slug}.md`,
+    },
+    gemini: {
+        pathPrefix: 'gemini/instructions/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `gemini/instructions/${slug}.md`,
+    },
+    antigravity: {
+        pathPrefix: 'antigravity/skills/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `antigravity/skills/${slug}.md`,
+    },
+    opencode: {
+        pathPrefix: 'opencode/instructions/',
+        extensions: ['.md'],
+        nested: false,
+        slugFor: (abs) => path.basename(abs).replace(/\.md$/, '') || null,
+        canonicalFilename: (slug) => `opencode/instructions/${slug}.md`,
+    },
+};
+export const SUPPORTED_TOOLS = Object.keys(DETECTORS);
 const IGNORED_DIRS = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.turbo']);
 function walkFiles(root) {
     const out = [];
@@ -19,65 +107,111 @@ function walkFiles(root) {
     walk(root);
     return out;
 }
-function detectFile(absPath, root, content) {
+/** Does the filename end with any of the detector's declared extensions? */
+function matchesExtension(absPath, detector) {
+    return detector.extensions.some((ext) => absPath.endsWith(ext));
+}
+/**
+ * Auto-detect mode: iterate every detector and pick the first one whose
+ * path-prefix + extension match. Returns null if nothing matches.
+ */
+function detectAuto(absPath, root, content) {
     const rel = path.relative(root, absPath).split(path.sep).join('/');
-    if (rel.startsWith('claude/') && rel.endsWith('/SKILL.md')) {
-        return { filename: rel, content, ecosystem: 'claude' };
-    }
-    if (rel.startsWith('claude-code/commands/') && rel.endsWith('.md')) {
-        return { filename: rel, content, ecosystem: 'claude-code' };
-    }
-    if (rel.startsWith('cursor/rules/') && rel.endsWith('.mdc')) {
-        return { filename: rel, content, ecosystem: 'cursor' };
-    }
-    if (rel.startsWith('chatgpt/') && rel.endsWith('.md')) {
-        return { filename: rel, content, ecosystem: 'chatgpt' };
+    for (const [ecosystem, detector] of Object.entries(DETECTORS)) {
+        if (!rel.startsWith(detector.pathPrefix))
+            continue;
+        if (!matchesExtension(absPath, detector))
+            continue;
+        const slug = detector.slugFor(absPath, root);
+        if (!slug)
+            continue;
+        return {
+            filename: detector.canonicalFilename(slug),
+            content,
+            ecosystem,
+            slug,
+        };
     }
     return null;
 }
-/** Returns the slug for a detected file by stripping ecosystem path prefix and extension. */
-function slugFor(file) {
-    if (file.ecosystem === 'claude') {
-        const dirs = file.filename.split('/');
-        return dirs[1] ?? 'untitled';
-    }
-    return path.basename(file.filename).replace(/\.(md|mdc)$/, '');
+/**
+ * `--from-tool` mode: every file matching the chosen ecosystem's extension
+ * becomes a draft skill for that ecosystem, regardless of path prefix.
+ * Slug + canonical filename come from the detector, so the upload uses the
+ * canonical BotDocs layout — that's what lets downstream `botdocs install`
+ * route the file back to the right on-disk destination.
+ */
+function detectFromTool(absPath, root, content, ecosystem) {
+    const detector = DETECTORS[ecosystem];
+    if (!detector)
+        return null;
+    if (!matchesExtension(absPath, detector))
+        return null;
+    const slug = detector.slugFor(absPath, root);
+    if (!slug)
+        return null;
+    return {
+        filename: detector.canonicalFilename(slug),
+        content,
+        ecosystem,
+        slug,
+    };
 }
 function titleFromContent(content, slug) {
     const m = content.match(/^#\s+(.+)$/m);
     return m?.[1]?.trim() ?? slug.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
 }
+/** Human-readable list of all canonical path prefixes for the empty-result message. */
+function ecosystemPrefixSummary() {
+    return Object.values(DETECTORS)
+        .map((d) => d.pathPrefix)
+        .join(', ');
+}
 export async function ingest(rootPath, options) {
     const root = path.resolve(rootPath);
     if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
         console.error(`\n  ✗ Not a directory: ${rootPath}\n`);
         process.exit(1);
+        return;
+    }
+    if (options.fromTool && !SUPPORTED_TOOLS.includes(options.fromTool)) {
+        console.error(`\n  ✗ Unknown --from-tool "${options.fromTool}". Supported: ${SUPPORTED_TOOLS.join(', ')}\n`);
+        process.exit(1);
+        return;
     }
     const detected = [];
     for (const filePath of walkFiles(root)) {
         const content = fs.readFileSync(filePath, 'utf-8');
-        const d = detectFile(filePath, root, content);
+        const d = options.fromTool
+            ? detectFromTool(filePath, root, content, options.fromTool)
+            : detectAuto(filePath, root, content);
         if (d)
             detected.push(d);
     }
     if (detected.length === 0) {
-        console.log('\n  No skills detected. Looked for: claude/, claude-code/commands/, cursor/rules/, chatgpt/.\n');
+        if (options.fromTool) {
+            const detector = DETECTORS[options.fromTool];
+            console.log(`\n  ⚠ No files matched ecosystem "${options.fromTool}" (expected ${detector.extensions.join(' or ')} files) in ${root}.\n`);
+        }
+        else {
+            console.log(`\n  No skills detected. Looked for: ${ecosystemPrefixSummary()}.\n`);
+        }
         return;
     }
-    // Group into logical skills by slug
+    // Group into logical skills by slug, merging files that share a slug
+    // across ecosystems (e.g. a `code-review` Claude SKILL.md + a Cursor rule).
     const grouped = new Map();
     for (const f of detected) {
-        const slug = slugFor(f);
-        if (!grouped.has(slug)) {
-            grouped.set(slug, {
-                slug,
-                title: titleFromContent(f.content, slug),
+        if (!grouped.has(f.slug)) {
+            grouped.set(f.slug, {
+                slug: f.slug,
+                title: titleFromContent(f.content, f.slug),
                 description: '',
                 sourceEcosystem: f.ecosystem,
                 files: [],
             });
         }
-        grouped.get(slug).files.push({ filename: f.filename, content: f.content });
+        grouped.get(f.slug).files.push({ filename: f.filename, content: f.content });
     }
     const skills = [...grouped.values()];
     console.log(`\n  ✓ Found ${skills.length} skill(s):`);

package/dist/commands/install.js

@@ -60,6 +60,7 @@ async function downloadAndWrite(file, dest, options, projectDir) {
 async function installSkill(ref, manifest, options, scope) {
     const ctx = buildContext(scope, ref.slug, options);
     const filesInstalled = [];
+    let manualPromptsShown = 0;
     for (const file of manifest.files) {
         const detection = detectDestination(file.filename, ctx);
         if (detection.kind === 'skip')
@@ -70,12 +71,30 @@ async function installSkill(ref, manifest, options, scope) {
                 const content = await fetchRawContent(file.rawUrl);
                 console.log(`\n  Manual paste required for ${file.filename}:\n${content}\n`);
             }
+            // A manual paste prompt counts as "we surfaced this file to the user",
+            // so don't trigger the no-installable-files warning below.
+            manualPromptsShown += 1;
             continue;
         }
         const installed = await downloadAndWrite(file, detection.dest, options, ctx.projectDir);
         if (installed)
             filesInstalled.push(installed);
     }
+    // Surface clear feedback when the manifest produced nothing actionable.
+    // Suppressed under --json so machine-readable output stays clean.
+    if (!options.json) {
+        const refStr = `@${ref.username}/${ref.slug}`;
+        if (manifest.files.length === 0) {
+            console.log(`\n  ⚠ ${refStr} has no files. Nothing to install.\n` +
+                `    This BotDoc may have been published before any content was added.\n`);
+        }
+        else if (filesInstalled.length === 0 && manualPromptsShown === 0) {
+            console.log(`\n  ⚠ ${refStr} has files but none target a supported agent.\n` +
+                `    It may be a spec-only BotDoc without compiled per-agent files\n` +
+                `    (claude/SKILL.md, cursor/rules/*.mdc, etc.).\n` +
+                `    Ask the author to run \`botdocs compile\` and re-publish.\n`);
+        }
+    }
     return {
         ref: `@${ref.username}/${ref.slug}`,
         type: 'SKILL',

package/dist/index.js

@@ -11,7 +11,7 @@ import { install } from './commands/install.js';
 import { list } from './commands/list.js';
 import { uninstall } from './commands/uninstall.js';
 import { sync } from './commands/sync.js';
-import { ingest } from './commands/ingest.js';
+import { ingest, SUPPORTED_TOOLS as INGEST_SUPPORTED_TOOLS } from './commands/ingest.js';
 import { checkUpdates } from './commands/check-updates.js';
 import { compile } from './commands/compile.js';
 import { edit } from './commands/edit.js';
@@ -141,6 +141,7 @@ program
     .description('Walk a directory of existing skill files and create drafts in your BotDocs account for review')
     .option('--bundle <name>', 'Group all detected skills into a single bundle draft')
     .option('--dry-run', 'Show what would be detected without uploading')
+    .option('--from-tool <ecosystem>', `Treat every file in the path as belonging to a single ecosystem (one of: ${INGEST_SUPPORTED_TOOLS.join(', ')}). Useful when ingesting directly from ~/.claude/commands/, .cursor/rules/, etc.`)
     .action(async (sourcePath, opts) => {
     await ingest(sourcePath, { ...opts, json: program.opts().json });
 });

package/package.json

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

package/templates/agents.md

@@ -129,7 +129,7 @@ the user and recommend they set one.
 | `backups list / restore / diff / clear` | Browse and manage backup runs. |
 | `compile <path>` | Generate per-ecosystem drafts from a canonical source (BYOK). |
 | `edit <ref>` | LLM-assisted revision of a published skill ecosystem file (BYOK). |
-| `ingest <path>` | Walk a directory, detect existing skills, upload as drafts. |
+| `ingest <path>` | Walk a directory, detect existing skills across all 10 ecosystems, upload as drafts. Use `--from-tool=<ecosystem>` to ingest from real on-disk locations like `~/.claude/commands/` or `.cursor/rules/`. |
 | `team list` | List teams you belong to. |
 | `team show <slug>` | Members + pinned skills for a team. |
 | `team push <slug> <ref>` | Pin a skill to a team (WRITE+). |