@agent-native/core 0.48.4 → 0.49.0

package/dist/cli/skills.js

@@ -8,48 +8,50 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { createCliTelemetry } from "./telemetry.js";
 import { buildAppSkillPack, ensureAppSkill, loadAppSkillManifest, normalizeAppSkillManifest, } from "./app-skill.js";
 import { readConnectClientPreferences, resolveClients, runConnect, writeConnectClientPreferences, } from "./connect.js";
 import { CONTEXT_XRAY_SKILL_MD, installLocalContextXray, } from "./context-xray-local.js";
 import { CLIENTS } from "./mcp-config-writers.js";
 import { PR_VISUAL_RECAP_SETUP, writePrVisualRecapWorkflow } from "./recap.js";
-const HELP = `agent-native skills
+const HELP = `npx @agent-native/core@latest skills
 
 Usage:
-  agent-native skills list
-  agent-native skills status [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--json]
-  agent-native skills update [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--dry-run] [--json]
-  agent-native skills add assets|design-exploration|visual-plan|visual-recap|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
-  agent-native skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
+  npx @agent-native/core@latest skills list
+  npx @agent-native/core@latest skills status [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--json]
+  npx @agent-native/core@latest skills update [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|all] [--scope user|project] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add assets|design-exploration|visual-plan|visual-recap|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
 
 Examples:
-  agent-native skills add assets
-  agent-native skills add design-exploration
-  agent-native skills add visual-plan
-  agent-native skills add visual-recap
-  agent-native skills add visual-recap --with-github-action
-  agent-native skills status visual-plan
-  agent-native skills update visual-plan
-  agent-native skills add visual-plan --no-connect
-  agent-native skills add context-xray --client all
-  agent-native skills add assets --client claude-code
-  agent-native skills add assets --mcp-url https://my-app.ngrok-free.dev
-  agent-native skills add ./dist/assets-skill --client codex
-  agent-native skills add BuilderIO/skills --client codex --scope project
-  agent-native skills add BuilderIO/skills --with-github-action
+  npx @agent-native/core@latest skills add assets
+  npx @agent-native/core@latest skills add design-exploration
+  npx @agent-native/core@latest skills add visual-plan
+  npx @agent-native/core@latest skills add visual-recap
+  npx @agent-native/core@latest skills add visual-recap --with-github-action
+  npx @agent-native/core@latest skills status visual-plan
+  npx @agent-native/core@latest skills update visual-plan
+  npx @agent-native/core@latest skills add visual-plan --no-connect
+  npx @agent-native/core@latest skills add context-xray --client all
+  npx @agent-native/core@latest skills add assets --client claude-code
+  npx @agent-native/core@latest skills add assets --mcp-url https://my-app.ngrok-free.dev
+  npx @agent-native/core@latest skills add ./dist/assets-skill --client codex
+  npx @agent-native/core@latest skills add BuilderIO/skills --client codex --scope project
+  npx @agent-native/core@latest skills add BuilderIO/skills --with-github-action
 
 The add command installs the SKILL.md instructions, registers the app-backed
 MCP connector, and then authenticates it in one step so you do not hit an OAuth
-wall on the first tool call. Authentication reuses "agent-native connect":
+wall on the first tool call. Authentication reuses "npx @agent-native/core@latest connect":
 OAuth-capable clients (Claude Code) get a URL-only entry and a /mcp authenticate
 prompt, while Codex / Cowork run the browser device-code flow. In a
 non-interactive shell or CI the auth step is skipped and the exact
-"agent-native connect <url>" command is printed instead.
+"npx @agent-native/core@latest connect <url>" command is printed instead.
 
 Running "npx @agent-native/skills add ..." directly installs instructions only;
 use this Agent Native CLI path when you want MCP setup and auth too. Pass --no-connect to
 register the connector without authenticating (leave auth to the host or run
-"agent-native connect" later). Pass --mcp-url to register that connector against
+"npx @agent-native/core@latest connect" later). Pass --mcp-url to register that connector against
 a custom origin (an ngrok tunnel, a local dev server, or a self-hosted
 deployment) instead of the built-in hosted default — a bare origin gets the
 standard /_agent-native/mcp path appended. Use app-skill pack for marketplace
@@ -57,7 +59,7 @@ bundles and custom adapter output.
 
 When installing visual-recap interactively, the CLI offers to add the optional PR
 Visual Recap GitHub Action. Pass --with-github-action to write it directly, then
-run "agent-native recap setup" / "agent-native recap doctor" to configure and
+run "npx @agent-native/core@latest recap setup" / "npx @agent-native/core@latest recap doctor" to configure and
 verify GitHub Actions.
 
 The status/update commands inspect copied Agent Native skill folders and refresh
