@agent-native/skills 0.2.11 → 0.2.13

package/dist/index.js

@@ -15,7 +15,8 @@ Usage:
 
 Options:
   --skill <name>              Install only this skill (repeatable)
-  --client, -a <client>       codex, claude-code, or all (default: all; repeatable or comma-separated)
+  --client, -a <client>       codex, claude-code, cowork, pi, cursor, opencode, github-copilot, or all
+                              (default: all; repeatable or comma-separated)
   --scope <user|project>      Install globally or into the current project (default: user)
   -g, --global                Alias for --scope user
   --project                   Alias for --scope project
@@ -32,9 +33,9 @@ Options:
   --dry-run                   Print intended writes without changing files
   --json                      Print the result as JSON
 
-App-backed skills (visual-plan, visual-recap, assets, design-exploration)
-register their hosted MCP server in your agent config by default so the agent
-can actually use them. Use --no-mcp to skip that and copy the files only.
+App-backed skills (visual-plan, visual-recap) register their hosted MCP server
+in your agent config by default so the agent can actually use them. Use
+--no-mcp to skip that and copy the files only.
 For visual-plan/visual-recap, choose --mode local-files for no sharing and all
 local files, or --mode self-hosted --mcp-url <url> for your own Plan app.
 
@@ -43,7 +44,15 @@ Examples:
   npx @agent-native/skills@latest add --skill quick-recap
   npx @agent-native/skills@latest add --skill visual-recap --with-github-action
 `;
-const CLIENTS = ["codex", "claude-code"];
+const CLIENTS = [
+    "codex",
+    "claude-code",
+    "cowork",
+    "pi",
+    "cursor",
+    "opencode",
+    "github-copilot",
+];
 const DEFAULT_SKILLS_SOURCE = "BuilderIO/skills";
 const MANAGED_INSTRUCTIONS_START = "<!-- BEGIN @agent-native/skills -->";
 const MANAGED_INSTRUCTIONS_END = "<!-- END @agent-native/skills -->";
@@ -110,6 +119,8 @@ export function parseSkillsCliArgs(argv) {
             out.dryRun = true;
         else if (arg === "--json")
             out.printJson = true;
+        else if (arg === "--quiet")
+            out.quiet = true;
         else if (arg === "--update-instructions")
             out.updateInstructions = true;
         else if (arg === "--no-update-instructions")
@@ -227,6 +238,11 @@ function shouldLoadPublicCatalog(parsed) {
         return true;
     return parsed.skillNames.some((name) => !resolveAppForSkill(name));
 }
+const HIDDEN_STANDALONE_BUILT_INS = [
+    "assets",
+    "design-exploration",
+    "context-xray",
+];
 export async function runSkillsCli(argv, options = {}) {
     const parsed = parseSkillsCliArgs(argv);
     // `@agent-native/skills` normally uses the exact same core flow as
@@ -255,6 +271,7 @@ export async function runSkillsCli(argv, options = {}) {
                 isInteractive: options.isInteractive,
                 baseDir: parsed.baseDir ?? options.baseDir,
                 catalogMode: "all",
+                hiddenBuiltInSkillTargets: HIDDEN_STANDALONE_BUILT_INS,
                 publicSkillSource: loadedSource?.root ?? parsed.source ?? DEFAULT_SKILLS_SOURCE,
                 publicSkillEntries,
                 promptSkills: options.promptSkills
@@ -268,6 +285,8 @@ export async function runSkillsCli(argv, options = {}) {
                 promptGithubAction: options.promptGithubAction
                     ? async (context) => options.promptGithubAction?.({
                         workflowPath: context.workflowPath,
+                        setupCommand: context.setupCommand,
+                        docsUrl: context.docsUrl,
                     }) ?? null
                     : undefined,
                 promptPlanMode: options.promptPlanMode,
@@ -333,8 +352,8 @@ export async function runSkillsCli(argv, options = {}) {
             withGithubAction: parsed.withGithubAction,
             force: parsed.force,
             connect: parsed.connect,
-            quiet: parsed.printJson,
-            log: parsed.printJson ? undefined : stdoutLog,
+            quiet: parsed.printJson || parsed.quiet,
+            log: parsed.printJson || parsed.quiet ? undefined : stdoutLog,
             isInteractive: options.isInteractive,
             promptSkills: options.promptSkills,
             promptClients: options.promptClients,
@@ -359,6 +378,8 @@ export async function runSkillsCli(argv, options = {}) {
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             return;
         }
+        if (parsed.quiet)
+            return;
         await printInstallResult(result, {
             baseDir: parsed.baseDir ?? options.baseDir ?? process.cwd(),
             dryRun: parsed.dryRun,
@@ -426,11 +447,14 @@ export async function installSkills(options) {
         options.telemetry?.track("skills_cli scope selected", { scope });
         const instructionBlocks = managedInstructionBlocksForSkills(skillNames);
         const shouldUpdateInstructions = await shouldUpdateManagedInstructions(instructionBlocks, options);
-        const shouldWriteGithubAction = selected.some((skill) => skill.name === "visual-recap") &&
-            shouldWritePrVisualRecapWorkflow(options, baseDir);
+        const shouldWriteGithubAction = await shouldWritePrVisualRecapWorkflow(selected.some((skill) => skill.name === "visual-recap"), options, baseDir);
         const mcpApps = options.mcp === false || planMode === "local-files"
             ? []
             : mcpAppsForSkills(skillNames, planMcpOverride);
+        const skillFileClients = clients.filter(supportsSkillFiles);
+        if (skillFileClients.length === 0 && mcpApps.length === 0) {
+            throw new Error("Claude Cowork is MCP-only for Agent Native skills. Choose Codex, Claude Code, Pi, Cursor, OpenCode, or GitHub Copilot for local skill files, or install an app-backed skill with MCP enabled.");
+        }
         const progress = await createInstallProgress(options, 1 +
             (shouldUpdateInstructions ? 1 : 0) +
             (shouldWriteGithubAction ? 1 : 0) +
@@ -441,8 +465,7 @@ export async function installSkills(options) {
         const mcpServers = [];
         try {
             progress?.start("Installing skill files...");
-            for (const client of clients) {
-                const root = installRootForClient(client, scope, baseDir);
+            for (const root of unique(skillFileClients.map((client) => installRootForClient(client, scope, baseDir)))) {
                 for (const skill of selected) {
                     const destination = path.join(root, skill.name);
                     written.push(destination);
@@ -463,7 +486,7 @@ export async function installSkills(options) {
             });
             if (shouldUpdateInstructions) {
                 progress?.message("Updating managed instructions...");
-                instructionFiles = writeManagedInstructions(instructionBlocks, baseDir, clients, scope, options);
+                instructionFiles = writeManagedInstructions(instructionBlocks, baseDir, skillFileClients, scope, options);
                 progress?.advance("Managed instructions updated");
                 if (instructionFiles.length) {
                     options.telemetry?.track("skills_cli instructions updated", {
@@ -480,12 +503,17 @@ export async function installSkills(options) {
                 }
             }
             // Register the hosted MCP server for app-backed skills (visual-plan /
-            // visual-recap → Agent-Native Plan, assets, design-exploration) so the
-            // agent can actually call them — not just read the SKILL.md. On by
-            // default; `--no-mcp` installs the skill files only. One registration per
-            // app, so visual-plan + visual-recap share a single "plan" server.
+            // visual-recap → Agent-Native Plan) so the agent can actually call them,
+            // not just read the SKILL.md. On by default; `--no-mcp` installs the
+            // skill files only. One registration per app, so visual-plan +
+            // visual-recap share a single "plan" server.
             if (mcpApps.length > 0) {
-                const mcpClients = clients.map((client) => client === "claude-code" ? "claude-code" : "codex");
+                const mcpClients = clients
+                    .map(skillClientToMcpClient)
+                    .filter((client) => Boolean(client));
+                if (mcpClients.length === 0) {
+                    throw new Error("MCP setup supports Claude Code, Codex, Cursor, OpenCode, GitHub Copilot / VS Code, or Claude Cowork. Use --mode local-files or --no-mcp for Pi.");
+                }
                 for (const app of mcpApps) {
                     progress?.message(`Registering ${app.displayName} MCP server...`);
                     if (!options.dryRun) {
@@ -574,6 +602,7 @@ function defaultArgs(command) {
         force: false,
         connect: true,
         mcp: true,
+        quiet: false,
     };
 }
 function selectedPlanApp(skillNames) {
@@ -651,14 +680,40 @@ function normalizeClients(value) {
             return CLIENTS;
         if (client === "codex")
             return ["codex"];
+        if (client === "cowork" || client === "claude-cowork") {
+            return ["cowork"];
+        }
+        if (client === "pi")
+            return ["pi"];
+        if (client === "cursor")
+            return ["cursor"];
+        if (client === "opencode" || client === "open-code") {
+            return ["opencode"];
+        }
+        if (client === "github-copilot" ||
+            client === "copilot" ||
+            client === "vscode" ||
+            client === "vs-code") {
+            return ["github-copilot"];
+        }
         if (client === "claude" ||
             client === "claude-code" ||
             client === "claude-code-cli") {
             return ["claude-code"];
         }
-        throw new Error(`Unsupported client "${raw}". Use codex, claude-code, or all.`);
+        throw new Error(`Unsupported client "${raw}". Use codex, claude-code, cowork, pi, cursor, opencode, github-copilot, or all.`);
     });
 }
+function skillClientToMcpClient(client) {
+    if (client === "pi")
+        return null;
+    if (client === "claude-code")
+        return "claude-code";
+    return client;
+}
+function supportsSkillFiles(client) {
+    return client !== "cowork";
+}
 function normalizeSkillName(value) {
     const normalized = value.trim().toLowerCase();
     if (!/^[a-z0-9][a-z0-9._-]*$/.test(normalized)) {
@@ -840,15 +895,24 @@ function isInteractive(options) {
 function installRootForClient(client, scope, baseDir) {
     const home = process.env.HOME || os.homedir();
     if (scope === "project") {
-        return client === "codex"
-            ? path.join(baseDir, ".agents", "skills")
-            : path.join(baseDir, ".claude", "skills");
+        if (client !== "claude-code") {
+            return path.join(baseDir, ".agents", "skills");
+        }
+        return path.join(baseDir, ".claude", "skills");
     }
     if (client === "codex") {
         return process.env.CODEX_HOME
             ? path.join(process.env.CODEX_HOME, "skills")
             : path.join(home, ".codex", "skills");
     }
+    if (client === "pi") {
+        return path.join(home, ".agents", "skills");
+    }
+    if (client === "cursor" ||
+        client === "opencode" ||
+        client === "github-copilot") {
+        return path.join(home, ".agents", "skills");
+    }
     return path.join(home, ".claude", "skills");
 }
 function discoverSkills(root) {
@@ -1055,14 +1119,17 @@ function resolveInstructionFiles(baseDir, explicit, clients, scope) {
     if (explicit && explicit.length > 0) {
         return explicit.map((file) => path.resolve(baseDir, file));
     }
+    const instructionClients = clients.filter(supportsSkillFiles);
+    if (instructionClients.length === 0)
+        return [];
     if (scope === "user") {
         const home = process.env.HOME || os.homedir();
         const files = [];
-        if (clients.includes("codex")) {
+        if (instructionClients.includes("codex")) {
             const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
             files.push(path.join(codexHome, "AGENTS.md"));
         }
-        if (clients.includes("claude-code")) {
+        if (instructionClients.includes("claude-code")) {
             files.push(path.join(home, ".claude", "CLAUDE.md"));
         }
         return unique(files);
@@ -1083,13 +1150,44 @@ function upsertManagedBlock(file, block) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function shouldWritePrVisualRecapWorkflow(options, baseDir) {
+const PR_VISUAL_RECAP_DOCS_URL = "https://www.agent-native.com/docs/pr-visual-recap";
+function prVisualRecapWorkflowPath(baseDir) {
+    return path.join(baseDir, ".github", "workflows", "pr-visual-recap.yml");
+}
+function prVisualRecapSetupCommand() {
+    return "npx @agent-native/core@latest recap setup";
+}
+async function promptForGithubAction(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.confirm({
+        message: "Optional: add automatic PR Visual Recaps? (GitHub Action)\n" +
+            "  Posts a human-friendly recap on every pull request.\n" +
+            `  Learn more: ${context.docsUrl}\n` +
+            `  Writes ${context.workflowPath}; ${context.setupCommand} finishes the GitHub secrets.`,
+        initialValue: false,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Skipped PR Visual Recap workflow.");
+        return null;
+    }
+    return Boolean(result);
+}
+async function shouldWritePrVisualRecapWorkflow(hasVisualRecap, options, baseDir) {
+    if (!hasVisualRecap)
+        return false;
     if (options.withGithubAction)
         return true;
-    if (fs.existsSync(path.join(baseDir, ".github", "workflows", "pr-visual-recap.yml"))) {
+    if (fs.existsSync(prVisualRecapWorkflowPath(baseDir)))
         return false;
-    }
-    return false;
+    if (options.yes || !isInteractive(options))
+        return false;
+    const prompt = options.promptGithubAction ?? promptForGithubAction;
+    const choice = await prompt({
+        workflowPath: path.join(".github", "workflows", "pr-visual-recap.yml"),
+        setupCommand: prVisualRecapSetupCommand(),
+        docsUrl: PR_VISUAL_RECAP_DOCS_URL,
+    });
+    return choice === true;
 }
 const PR_VISUAL_RECAP_REUSABLE_WORKFLOW = `name: PR Visual Recap