emberflow-skills 1.11.0 → 1.13.0

package/README.md

@@ -8,12 +8,21 @@ Publish beautiful docs from your AI coding tools to [Emberflow](https://www.embe
 npx emberflow-skills
 ```
 
-The installer auto-detects your project type (Claude Code or Cursor) and copies all skills to the right directory. You'll be publishing docs in under 10 seconds.
+The installer auto-detects which AI coding tools you use and installs skills in the correct format for each.
+
+| Tool | Install location | How to invoke |
+|------|-----------------|---------------|
+| **Claude Code** | `.claude/skills/` | `/ember-publish [topic]` |
+| **Codex** | `.agents/skills/` | `$ember-publish [topic]` |
+| **Cursor** | `.cursor/rules/*.mdc` | `@ember-publish-explainer` or ask naturally |
+| **Windsurf** | `.windsurf/rules/*.md` | Ask naturally: "publish this to Emberflow" |
+
+If multiple tools are detected, skills are installed for all of them.
 
 ### Options
 
 ```bash
-# Install to current project (default)
+# Install to current project (default — auto-detects tools)
 npx emberflow-skills
 
 # Install globally for Claude Code (available in all projects)
@@ -22,9 +31,13 @@ npx emberflow-skills --global
 
 ### What the installer does
 
-1. Detects if you're in a Claude Code project (`.claude/`) or Cursor project (`.cursor/`)
-2. Copies all Emberflow skills into your project's skills directory
-3. Done — use any `/ember-publish` command in your next conversation
+1. Detects tool configs in your project (`.claude/`, `.agents/`, `.cursor/`, `.windsurf/`)
+2. Installs skills in each tool's native format:
+   - Claude Code & Codex: `SKILL.md` with frontmatter (native skill system)
+   - Cursor: `.mdc` rules with auto-attach descriptions
+   - Windsurf: `.md` rules
+3. Copies reference templates for the explainer skill
+4. Done — use the skills in your next conversation
 
 ## Skills
 
@@ -62,7 +75,7 @@ Publish CSV files as an interactive dataset viewer with virtual scroll (handles
 
 ### `/ember-publish-explainer`
 
-Generate interactive visual explainers — the AI chooses the best visualization type (flowchart, chart, timeline, grid, etc.) for the topic. Slide-based with animated transitions.
+Generate interactive visual explainers — the AI chooses the best visualization type (funnel, heatmap, radar chart, waterfall, timeline, architecture diagram, etc.) for the topic. Slide-based with animated transitions.
 
 ```
 /ember-publish-explainer how our CI/CD pipeline works
@@ -95,12 +108,21 @@ If you prefer not to use npx:
 
 ```bash
 git clone https://github.com/pmccurley87/emberflow-skills.git
+
+# Claude Code
 cp -r emberflow-skills/skills/* .claude/skills/
+
+# Codex — same SKILL.md format
+cp -r emberflow-skills/skills/* .agents/skills/
+
+# Cursor — copy as .mdc rules (or use npx for auto-conversion)
+# Windsurf — copy to .windsurf/rules/
 ```
 
 ## Works with
 
-- **Claude Code** — skills run natively
-- **Cursor** — skills auto-detected from `.cursor/skills/`
-- **Codex CLI** — supports SKILL.md format
+- **Claude Code** — native skill system, invoke with `/ember-publish`
+- **Codex** — native skill system, invoke with `$ember-publish`
+- **Cursor** — auto-attached rules, invoke with `@ember-publish-explainer` or ask naturally
+- **Windsurf** — rules loaded automatically, ask naturally
 - **Any MCP-compatible tool** — Emberflow also provides an MCP server

package/bin/install.js

@@ -18,13 +18,39 @@ const green = (s) => `\x1b[32m${s}\x1b[0m`;
 const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
 const orange = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
 
-const targets = [
-  { dir: '.claude/skills', label: 'Claude Code (project)' },
-  { dir: '.cursor/skills', label: 'Cursor (project)' },
-];
-
-const globalTargets = [
-  { dir: path.join(os.homedir(), '.claude', 'skills'), label: 'Claude Code (global)' },
+// ── Tool definitions ──
+
+const TOOLS = [
+  {
+    type: 'claude',
+    detect: ['.claude'],
+    projectDir: '.claude/skills',
+    globalDir: path.join(os.homedir(), '.claude', 'skills'),
+    label: 'Claude Code',
+    usage: '/ember-publish',
+  },
+  {
+    type: 'cursor',
+    detect: ['.cursor', '.cursorrules'],
+    projectDir: '.cursor/rules',
+    label: 'Cursor',
+    usage: '"publish this to Emberflow"',
+  },
+  {
+    type: 'windsurf',
+    detect: ['.windsurf', '.windsurfrules'],
+    projectDir: '.windsurf/rules',
+    label: 'Windsurf',
+    usage: '"publish this to Emberflow"',
+  },
+  {
+    type: 'codex',
+    detect: ['.agents', 'AGENTS.md'],
+    projectDir: '.agents/skills',
+    globalDir: path.join(os.homedir(), '.agents', 'skills'),
+    label: 'Codex',
+    usage: '$ember-publish',
+  },
 ];
 
 const args = process.argv.slice(2);
@@ -77,7 +103,22 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
-// ── Skill installer ──
+// ── SKILL.md parsing ──
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { meta: {}, body: content };
+  const meta = {};
+  for (const line of match[1].split('\n')) {
+    const idx = line.indexOf(':');
+    if (idx > 0) {
+      meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+    }
+  }
+  return { meta, body: match[2] };
+}
+
+// ── File helpers ──
 
 function copyDirRecursive(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -92,25 +133,138 @@ function copyDirRecursive(src, dest) {
   }
 }
 
-function install(destDir, label) {
+function rewriteTemplatePaths(body, templatesRelPath) {
+  // Rewrite "Read templates/" to use the full relative path from project root
+  return body.replace(
+    /Read templates\//g,
+    `Read ${templatesRelPath}/`
+  );
+}
+
+// ── Installers per tool type ──
+
+function installClaude(name, destDir) {
+  const srcDir = path.join(SKILLS_DIR, name);
+  const skillDir = path.join(destDir, name);
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.copyFileSync(path.join(srcDir, 'SKILL.md'), path.join(skillDir, 'SKILL.md'));
+
+  const templatesDir = path.join(srcDir, 'templates');
+  if (fs.existsSync(templatesDir)) {
+    copyDirRecursive(templatesDir, path.join(skillDir, 'templates'));
+  }
+}
+
+function installCursor(name, destDir, cwd) {
+  const srcDir = path.join(SKILLS_DIR, name);
+  const skillMd = fs.readFileSync(path.join(srcDir, 'SKILL.md'), 'utf8');
+  const { meta, body } = parseFrontmatter(skillMd);
+
+  // Copy templates to .cursor/rules/<name>/templates/
+  const templatesDir = path.join(srcDir, 'templates');
+  const hasTemplates = fs.existsSync(templatesDir);
+  if (hasTemplates) {
+    copyDirRecursive(templatesDir, path.join(destDir, name, 'templates'));
+  }
+
+  // Rewrite template paths relative to project root
+  let content = body;
+  if (hasTemplates) {
+    const relPath = path.relative(cwd, path.join(destDir, name, 'templates'));
+    content = rewriteTemplatePaths(content, relPath);
+  }
+
+  // Write .mdc file with Cursor frontmatter
+  const description = meta.description || name;
+  const hint = meta['argument-hint'] ? ` — ${meta['argument-hint']}` : '';
+  const mdc = `---
+description: ${description}${hint}
+globs:
+alwaysApply: false
+---
+
+${content}`;
+
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.writeFileSync(path.join(destDir, `${name}.mdc`), mdc);
+}
+
+function installWindsurf(name, destDir, cwd) {
+  const srcDir = path.join(SKILLS_DIR, name);
+  const skillMd = fs.readFileSync(path.join(srcDir, 'SKILL.md'), 'utf8');
+  const { body } = parseFrontmatter(skillMd);
+
+  // Copy templates
+  const templatesDir = path.join(srcDir, 'templates');
+  const hasTemplates = fs.existsSync(templatesDir);
+  if (hasTemplates) {
+    copyDirRecursive(templatesDir, path.join(destDir, name, 'templates'));
+  }
+
+  // Rewrite template paths
+  let content = body;
+  if (hasTemplates) {
+    const relPath = path.relative(cwd, path.join(destDir, name, 'templates'));
+    content = rewriteTemplatePaths(content, relPath);
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+  fs.writeFileSync(path.join(destDir, `${name}.md`), content);
+}
+
+function installCodex(name, destDir, cwd) {
+  // Codex uses the same SKILL.md format as Claude Code, discovered from .agents/skills/<name>/
+  const srcDir = path.join(SKILLS_DIR, name);
+  const skillDir = path.join(destDir, name);
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.copyFileSync(path.join(srcDir, 'SKILL.md'), path.join(skillDir, 'SKILL.md'));
+
+  // Copy templates
+  const templatesDir = path.join(srcDir, 'templates');
+  if (fs.existsSync(templatesDir)) {
+    copyDirRecursive(templatesDir, path.join(skillDir, 'templates'));
+  }
+}
+
+// ── Main install function ──
+
+function install(destDir, tool, cwd) {
   for (const name of SKILL_NAMES) {
-    const srcDir = path.join(SKILLS_DIR, name);
-    const skillDir = path.join(destDir, name);
-    const destFile = path.join(skillDir, 'SKILL.md');
-    fs.mkdirSync(skillDir, { recursive: true });
-    fs.copyFileSync(path.join(srcDir, 'SKILL.md'), destFile);
-
-    // Copy templates directory if it exists
-    const templatesDir = path.join(srcDir, 'templates');
-    if (fs.existsSync(templatesDir)) {
-      copyDirRecursive(templatesDir, path.join(skillDir, 'templates'));
+    switch (tool.type) {
+      case 'claude':
+        installClaude(name, destDir);
+        break;
+      case 'cursor':
+        installCursor(name, destDir, cwd);
+        break;
+      case 'windsurf':
+        installWindsurf(name, destDir, cwd);
+        break;
+      case 'codex':
+        installCodex(name, destDir, cwd);
+        break;
     }
-
-    console.log(`  ${green('✓')} Installed ${name} to ${path.relative(process.cwd(), skillDir) || skillDir} ${dim(`(${label})`)}`);
+    const relDest = path.relative(cwd, destDir) || destDir;
+    console.log(`  ${green('✓')} ${name} → ${dim(relDest)} ${dim(`(${tool.label})`)}`);
   }
   return true;
 }
 
+// ── Detection ──
+
+function detectTools(cwd) {
+  const detected = [];
+  for (const tool of TOOLS) {
+    for (const marker of tool.detect) {
+      if (fs.existsSync(path.join(cwd, marker))) {
+        detected.push(tool);
+        break;
+      }
+    }
+  }
+  return detected;
+}
+
 // ── Auth flow ──
 
 function hasValidToken() {
@@ -128,7 +282,6 @@ async function authenticate() {
   console.log(`  ${dim('Your published docs will be attributed to your account.')}`);
   console.log();
 
-  // Request device code
   let resp;
   try {
     resp = await request('POST', `${EMBERFLOW_URL}/api/device-code`);
@@ -151,7 +304,6 @@ async function authenticate() {
   console.log(`  Your code: ${bold(code)}`);
   console.log();
 
-  // Try to open the URL automatically
   try {
     const { exec } = require('child_process');
     if (process.platform === 'win32') {
@@ -165,8 +317,7 @@ async function authenticate() {
 
   process.stdout.write(`  ${dim('Waiting for approval...')}`);
 
-  // Poll for approval
-  const maxAttempts = 60; // 3 minutes at 3s intervals
+  const maxAttempts = 60;
   for (let i = 0; i < maxAttempts; i++) {
     await sleep(3000);
 
@@ -174,7 +325,6 @@ async function authenticate() {
       const status = await request('GET', `${EMBERFLOW_URL}/api/device-code/${code}`);
 
       if (status.data.status === 'approved' && status.data.session_token) {
-        // Strip cookie name prefix if present (e.g. "__Secure-better-auth.session_token=VALUE" -> "VALUE")
         const raw = status.data.session_token.replace(/^(?:__Secure-)?better-auth\.session_token=/, '');
         fs.mkdirSync(path.dirname(TOKEN_PATH), { recursive: true });
         fs.writeFileSync(TOKEN_PATH, JSON.stringify({ token: raw }, null, 2));
@@ -194,7 +344,6 @@ async function authenticate() {
       // Network error, keep polling
     }
 
-    // Spinner
     const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
     process.stdout.clearLine(0);
     process.stdout.cursorTo(0);
@@ -217,38 +366,54 @@ async function main() {
   console.log();
 
   if (!authOnly) {
+    const cwd = process.cwd();
     let installed = 0;
 
     if (isGlobal) {
-      for (const t of globalTargets) {
-        install(t.dir, t.label);
-        installed++;
-      }
-    } else {
-      const cwd = process.cwd();
-      const detected = [];
-
-      for (const t of targets) {
-        const parent = path.dirname(path.join(cwd, t.dir));
-        if (fs.existsSync(path.join(cwd, t.dir)) || fs.existsSync(parent)) {
-          detected.push(t);
+      // Global install — Claude Code + Codex (both support global skills)
+      for (const tool of TOOLS) {
+        if (tool.globalDir) {
+          install(tool.globalDir, tool, cwd);
+          installed++;
         }
       }
+    } else {
+      const detected = detectTools(cwd);
 
       if (detected.length === 0) {
-        detected.push(targets[0]);
+        // Default to Claude Code
+        detected.push(TOOLS[0]);
+        console.log(`  ${dim('No tool config detected — defaulting to Claude Code')}`);
+        console.log();
+      } else {
+        console.log(`  ${dim(`Detected: ${detected.map(t => t.label).join(', ')}`)}`);
+        console.log();
       }
 
-      for (const t of detected) {
-        install(path.join(cwd, t.dir), t.label);
+      for (const tool of detected) {
+        const destDir = path.join(cwd, tool.projectDir);
+        install(destDir, tool, cwd);
         installed++;
+        console.log();
       }
     }
 
     if (installed > 0) {
-      console.log();
-      console.log(`  Use: ${cyan('/ember-publish')} ${dim('[topic]')}  — auto-picks format (doc, JSON, Space, or explainer)`);
-      console.log(`       ${cyan('/ember-publish-doc')} ${dim('[topic]')}  ${cyan('/ember-publish-json')} ${dim('[data]')}  ${cyan('/ember-publish-space')} ${dim('[directory]')}  ${cyan('/ember-publish-explainer')} ${dim('[topic]')}`);
+      const tools = isGlobal ? TOOLS.filter(t => t.globalDir) : (detectTools(cwd).length > 0 ? detectTools(cwd) : [TOOLS[0]]);
+
+      for (const tool of tools) {
+        if (tool.type === 'claude') {
+          console.log(`  ${bold('Claude Code:')} ${cyan('/ember-publish')} ${dim('[topic]')}  — auto-picks format`);
+          console.log(`       ${cyan('/ember-publish-doc')}  ${cyan('/ember-publish-json')}  ${cyan('/ember-publish-explainer')}  ${cyan('/ember-publish-space')}`);
+        } else if (tool.type === 'codex') {
+          console.log(`  ${bold('Codex:')} ${cyan('$ember-publish')} ${dim('[topic]')}  — invoke skills with $ prefix`);
+          console.log(`       ${cyan('$ember-publish-doc')}  ${cyan('$ember-publish-json')}  ${cyan('$ember-publish-explainer')}  ${cyan('$ember-publish-space')}`);
+        } else if (tool.type === 'cursor') {
+          console.log(`  ${bold('Cursor:')} Type ${cyan('@ember-publish-explainer')} or ask ${cyan('"publish this to Emberflow"')}`);
+        } else if (tool.type === 'windsurf') {
+          console.log(`  ${bold('Windsurf:')} Ask ${cyan('"publish this to Emberflow"')} or ${cyan('"create an Emberflow explainer"')}`);
+        }
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emberflow-skills",
-  "version": "1.11.0",
+  "version": "1.13.0",
   "description": "Install Emberflow skills for AI coding tools",
   "bin": {
     "emberflow-skills": "./bin/install.js"