@@ -121,7 +123,7 @@ of using a generic image generator.
 
 - Hosted default: connect \`https://assets.agent-native.com/_agent-native/mcp\`.
   Do not put shared secrets in skill files.
-- For CLI/code-editor clients, keep any \`agent-native connect\` command
+- For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
   running until browser authorization finishes. Stopping it early can leave the
   browser approved but the local MCP config unwritten. Restart or reload the
   agent client after installing or connecting if Assets tools do not appear in
@@ -131,9 +133,12 @@ of using a generic image generator.
 - Do not call image/video providers directly from another app. Assets owns
   generation, picker UI, search/list/export, and asset context.
 - If an Assets tool call returns \`Session terminated\`, \`needs auth\`, or
-  another connector/session error, do not keep retrying the tool. Tell the user
-  to reconnect or authenticate the Assets MCP connector, then continue after it
-  is available.
+  another connector/session error, do not keep retrying the tool. Stop and give
+  the user the reconnect step: in Claude Code run \`/mcp\` and choose
+  Authenticate/Reconnect for the Assets connector; from any terminal run
+  \`npx @agent-native/core@latest reconnect https://assets.agent-native.com\` — this
+  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix
+  auth. Continue once the connector is available.
 - Do not hand-roll MCP HTTP requests with curl from the agent session. Use the
   host-exposed Assets tools after restart/reload, or use the returned
   browser/deep-link fallback.
@@ -193,7 +198,7 @@ iteration, or a human-in-the-loop choice among design directions.
 
 - Hosted default: connect \`https://design.agent-native.com/_agent-native/mcp\`.
   Do not put shared secrets in skill files.
-- For CLI/code-editor clients, keep any \`agent-native connect\` command
+- For CLI/code-editor clients, keep any \`npx @agent-native/core@latest connect\` command
   running until browser authorization finishes. Stopping it early can leave the
   browser approved but the local MCP config unwritten. Restart or reload the
   agent client after installing or connecting if Design tools do not appear in
@@ -203,9 +208,12 @@ iteration, or a human-in-the-loop choice among design directions.
 - Keep the loop visual: surface the inline MCP App or the returned "Open
   design" link instead of pasting large HTML blobs into chat.
 - If a Design tool call returns \`Session terminated\`, \`needs auth\`, or
-  another connector/session error, do not keep retrying the tool. Tell the user
-  to reconnect or authenticate the Design MCP connector, then continue after it
-  is available.
+  another connector/session error, do not keep retrying the tool. Stop and give
+  the user the reconnect step: in Claude Code run \`/mcp\` and choose
+  Authenticate/Reconnect for the Design connector; from any terminal run
+  \`npx @agent-native/core@latest reconnect https://design.agent-native.com\` — this
+  re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix
+  auth. Continue once the connector is available.
 - Do not hand-roll MCP HTTP requests with curl from the agent session. Use the
   host-exposed Design tools after restart/reload, or use the returned
   browser/deep-link fallback.
@@ -251,10 +259,13 @@ your repo as MDX. This local mode is a separate advanced path, not the default
 hosted flow.
 
 If a Plans tool returns \`needs auth\`, \`Unauthorized\`, or \`Session terminated\`,
-do not keep retrying the tool. Authenticate the connector with
-\`npx @agent-native/core@latest connect https://plan.agent-native.com\` (OAuth-capable hosts can
-instead re-run /mcp and choose Authenticate), then continue once the connector
-is available.
+do not keep retrying the tool. Stop and give the user the reconnect step: in
+Claude Code run \`/mcp\` and choose Authenticate/Reconnect for the plan
+connector; from any terminal run
+\`npx @agent-native/core@latest reconnect https://plan.agent-native.com\` — this
+re-authenticates WITHOUT reinstalling and finds the entry by URL regardless of
+connector name. Never reinstall from scratch just to fix auth. Continue once
+the connector is available.
 
 Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
 not put shared secrets in skill files.`;
@@ -916,11 +927,12 @@ plan over as inline chat content — no Markdown prose, ASCII sketch, table, or
 fenced wireframe. If the connector's tools are missing, do NOT fall back to
 inline output: the usual cause is a connector that did not finish connecting
 this session (it registers zero tools), not auth. Stop and give the user the
-exact restore step — reconnect via \`/mcp\` (or restart the session); only if
-genuinely unauthenticated, run
-\`npx @agent-native/core@latest connect https://plan.agent-native.com\`. Publish once the tool is
-reachable. Local-files privacy mode (after Tool Guidance) is the only
-exception.
+exact restore step — in Claude Code run \`/mcp\` and choose
+Authenticate/Reconnect (or restart the session); if genuinely unauthenticated,
+run \`npx @agent-native/core@latest reconnect https://plan.agent-native.com\` — this
+re-authenticates WITHOUT reinstalling. Never reinstall from scratch just to fix
+auth. Publish once the tool is reachable. Local-files privacy mode (after Tool
+Guidance) is the only exception.
 
 ## Core Workflow
 
@@ -1224,10 +1236,13 @@ because it is named \`agent-native-plans\` instead of \`plan\`. The usual cause
 connector that did not finish connecting this session (it registers zero tools),
 NOT necessarily an auth problem — so do not assume the user must authenticate.
 Stop and tell the user how to restore it: reconnect the Plan MCP connector (in
-Claude Code, run \`/mcp\` and reconnect, or restart the session); only if it is
-genuinely unauthenticated, run \`npx @agent-native/core@latest connect <plan-app-url>\` or
-re-authenticate via \`/mcp\`. Then publish once the tool is reachable. Falling
-back to inline content is a defect, not a degraded mode.
+Claude Code, run \`/mcp\` and choose Authenticate/Reconnect, or restart the
+session); if it is genuinely unauthenticated, run
+\`npx @agent-native/core@latest reconnect https://plan.agent-native.com\` — this
+re-authenticates WITHOUT reinstalling and finds the entry by URL regardless of
+connector name. Never reinstall from scratch just to fix auth. Then publish once
+the tool is reachable. Falling back to inline content is a defect, not a
+degraded mode.
 
 ## When To Use
 
@@ -2025,7 +2040,7 @@ function writeSkillFolder(dir, bundle, installedAt = new Date().toISOString()) {
         contentHash: bundle.contentHash,
         mcpUrl: bundle.mcpUrl,
         installedAt,
-        updateCommand: `agent-native skills update ${bundle.skillName}`,
+        updateCommand: `npx @agent-native/core@latest skills update ${bundle.skillName}`,
     };
     fs.writeFileSync(path.join(dir, AGENT_NATIVE_SKILL_METADATA_FILE), `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
 }
@@ -2152,7 +2167,7 @@ function targetIdsForStatus(parsed) {
     }
     const known = normalizeKnownSkillTarget(parsed.target);
     if (!known) {
-        throw new Error(`Unknown built-in skill: ${parsed.target}. Run "agent-native skills list".`);
+        throw new Error(`Unknown built-in skill: ${parsed.target}. Run "npx @agent-native/core@latest skills list".`);
     }
     if (isLocalOnlyBuiltInSkill(BUILT_IN_APP_SKILLS[known])) {
         throw new Error(`${BUILT_IN_APP_SKILLS[known].manifest.displayName} is installed as a local command and cannot be refreshed with skills update yet.`);
@@ -2290,8 +2305,11 @@ function prVisualRecapSetupCommand() {
 async function promptForGithubAction(context) {
     const clack = await import("@clack/prompts");
     const result = await clack.confirm({
-        message: "Optional: add automatic PR Visual Recaps?\n" +
-            `  This writes ${context.workflowPath}; ${context.setupCommand} can finish GitHub secrets.`,
+        message: "Optional: add automatic PR Visual Recaps? (GitHub Action)\n" +
+            "  Posts a human-friendly recap on every pull request — a high-altitude\n" +
+            "  overview of what the PR does, with annotated code, diagrams, and\n" +
+            "  before/after notes instead of a raw diff.\n" +
+            `  Writes ${context.workflowPath}; ${context.setupCommand} finishes the GitHub secrets.`,
         initialValue: false,
     });
     if (clack.isCancel(result)) {
@@ -2392,9 +2410,16 @@ async function resolveSkillTargets(parsed, options) {
         return [parsed.target ?? "assets"];
     }
     const prompt = options.promptSkills ?? promptForSkills;
+    const promptOptions = skillPromptOptions();
+    // The interactive multiselect skill picker is about to be shown (no --skill /
+    // target passed and we are interactive) — record the funnel "prompted" step.
+    options.telemetry?.track("skills_cli skills prompted", {
+        availableCount: promptOptions.length,
+        available: promptOptions.map((option) => option.value).join(","),
+    });
     const selected = await prompt({
         initialTargets: ["visual-plan", "visual-recap"],
-        options: skillPromptOptions(),
+        options: promptOptions,
     });
     if (!selected || selected.length === 0)
         return null;
@@ -2610,6 +2635,7 @@ function preserveMcpUrlAppPathOverride(target, input) {
 function dryRunInstallCommand(parsed, target) {
     const clients = parsed.clients ?? resolveClients(parsed.client);
     const args = [
+        "@agent-native/core@latest",
         "skills",
         "add",
         target,
@@ -2634,7 +2660,7 @@ function dryRunInstallCommand(parsed, target) {
         args.push("--no-update-instructions");
     if (parsed.yes || isKnownSkill(target))
         args.push("--yes");
-    return commandString("agent-native", args);
+    return commandString("npx", args);
 }
 async function runCommand(cmd, args, options = {}) {
     return new Promise((resolve, reject) => {
@@ -2784,6 +2810,12 @@ async function addPlainSkillRepo(parsed, options) {
         if (code !== 0)
             throw new Error(`npx @agent-native/skills add exited with ${code}.`);
     }
+    options.telemetry?.track("skills_cli install completed", {
+        skills: target,
+        clients: clients.join(","),
+        scope: parsed.scope,
+        dryRun: Boolean(parsed.dryRun),
+    });
     return {
         id: target,
         displayName: target,
@@ -2813,6 +2845,7 @@ function canRunInteractiveConnect(options) {
 /** Build the `npx @agent-native/core@latest connect <url> --client … --scope …` command. */
 function connectCommandFor(hostedUrl, clients, scope) {
     const args = [
+        "@agent-native/core@latest",
         "connect",
         hostedUrl,
         "--client",
@@ -2820,7 +2853,7 @@ function connectCommandFor(hostedUrl, clients, scope) {
         "--scope",
         scope,
     ];
-    return commandString("agent-native", args);
+    return commandString("npx", args);
 }
 /**
  * Authenticate the freshly-registered hosted MCP connector so the user does not
@@ -2845,6 +2878,7 @@ async function connectAfterEnsure(installTarget, clients, parsed, options) {
         return { connected: false, connectCommand };
     }
     options.log?.(`Authenticating ${installTarget.displayName}…`);
+    options.telemetry?.track("skills_cli connect started");
     try {
         await (options.runConnect ?? runConnect)([
             hostedUrl,
@@ -2853,10 +2887,14 @@ async function connectAfterEnsure(installTarget, clients, parsed, options) {
             "--scope",
             parsed.scope,
         ]);
+        options.telemetry?.track("skills_cli connect completed");
         return { connected: true, connectCommand: "" };
     }
     catch (err) {
         // Non-fatal: the MCP connector is registered. Surface the manual command.
+        options.telemetry?.track("skills_cli connect failed", {
+            error: err?.message ?? String(err),
+        });
         options.log?.(`Could not finish authentication automatically (${err?.message ?? err}). ` +
             `Run it later with: ${connectCommand}`);
         return { connected: false, connectCommand };
@@ -2877,7 +2915,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         return addPlainSkillRepo({ ...parsed, target }, options);
     }
     if (!knownTarget && !fs.existsSync(path.resolve(target))) {
-        throw new Error(`Unknown skill or manifest path: ${target}. Run "agent-native skills list".`);
+        throw new Error(`Unknown skill or manifest path: ${target}. Run "npx @agent-native/core@latest skills list".`);
     }
     const knownBuiltIn = knownTarget ? BUILT_IN_APP_SKILLS[knownTarget] : null;
     if (isLocalOnlyBuiltInSkill(knownBuiltIn)) {
@@ -2893,6 +2931,12 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             const githubActionPath = parsed.withGithubAction && knownTarget === "visual-plans"
                 ? prVisualRecapWorkflowDisplayPath()
                 : undefined;
+            options.telemetry?.track("skills_cli install completed", {
+                skills: knownBuiltIn.skillName,
+                clients: clients.join(","),
+                scope: parsed.scope,
+                dryRun: true,
+            });
             return {
                 id: knownBuiltIn.manifest.id,
                 displayName: knownBuiltIn.manifest.displayName,
@@ -2911,6 +2955,12 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             clients,
             scope: parsed.scope,
         });
+        options.telemetry?.track("skills_cli install completed", {
+            skills: knownBuiltIn.skillName,
+            clients: clients.join(","),
+            scope: parsed.scope,
+            dryRun: false,
+        });
         return {
             id: knownBuiltIn.manifest.id,
             displayName: knownBuiltIn.manifest.displayName,
@@ -2941,6 +2991,12 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             const githubActionSuggestedCommand = installsRecap && !parsed.withGithubAction
                 ? prVisualRecapInstallCommand()
                 : undefined;
+            options.telemetry?.track("skills_cli install completed", {
+                skills: installTarget.skillNames.join(","),
+                clients: clients.join(","),
+                scope: parsed.scope,
+                dryRun: true,
+            });
             return {
                 id: installTarget.id,
                 displayName: installTarget.displayName,
@@ -3013,6 +3069,14 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 }
             }
         }
+        // Skill instructions are now on disk (built-in folders copied or external
+        // pack materialized) — record the install before MCP registration/connect.
+        options.telemetry?.track("skills_cli install completed", {
+            skills: installTarget.skillNames.join(","),
+            clients: clients.join(","),
+            scope: parsed.scope,
+            dryRun: Boolean(parsed.dryRun),
+        });
         if (parsed.mcp) {
             commands.push(`npx @agent-native/core@latest app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`);
             if (!parsed.dryRun) {
@@ -3024,6 +3088,9 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     confirm: true,
                     log: options.log,
                 });
+                options.telemetry?.track("skills_cli mcp registered", {
+                    skills: installTarget.skillNames.join(","),
+                });
                 // One-step install + authenticate: after registering a hosted MCP
                 // connector, kick off the existing connect/device-code flow so the user
                 // does not hit an OAuth wall on the first tool call. `--no-connect`
@@ -3047,13 +3114,21 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         if (installsRecap &&
             !withGithubAction &&
             !fs.existsSync(prVisualRecapWorkflowPath(baseDir))) {
-            if (shouldPrompt(parsed, options)) {
+            // Normally the recap decision is made up front in `runSkills` (so it's
+            // resolved here). Only prompt inline when a direct caller invoked
+            // addAgentNativeSkill without going through that up-front step.
+            if (!parsed.githubActionResolved && shouldPrompt(parsed, options)) {
                 const prompt = options.promptGithubAction ?? promptForGithubAction;
-                withGithubAction =
-                    (await prompt({
-                        workflowPath: prVisualRecapWorkflowDisplayPath(),
-                        setupCommand: prVisualRecapSetupCommand(),
-                    })) === true;
+                const choice = await prompt({
+                    workflowPath: prVisualRecapWorkflowDisplayPath(),
+                    setupCommand: prVisualRecapSetupCommand(),
+                });
+                if (choice === null) {
+                    options.telemetry?.track("skills_cli cancelled", {
+                        step: "github-action",
+                    });
+                }
+                withGithubAction = choice === true;
             }
             if (!withGithubAction) {
                 githubActionSuggestedCommand = prVisualRecapInstallCommand();
@@ -3074,6 +3149,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 githubActionExisted =
                     writeResult.status === "written" ? writeResult.existed : false;
                 commands.push(`write ${writeResult.path}`);
+                options.telemetry?.track("skills_cli github action added");
             }
         }
         return {
@@ -3153,7 +3229,7 @@ function runSkillsStatusOrUpdate(parsed, options, update) {
     }
     if (before.length === 0) {
         const target = parsed.target ? ` for ${parsed.target}` : "";
-        process.stdout.write(`No installed Agent Native skill copies found${target}.\nRun "agent-native skills add ${parsed.target ?? "visual-plan"}" to install one.\n`);
+        process.stdout.write(`No installed Agent Native skill copies found${target}.\nRun "npx @agent-native/core@latest skills add ${parsed.target ?? "visual-plan"}" to install one.\n`);
         return;
     }
     if (update) {
@@ -3171,6 +3247,21 @@ function runSkillsStatusOrUpdate(parsed, options, update) {
     const rows = (update && parsed.dryRun ? before : after).map(formatSkillState);
     process.stdout.write(`${rows.join("\n")}\n`);
 }
+/**
+ * Resolve the CLI version the same way `index.ts` does — read it from the
+ * package.json two levels up from the compiled module (dist/cli/skills.js →
+ * ../../package.json). Best-effort: falls back to "unknown".
+ */
+function readCliVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(fs.readFileSync(path.resolve(here, "../../package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
 export async function runSkills(argv, options = {}) {
     const parsed = parseSkillsArgs(argv);
     const log = parsed.printJson
@@ -3180,124 +3271,231 @@ export async function runSkills(argv, options = {}) {
         process.stdout.write(`${HELP}\n`);
         return;
     }
-    if (parsed.command === "list") {
-        const skills = listSkills();
+    // `@agent-native/skills` now delegates its interactive install to this
+    // function. For plain skill repos we still shell out to
+    // `npx @agent-native/skills add …`; this env guard tells that child process
+    // to run its OWN headless installer instead of bouncing back into core,
+    // which would otherwise be an infinite skills → core → skills loop.
+    process.env.AGENT_NATIVE_SKILLS_DIRECT = "1";
+    // Best-effort install-funnel telemetry. Created once per run and flushed in a
+    // finally so events send on success, error, and cancellation — the CLI is
+    // short-lived, so flushing before exit is essential or the events never send.
+    const startedAt = Date.now();
+    const telemetry = options.telemetry ??
+        createCliTelemetry({
+            cli: "core",
+            cliVersion: readCliVersion(),
+            command: parsed.command,
+            interactive: shouldPrompt(parsed, options),
+        });
+    const optionsWithTelemetry = { ...options, telemetry };
+    try {
+        telemetry.track("skills_cli started");
+        if (parsed.command === "list") {
+            const skills = listSkills();
+            telemetry.track("skills_cli skills listed", {
+                availableCount: skills.length,
+                available: skills.map((skill) => skill.id).join(","),
+            });
+            if (parsed.printJson) {
+                process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`);
+                return;
+            }
+            for (const skill of skills) {
+                const description = skill.description.replace(/[.?!]?$/, ".");
+                const aliases = skill.aliases.length
+                    ? ` Aliases: ${skill.aliases.join(", ")}.`
+                    : "";
+                const target = skill.local ? "local command" : skill.mcpUrl;
+                process.stdout.write(`${skill.id.padEnd(12)} ${description}${aliases} (${target})\n`);
+            }
+            return;
+        }
+        if (parsed.command === "status" || parsed.command === "update") {
+            runSkillsStatusOrUpdate(parsed, options, parsed.command === "update");
+            return;
+        }
+        const targets = await resolveSkillTargets(parsed, optionsWithTelemetry);
+        if (!targets) {
+            telemetry.track("skills_cli cancelled", { step: "skills" });
+            return;
+        }
+        const preselected = Boolean(parsed.target);
+        telemetry.track("skills_cli skills selected", {
+            selected: targets.join(","),
+            selectedCount: targets.length,
+            // Best-effort "took everything offered" signal: compare against the
+            // interactive picker's option count (the plan sub-skills collapse into a
+            // single bundle target, so this is approximate, like the standalone CLI).
+            selectedAll: targets.length === skillPromptOptions().length,
+            preselected,
+        });
+        const clients = await resolveSkillsClients(parsed, optionsWithTelemetry);
+        if (!clients) {
+            telemetry.track("skills_cli cancelled", { step: "clients" });
+            return;
+        }
+        telemetry.track("skills_cli clients selected", {
+            clients: clients.join(","),
+            clientCount: clients.length,
+        });
+        // Ask where to install (project vs user) unless an explicit --scope was
+        // passed or we are running non-interactively.
+        if (!parsed.scopeExplicit && shouldPrompt(parsed, options)) {
+            const promptScope = options.promptScope ?? promptForScope;
+            const scope = await promptScope({ initialScope: "project" });
+            if (!scope) {
+                telemetry.track("skills_cli cancelled", { step: "scope" });
+                return;
+            }
+            parsed.scope = scope;
+        }
+        telemetry.track("skills_cli scope selected", { scope: parsed.scope });
+        // Decide the optional PR Visual Recap GitHub Action UP FRONT — before any
+        // install or MCP registration — so every prompt is answered before we touch
+        // disk. The choice is threaded into each install via `withGithubAction` +
+        // `githubActionResolved` (so addAgentNativeSkill doesn't re-prompt mid-flow).
+        const recapBaseDir = options.baseDir ?? process.cwd();
+        const anyRecapTarget = targets.some((target) => {
+            if (normalizeKnownSkillTarget(target) !== "visual-plans")
+                return false;
+            const only = builtInOnlySkillNames(target);
+            return !only || only.includes("visual-recap");
+        });
+        if (anyRecapTarget &&
+            !parsed.withGithubAction &&
+            !fs.existsSync(prVisualRecapWorkflowPath(recapBaseDir)) &&
+            shouldPrompt(parsed, options)) {
+            const prompt = options.promptGithubAction ?? promptForGithubAction;
+            const choice = await prompt({
+                workflowPath: prVisualRecapWorkflowDisplayPath(),
+                setupCommand: prVisualRecapSetupCommand(),
+            });
+            if (choice === null) {
+                telemetry.track("skills_cli cancelled", { step: "github-action" });
+            }
+            parsed.withGithubAction = choice === true;
+            parsed.githubActionResolved = true;
+        }
+        const results = [];
+        for (const target of targets) {
+            results.push(await addAgentNativeSkill({
+                ...parsed,
+                target,
+                client: clientArgForClients(clients),
+                clients,
+            }, {
+                ...optionsWithTelemetry,
+                log,
+            }));
+        }
+        // The add flow succeeded for every target — record the funnel completion
+        // before printing output (output below cannot fail the install).
+        const completedSkills = [
+            ...new Set(results.flatMap((result) => result.skillNames)),
+        ];
+        const completedClients = [
+            ...new Set(results.flatMap((result) => result.mcpClients)),
+        ];
+        telemetry.track("skills_cli completed", {
+            skills: completedSkills.join(","),
+            clients: completedClients.join(","),
+            scope: parsed.scope,
+            durationMs: Date.now() - startedAt,
+        });
         if (parsed.printJson) {
-            process.stdout.write(`${JSON.stringify(skills, null, 2)}\n`);
+            process.stdout.write(`${JSON.stringify(results.length === 1 ? results[0] : results, null, 2)}\n`);
             return;
         }
-        for (const skill of skills) {
-            const description = skill.description.replace(/[.?!]?$/, ".");
-            const aliases = skill.aliases.length
-                ? ` Aliases: ${skill.aliases.join(", ")}.`
+        if (parsed.dryRun) {
+            process.stdout.write(`${results.flatMap((result) => result.commands).join("\n")}\n`);
+            return;
+        }
+        const installedNames = results
+            .map((result) => result.displayName)
+            .join(", ");
+        const skillsAgents = [
+            ...new Set(results.flatMap((result) => result.skillsAgents)),
+        ];
+        const mcpClients = [
+            ...new Set(results.flatMap((result) => result.mcpClients)),
+        ];
+        const mcpUrls = [
+            ...new Set(results.map((result) => result.mcpUrl).filter(Boolean)),
+        ];
+        const localCommands = [
+            ...new Set(results
+                .filter((result) => result.local)
+                .flatMap((result) => result.commands)),
+        ];
+        const authConnected = results.some((result) => result.connected);
+        const pendingConnectCommands = [
+            ...new Set(results
+                .map((result) => result.connectCommand)
+                .filter((command) => Boolean(command))),
+        ];
+        const authLine = authConnected
+            ? "Authentication: completed."
+            : pendingConnectCommands.length
+                ? `Authentication: pending — run ${pendingConnectCommands.join(" && ")}`
                 : "";
-            const target = skill.local ? "local command" : skill.mcpUrl;
-            process.stdout.write(`${skill.id.padEnd(12)} ${description}${aliases} (${target})\n`);
+        const githubActions = [
+            ...new Set(results
+                .map((result) => result.githubActionPath)
+                .filter((p) => Boolean(p))),
+        ];
+        const githubActionLine = githubActions.length
+            ? `PR Visual Recap workflow: wrote ${githubActions.join(", ")}.\nNext: run ${prVisualRecapSetupCommand()} to configure GitHub secrets/variables, or set them manually:\n  ${PR_VISUAL_RECAP_SETUP.join("\n  ")}`
+            : "";
+        const githubActionSuggestions = [
+            ...new Set(results
+                .map((result) => result.githubActionSuggestedCommand)
+                .filter((command) => Boolean(command))),
+        ];
+        const githubActionSuggestionLine = githubActionSuggestions.length
+            ? `Optional PR Visual Recap workflow: run ${githubActionSuggestions.join(" && ")} to add automatic recap comments on pull requests.`
+            : "";
+        const clack = await import("@clack/prompts");
+        const summary = [
+            skillsAgents.length
+                ? `Skill instructions   ${skillsAgents.join(", ")}`
+                : "Skill instructions   skipped",
+            mcpClients.length
+                ? `MCP config           ${mcpClients.join(", ")}`
+                : "MCP config           not required",
+            mcpUrls.length ? `MCP URL              ${mcpUrls.join(", ")}` : "",
+            authConnected
+                ? "Authentication       completed"
+                : pendingConnectCommands.length
+                    ? `Authentication       pending — run ${pendingConnectCommands.join(" && ")}`
+                    : "",
+            localCommands.length
+                ? `Local command        ${localCommands.join(", ")}`
+                : "",
+        ].filter(Boolean);
+        clack.note(summary.join("\n"), `Installed ${installedNames} skill${results.length === 1 ? "" : "s"}`);
+        // GitHub Action follow-ups — kept as exact, copy-pasteable command lines.
+        for (const line of [githubActionLine, githubActionSuggestionLine].filter(Boolean)) {
+            process.stdout.write(`${line}\n`);
         }
-        return;
-    }
-    if (parsed.command === "status" || parsed.command === "update") {
-        runSkillsStatusOrUpdate(parsed, options, parsed.command === "update");
-        return;
-    }
-    const targets = await resolveSkillTargets(parsed, options);
-    if (!targets)
-        return;
-    const clients = await resolveSkillsClients(parsed, options);
-    if (!clients)
-        return;
-    // Ask where to install (project vs user) unless an explicit --scope was
-    // passed or we are running non-interactively.
-    if (!parsed.scopeExplicit && shouldPrompt(parsed, options)) {
-        const promptScope = options.promptScope ?? promptForScope;
-        const scope = await promptScope({ initialScope: "project" });
-        if (!scope)
-            return;
-        parsed.scope = scope;
-    }
-    const results = [];
-    for (const target of targets) {
-        results.push(await addAgentNativeSkill({
-            ...parsed,
-            target,
-            client: clientArgForClients(clients),
-            clients,
-        }, {
-            ...options,
-            log,
-        }));
+        const slashCommands = completedSkills.map((name) => `/${name}`).join("  ");
+        const clientHint = parsed.clientExplicit
+            ? ""
+            : "\n   Add another client later with --client <client> (e.g. --client claude-code).";
+        clack.outro(`✅ All set! Start using ${slashCommands || "your new skills"} in your agent client.` +
+            `\n   You may need to reload the client for the skill + MCP server to appear.` +
+            clientHint);
     }
-    if (parsed.printJson) {
-        process.stdout.write(`${JSON.stringify(results.length === 1 ? results[0] : results, null, 2)}\n`);
-        return;
+    catch (error) {
+        telemetry.track("skills_cli failed", {
+            command: parsed.command,
+            error: error instanceof Error ? error.message : String(error),
+            durationMs: Date.now() - startedAt,
+        });
+        throw error;
     }
-    if (parsed.dryRun) {
-        process.stdout.write(`${results.flatMap((result) => result.commands).join("\n")}\n`);
-        return;
+    finally {
+        await telemetry.flush();
     }
-    const installedNames = results.map((result) => result.displayName).join(", ");
-    const skillsAgents = [
-        ...new Set(results.flatMap((result) => result.skillsAgents)),
-    ];
-    const mcpClients = [
-        ...new Set(results.flatMap((result) => result.mcpClients)),
-    ];
-    const mcpUrls = [
-        ...new Set(results.map((result) => result.mcpUrl).filter(Boolean)),
-    ];
-    const localCommands = [
-        ...new Set(results
-            .filter((result) => result.local)
-            .flatMap((result) => result.commands)),
-    ];
-    const authConnected = results.some((result) => result.connected);
-    const pendingConnectCommands = [
-        ...new Set(results
-            .map((result) => result.connectCommand)
-            .filter((command) => Boolean(command))),
-    ];
-    const authLine = authConnected
-        ? "Authentication: completed."
-        : pendingConnectCommands.length
-            ? `Authentication: pending — run ${pendingConnectCommands.join(" && ")}`
-            : "";
-    const githubActions = [
-        ...new Set(results
-            .map((result) => result.githubActionPath)
-            .filter((p) => Boolean(p))),
-    ];
-    const githubActionLine = githubActions.length
-        ? `PR Visual Recap workflow: wrote ${githubActions.join(", ")}.\nNext: run ${prVisualRecapSetupCommand()} to configure GitHub secrets/variables, or set them manually:\n  ${PR_VISUAL_RECAP_SETUP.join("\n  ")}`
-        : "";
-    const githubActionSuggestions = [
-        ...new Set(results
-            .map((result) => result.githubActionSuggestedCommand)
-            .filter((command) => Boolean(command))),
-    ];
-    const githubActionSuggestionLine = githubActionSuggestions.length
-        ? `Optional PR Visual Recap workflow: run ${githubActionSuggestions.join(" && ")} to add automatic recap comments on pull requests.`
-        : "";
-    process.stdout.write([
-        `Installed ${installedNames} skill${results.length === 1 ? "" : "s"}.`,
-        skillsAgents.length
-            ? `Skill instructions: ${skillsAgents.join(", ")}.`
-            : "Skill instructions: skipped.",
-        mcpClients.length
-            ? `MCP config: ${mcpClients.join(", ")}.`
-            : "MCP config: not required.",
-        mcpUrls.length
-            ? `MCP URL${mcpUrls.length === 1 ? "" : "s"}: ${mcpUrls.join(", ")}.`
-            : "",
-        authLine,
-        githubActionLine,
-        githubActionSuggestionLine,
-        localCommands.length ? `Local command: ${localCommands.join(", ")}.` : "",
-        "Restart or reload selected agent clients if the skill is not visible yet.",
-        parsed.clientExplicit
-            ? ""
-            : `To add another client later, rerun with --client <client> (for example: --client claude-code).`,
-    ]
-        .filter(Boolean)
-        .join("\n") + "\n");
 }
 //# sourceMappingURL=skills.js.map