@agent-native/core 0.51.10 → 0.51.13

package/dist/cli/skills.js

@@ -45,16 +45,16 @@ Examples:
 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. By default, add targets every supported local
-client this CLI can configure (Claude Code, Claude Code CLI, Codex, and Cowork);
+client this CLI can configure (Claude Code, Codex, and Cowork);
 pass --client to narrow it. 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
 "npx @agent-native/core@latest connect <url> --client all" command is printed instead.
 
-Running "npx @agent-native/skills@latest 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
+Running "npx @agent-native/skills@latest add ..." uses this same shared install
+flow with the broader BuilderIO skills catalog enabled. Pass --no-connect to
+register MCP where possible without authenticating (leave auth to the host or run
 "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
@@ -2246,6 +2246,14 @@ const CLIENT_HINTS = {
     codex: "$CODEX_HOME/config.toml or ~/.codex/config.toml",
     cowork: "~/.cowork/mcp.json",
 };
+const SKILLS_CLIENTS = ["claude-code", "codex", "cowork"];
+const SKILL_INSTRUCTION_CLIENTS = ["claude-code", "codex"];
+const SKILL_INSTRUCTION_CLIENT_HINTS = {
+    "claude-code": ".claude/skills or .claude/commands",
+    "claude-code-cli": ".claude/skills or .claude/commands",
+    codex: ".agents/skills or ~/.codex/skills",
+    cowork: "MCP only",
+};
 function normalizeKnownSkillTarget(value) {
     const key = value?.trim().toLowerCase();
     if (!key)
@@ -2632,19 +2640,51 @@ function normalizeClientIds(values) {
     }
     return out;
 }
-function clientPromptOptions() {
-    return CLIENTS.map((client) => ({
+function normalizeSkillsClientIds(values) {
+    const seen = new Set();
+    const out = [];
+    for (const client of normalizeClientIds(values)) {
+        const normalized = client === "claude-code-cli" ? "claude-code" : client;
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+}
+function resolveSkillsClientArg(client) {
+    return normalizeSkillsClientIds(resolveClients(client));
+}
+function skillsClients(installsMcp) {
+    return installsMcp ? SKILLS_CLIENTS : SKILL_INSTRUCTION_CLIENTS;
+}
+function filterSkillsClients(clients, installsMcp) {
+    if (installsMcp)
+        return clients;
+    return clients.filter((client) => SKILL_INSTRUCTION_CLIENTS.includes(client));
+}
+function clientPromptOptions(installsMcp) {
+    return skillsClients(installsMcp).map((client) => ({
         value: client,
         label: CLIENT_LABELS[client],
-        hint: CLIENT_HINTS[client],
+        hint: installsMcp
+            ? CLIENT_HINTS[client]
+            : SKILL_INSTRUCTION_CLIENT_HINTS[client],
     }));
 }
-// For now the interactive installer offers only the two plan skills, each as
-// an independently selectable entry (uncheck one to install just the other).
-// The other built-in skills stay installable via `agent-native skills add
-// <name>` but are hidden from the default checklist. The values are the real
-// slash-command names so users see exactly what they are installing.
-const PLAN_SKILL_PROMPT_OPTIONS = [
+const DEFAULT_PUBLIC_SKILLS_SOURCE = "BuilderIO/skills";
+const PUBLIC_SKILL_TARGET_PREFIX = "public-skills:";
+const BUILT_IN_SKILL_PROMPT_OPTIONS = [
+    {
+        value: "assets",
+        label: "assets",
+        hint: BUILT_IN_APP_SKILLS.assets.manifest.description,
+    },
+    {
+        value: "design-exploration",
+        label: "design-exploration",
+        hint: BUILT_IN_APP_SKILLS.design.manifest.description,
+    },
     {
         value: "visual-plan",
         label: "visual-plan",
@@ -2655,9 +2695,64 @@ const PLAN_SKILL_PROMPT_OPTIONS = [
         label: "visual-recap",
         hint: "Interactive visual recap that maps PRs/diffs with diagrams, annotated diffs, API/schema summaries, and review notes.",
     },
+    {
+        value: "context-xray",
+        label: "context-xray",
+        hint: BUILT_IN_APP_SKILLS["context-xray"].manifest.description,
+    },
 ];
-function skillPromptOptions() {
-    return PLAN_SKILL_PROMPT_OPTIONS;
+const DEFAULT_SKILL_PROMPT_TARGETS = ["visual-plan", "visual-recap"];
+function publicSkillEntries(options) {
+    if (options.catalogMode !== "all")
+        return [];
+    const seen = new Set();
+    return (options.publicSkillEntries ?? [])
+        .map((entry) => ({
+        name: entry.name.trim().toLowerCase(),
+        description: entry.description,
+    }))
+        .filter((entry) => {
+        if (!entry.name || isKnownSkill(entry.name) || seen.has(entry.name)) {
+            return false;
+        }
+        seen.add(entry.name);
+        return true;
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function publicSkillNames(options) {
+    return new Set(publicSkillEntries(options).map((entry) => entry.name));
+}
+function publicSkillPromptOptions(options) {
+    return publicSkillEntries(options).map((entry) => ({
+        value: entry.name,
+        label: entry.name,
+        hint: entry.description ?? "Public skill from the BuilderIO skills catalog.",
+    }));
+}
+function skillPromptOptions(options = {}) {
+    return [
+        ...BUILT_IN_SKILL_PROMPT_OPTIONS,
+        ...publicSkillPromptOptions(options),
+    ];
+}
+function defaultSkillPromptTargets(options) {
+    return [
+        ...DEFAULT_SKILL_PROMPT_TARGETS,
+        ...publicSkillEntries(options).map((entry) => entry.name),
+    ];
+}
+function publicSkillSelectionTarget(skillNames) {
+    return `${PUBLIC_SKILL_TARGET_PREFIX}${skillNames.join(",")}`;
+}
+function publicSkillSelectionNames(target) {
+    if (!target.startsWith(PUBLIC_SKILL_TARGET_PREFIX))
+        return null;
+    return target
+        .slice(PUBLIC_SKILL_TARGET_PREFIX.length)
+        .split(",")
+        .map((name) => name.trim().toLowerCase())
+        .filter(Boolean);
 }
 function prVisualRecapWorkflowPath(baseDir) {
     return path.join(baseDir, ".github", "workflows", "pr-visual-recap.yml");
@@ -2700,9 +2795,13 @@ function shouldPrompt(parsed, options) {
 }
 async function promptForClients(context) {
     const clack = await import("@clack/prompts");
+    const message = context.installsMcp
+        ? "Install the MCP connector and skills for which local agents?\n" +
+            "  (space toggles, enter confirms; saved for next time)"
+        : "Install skill instructions for which local agents?\n" +
+            "  (space toggles, enter confirms; saved for next time)";
     const result = await clack.multiselect({
-        message: "Install the MCP connector for which local agents?\n" +
-            "  (space toggles, enter confirms; saved for next time)",
+        message,
         options: context.options,
         initialValues: context.initialClients,
         required: true,
@@ -2745,7 +2844,7 @@ async function promptForPlanMode(context) {
             {
                 value: "hosted",
                 label: "Hosted Plans, shareable links",
-                hint: "Stores plans at plan.agent-native.com. Enables sharing, comments, browser editor. Requires one-time browser sign-in.",
+                hint: "100% free and open source. Stores plans at plan.agent-native.com with sharing, comments, and browser editor. Requires one-time browser sign-in.",
             },
             {
                 value: "local-files",
@@ -2787,6 +2886,18 @@ async function promptForPlanMcpUrl() {
     }
     return String(result).trim();
 }
+async function promptForUpdateInstructions() {
+    const clack = await import("@clack/prompts");
+    const result = await clack.confirm({
+        message: "Add managed AGENTS.md / CLAUDE.md instructions for always-on skill behavior?",
+        initialValue: true,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Skipped managed instruction updates.");
+        return null;
+    }
+    return Boolean(result);
+}
 async function promptForSkills(context) {
     const clack = await import("@clack/prompts");
     const result = await clack.multiselect({
@@ -2804,15 +2915,20 @@ async function promptForSkills(context) {
         return [];
     return result.filter((value) => typeof value === "string");
 }
-async function resolveSkillsClients(parsed, options) {
+async function resolveSkillsClients(parsed, options, installsMcp) {
     if (parsed.clientExplicit || !shouldPrompt(parsed, options)) {
-        return resolveClients(parsed.client);
+        const clients = filterSkillsClients(resolveSkillsClientArg(parsed.client), installsMcp);
+        if (clients.length === 0) {
+            throw new Error("Local-file skill instructions only support Codex or Claude Code clients.");
+        }
+        return clients;
     }
-    const initialClients = resolveClients("all");
+    const initialClients = skillsClients(installsMcp);
     const prompt = options.promptClients ?? promptForClients;
-    const selected = normalizeClientIds(await prompt({
+    const selected = normalizeSkillsClientIds(await prompt({
         initialClients,
-        options: clientPromptOptions(),
+        options: clientPromptOptions(installsMcp),
+        installsMcp,
     }));
     if (selected.length === 0)
         return null;
@@ -2848,12 +2964,66 @@ function targetIncludesPlans(target) {
 function targetsIncludePlans(targets) {
     return targets.some(targetIncludesPlans);
 }
+function planSkillNamesSelected(skillNames) {
+    return Boolean(skillNames?.some((name) => normalizeKnownSkillTarget(name) === "visual-plans"));
+}
+function recapSkillNamesSelected(skillNames) {
+    return Boolean(skillNames?.some((name) => {
+        const normalized = name.trim().toLowerCase();
+        return (normalized === "visual-recap" ||
+            normalized === "visual-recaps" ||
+            normalizeKnownSkillTarget(normalized) === "visual-plans");
+    }));
+}
+function resolveSelectedSkillTargets(selected, options) {
+    const publicNames = publicSkillNames(options);
+    const builtInSelections = [];
+    const publicSelections = [];
+    for (const raw of selected) {
+        const skill = raw.trim().toLowerCase();
+        if (!skill)
+            continue;
+        if (isKnownSkill(skill)) {
+            builtInSelections.push(skill);
+            continue;
+        }
+        if (publicNames.has(skill)) {
+            publicSelections.push(skill);
+            continue;
+        }
+        throw new Error(`Unknown skill: ${raw}. Run "npx @agent-native/core@latest skills list".`);
+    }
+    const out = [];
+    const planSubskills = ["visual-plan", "visual-recap"];
+    const selectedPlanSubskills = planSubskills.filter((skill) => builtInSelections.includes(skill));
+    if (selectedPlanSubskills.length === planSubskills.length) {
+        out.push("visual-plans");
+    }
+    else {
+        out.push(...selectedPlanSubskills);
+    }
+    out.push(...builtInSelections.filter((skill) => !planSubskills.includes(skill) && !out.includes(skill)));
+    if (publicSelections.length > 0) {
+        out.push(publicSkillSelectionTarget([...new Set(publicSelections)]));
+    }
+    return out;
+}
 async function resolveSkillTargets(parsed, options) {
+    if (!parsed.target && parsed.plainSkillNames?.length) {
+        return resolveSelectedSkillTargets(parsed.plainSkillNames, options);
+    }
     if (parsed.target || !shouldPrompt(parsed, options)) {
-        return [parsed.target ?? "assets"];
+        const target = parsed.target ?? "assets";
+        if (!parsed.target)
+            return [target];
+        const normalizedTarget = target.trim().toLowerCase();
+        if (publicSkillNames(options).has(normalizedTarget)) {
+            return [publicSkillSelectionTarget([normalizedTarget])];
+        }
+        return [target];
     }
     const prompt = options.promptSkills ?? promptForSkills;
-    const promptOptions = skillPromptOptions();
+    const promptOptions = skillPromptOptions(options);
     // 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", {
@@ -2861,22 +3031,12 @@ async function resolveSkillTargets(parsed, options) {
         available: promptOptions.map((option) => option.value).join(","),
     });
     const selected = await prompt({
-        initialTargets: ["visual-plan", "visual-recap"],
+        initialTargets: defaultSkillPromptTargets(options),
         options: promptOptions,
     });
     if (!selected || selected.length === 0)
         return null;
-    // Both plan skills share one MCP connector, so when both are selected install
-    // them through the bundle target — that registers/authenticates the connector
-    // once instead of twice.
-    const planSubskills = ["visual-plan", "visual-recap"];
-    if (planSubskills.every((skill) => selected.includes(skill))) {
-        return [
-            "visual-plans",
-            ...selected.filter((s) => !planSubskills.includes(s)),
-        ];
-    }
-    return selected;
+    return resolveSelectedSkillTargets(selected, options);
 }
 export function parseSkillsArgs(argv) {
     const first = argv[0];
@@ -2932,6 +3092,14 @@ export function parseSkillsArgs(argv) {
             out.client = value;
             out.clientExplicit = true;
         }
+        else if ((value = eat("--agent")) !== undefined) {
+            out.client = value;
+            out.clientExplicit = true;
+        }
+        else if ((value = eat("-a")) !== undefined) {
+            out.client = value;
+            out.clientExplicit = true;
+        }
         else if ((value = eat("--skill")) !== undefined) {
             out.plainSkillNames = [...(out.plainSkillNames ?? []), value];
         }
@@ -2942,6 +3110,8 @@ export function parseSkillsArgs(argv) {
             out.scope = value;
             out.scopeExplicit = true;
         }
+        else if ((value = eat("--cwd")) !== undefined)
+            out.baseDir = value;
         else if ((value = eat("--mcp-url")) !== undefined)
             out.mcpUrl = value;
         else if ((value = eat("--mode")) !== undefined)
@@ -2958,6 +3128,18 @@ export function parseSkillsArgs(argv) {
             out.dryRun = true;
         else if (arg === "--json")
             out.printJson = true;
+        else if (arg === "-g" || arg === "--global") {
+            out.scope = "user";
+            out.scopeExplicit = true;
+        }
+        else if (arg === "--project") {
+            out.scope = "project";
+            out.scopeExplicit = true;
+        }
+        else if (arg === "--copy") {
+            // Compatibility with @agent-native/skills. Core always copies skill
+            // instructions instead of linking to the source repo.
+        }
         else if (arg === "--mcp-only")
             out.instructions = false;
         else if (arg === "--instructions-only" || arg === "--no-mcp")
@@ -3087,7 +3269,7 @@ function preserveMcpUrlAppPathOverride(target, input) {
     };
 }
 function dryRunInstallCommand(parsed, target) {
-    const clients = parsed.clients ?? resolveClients(parsed.client);
+    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
     const args = [
         "@agent-native/core@latest",
         "skills",
@@ -3219,21 +3401,30 @@ function isGithubSkillRepoTarget(target) {
 function isPlainSkillRepoTarget(target) {
     return isPlainSkillRepoPath(target) || isGithubSkillRepoTarget(target);
 }
-function agentNativeSkillsInstallArgs(parsed, target, clients) {
+function agentNativeSkillsInstallArgs(parsed, target, clients, baseDir) {
     const args = [
         "--yes",
         "@agent-native/skills@latest",
         "add",
+        "--copy",
         target,
         "--client",
         clientArgForClients(clients),
         "--scope",
         parsed.scope,
     ];
+    if (baseDir)
+        args.push("--cwd", baseDir);
     if (parsed.withGithubAction)
         args.push("--with-github-action");
     if (parsed.force)
         args.push("--force");
+    if (parsed.planMode)
+        args.push("--mode", parsed.planMode);
+    if (parsed.mcpUrl)
+        args.push("--mcp-url", parsed.mcpUrl);
+    if (!parsed.mcp)
+        args.push("--no-mcp");
     if (!parsed.connect)
         args.push("--no-connect");
     for (const skill of parsed.plainSkillNames ?? []) {
@@ -3245,6 +3436,8 @@ function agentNativeSkillsInstallArgs(parsed, target, clients) {
         args.push("--no-update-instructions");
     if (parsed.yes)
         args.push("--yes");
+    if (parsed.dryRun)
+        args.push("--dry-run");
     return args;
 }
 async function addPlainSkillRepo(parsed, options) {
@@ -3252,15 +3445,16 @@ async function addPlainSkillRepo(parsed, options) {
     if (!parsed.instructions && parsed.mcp) {
         throw new Error("Plain skill repositories only install skill instructions. Run without --mcp-only.");
     }
-    if (parsed.mcpUrl) {
+    if (parsed.mcpUrl && !planSkillNamesSelected(parsed.plainSkillNames)) {
         throw new Error("--mcp-url only applies to app-backed Agent Native skills.");
     }
-    const clients = parsed.clients ?? resolveClients(parsed.client);
+    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
     const skillsAgents = skillsAgentsForClients(clients);
+    const selectedSkillNames = parsed.plainSkillNames ?? [];
     if (skillsAgents.length === 0) {
         throw new Error("Plain skill repositories can only install instructions for Codex or Claude Code clients.");
     }
-    const args = agentNativeSkillsInstallArgs(parsed, target, clients);
+    const args = agentNativeSkillsInstallArgs(parsed, target, clients, options.baseDir);
     if (!parsed.dryRun) {
         const code = await (options.runCommand ?? runCommand)("npx", args, {
             stdio: parsed.yes ? "silent" : "inherit",
@@ -3269,15 +3463,17 @@ async function addPlainSkillRepo(parsed, options) {
             throw new Error(`npx @agent-native/skills@latest add exited with ${code}.`);
     }
     options.telemetry?.track("skills_cli install completed", {
-        skills: target,
+        skills: selectedSkillNames.length ? selectedSkillNames.join(",") : target,
         clients: clients.join(","),
         scope: parsed.scope,
         dryRun: Boolean(parsed.dryRun),
     });
     return {
         id: target,
-        displayName: target,
-        skillNames: [],
+        displayName: selectedSkillNames.length
+            ? selectedSkillNames.join(", ")
+            : target,
+        skillNames: selectedSkillNames,
         skillsAgents,
         mcpUrl: "",
         mcpClients: [],
@@ -3338,13 +3534,29 @@ async function connectAfterEnsure(installTarget, clients, parsed, options) {
     options.log?.(`Authenticating ${installTarget.displayName}…`);
     options.telemetry?.track("skills_cli connect started");
     try {
-        await (options.runConnect ?? runConnect)([
+        const connectArgs = [
             hostedUrl,
             "--client",
             clientArgForClients(clients),
             "--scope",
             parsed.scope,
-        ]);
+        ];
+        if (options.runConnect) {
+            await options.runConnect(connectArgs);
+        }
+        else {
+            await runConnect(connectArgs, {
+                isInteractive: options.isInteractive,
+                logOut: (message) => {
+                    if (message.trim())
+                        options.log?.(message);
+                },
+                logErr: (message) => {
+                    if (message.trim())
+                        options.log?.(message);
+                },
+            });
+        }
         options.telemetry?.track("skills_cli connect completed");
         return { connected: true, connectCommand: "" };
     }
@@ -3360,6 +3572,14 @@ async function connectAfterEnsure(installTarget, clients, parsed, options) {
 }
 export async function addAgentNativeSkill(parsed, options = {}) {
     const target = parsed.target ?? "assets";
+    const publicSelection = publicSkillSelectionNames(target);
+    if (publicSelection) {
+        return addPlainSkillRepo({
+            ...parsed,
+            target: options.publicSkillSource ?? DEFAULT_PUBLIC_SKILLS_SOURCE,
+            plainSkillNames: publicSelection,
+        }, options);
+    }
     const knownTarget = normalizeKnownSkillTarget(target);
     const planMode = knownTarget === "visual-plans"
         ? (parsed.planMode ?? (parsed.mcpUrl ? "self-hosted" : "hosted"))
@@ -3397,7 +3617,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         if (!parsed.instructions && parsed.mcp) {
             throw new Error("Context X-Ray does not need MCP config yet. Run without --mcp-only.");
         }
-        const clients = parsed.clients ?? resolveClients(parsed.client);
+        const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
         const skillsAgents = skillsAgentsForClients(clients);
         if (parsed.dryRun) {
             const githubActionPath = parsed.withGithubAction && knownTarget === "visual-plans"
@@ -3452,7 +3672,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     if (parsed.mcpUrl) {
         installTarget = withMcpUrlOverride(installTarget, parsed.mcpUrl);
     }
-    const clients = parsed.clients ?? resolveClients(parsed.client);
+    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
     installTarget = preserveMcpUrlAppPathOverride(installTarget, parsed.mcpUrl);
     const skillsAgents = skillsAgentsForClients(clients);
     if (parsed.dryRun) {
@@ -3495,6 +3715,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     let instructionsWritten;
     let connected = false;
     let connectCommand;
+    let registeredMcpClients = shouldRegisterMcp ? clients : [];
     try {
         if (parsed.instructions) {
             if (skillsAgents.length === 0) {
@@ -3557,7 +3778,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         if (shouldRegisterMcp) {
             commands.push(`npx @agent-native/core@latest app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`);
             if (!parsed.dryRun) {
-                await ensureAppSkill(installTarget.loaded, {
+                const ensureResult = await ensureAppSkill(installTarget.loaded, {
                     clients,
                     scope: parsed.scope,
                     baseDir: options.baseDir,
@@ -3565,6 +3786,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     confirm: true,
                     log: options.log,
                 });
+                registeredMcpClients = ensureResult.written.map((written) => written.client);
                 options.telemetry?.track("skills_cli mcp registered", {
                     skills: installTarget.skillNames.join(","),
                 });
@@ -3576,9 +3798,18 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     const result = await connectAfterEnsure(installTarget, clients, parsed, options);
                     connected = result.connected;
                     connectCommand = result.connectCommand || undefined;
+                    if (connected)
+                        registeredMcpClients = clients;
                     if (connectCommand)
                         commands.push(connectCommand);
                 }
+                else {
+                    const pendingClients = clients.filter((client) => !registeredMcpClients.includes(client));
+                    if (pendingClients.length > 0) {
+                        connectCommand = connectCommandFor(installTarget.loaded.manifest.hosted.url, pendingClients, parsed.scope);
+                        commands.push(connectCommand);
+                    }
+                }
             }
         }
         // `--with-github-action`: also drop the PR Visual Recap workflow into the
@@ -3638,7 +3869,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
                 ? ""
                 : installTarget.loaded.manifest.hosted.mcpUrl,
-            mcpClients: shouldRegisterMcp ? clients : [],
+            mcpClients: registeredMcpClients,
             dryRun: parsed.dryRun,
             commands,
             written: instructionsWritten,
@@ -3655,15 +3886,29 @@ export async function addAgentNativeSkill(parsed, options = {}) {
         installTarget.cleanup?.();
     }
 }
-function listSkills() {
-    return Object.values(BUILT_IN_APP_SKILLS).map((entry) => ({
-        id: entry.manifest.id,
-        aliases: BUILT_IN_APP_SKILL_DISPLAY_ALIASES[entry.manifest.id] ?? [],
-        name: entry.manifest.displayName,
-        description: entry.manifest.description,
-        mcpUrl: isLocalOnlyBuiltInSkill(entry) ? "" : entry.manifest.hosted.mcpUrl,
-        local: isLocalOnlyBuiltInSkill(entry),
-    }));
+function listSkills(options = {}) {
+    return [
+        ...Object.values(BUILT_IN_APP_SKILLS).map((entry) => ({
+            id: entry.manifest.id,
+            aliases: BUILT_IN_APP_SKILL_DISPLAY_ALIASES[entry.manifest.id] ?? [],
+            name: entry.manifest.displayName,
+            description: entry.manifest.description,
+            mcpUrl: isLocalOnlyBuiltInSkill(entry)
+                ? ""
+                : entry.manifest.hosted.mcpUrl,
+            local: isLocalOnlyBuiltInSkill(entry),
+            source: "agent-native",
+        })),
+        ...publicSkillEntries(options).map((entry) => ({
+            id: entry.name,
+            aliases: [],
+            name: entry.name,
+            description: entry.description ?? "Public skill from the BuilderIO skills catalog.",
+            mcpUrl: "",
+            local: true,
+            source: options.publicSkillSource ?? DEFAULT_PUBLIC_SKILLS_SOURCE,
+        })),
+    ];
 }
 function skillStateJson(state) {
     return {
@@ -3696,6 +3941,55 @@ function planModeSummary(mode) {
         return "Self-hosted/custom Plan app";
     return "Hosted Plans - shareable links and comments";
 }
+function targetInstallsMcp(target, parsed) {
+    if (!parsed.mcp)
+        return false;
+    if (publicSkillSelectionNames(target))
+        return false;
+    const knownTarget = normalizeKnownSkillTarget(target);
+    if (knownTarget === "visual-plans")
+        return parsed.planMode !== "local-files";
+    if (knownTarget) {
+        return !isLocalOnlyBuiltInSkill(BUILT_IN_APP_SKILLS[knownTarget]);
+    }
+    return true;
+}
+function targetsInstallMcp(targets, parsed) {
+    return targets.some((target) => targetInstallsMcp(target, parsed));
+}
+function instructionContentForSkill(skillName) {
+    if (skillName === "quick-recap") {
+        return "When writing final response status indicators, use the /quick-recap skill always.";
+    }
+    if (skillName === "efficient-fable") {
+        return "When operating as Claude Fable, use the /efficient-fable skill always.";
+    }
+    if (skillName === "efficient-frontier") {
+        return "When using a high-cost frontier model for codebase-heavy work, use the /efficient-frontier skill always.";
+    }
+    if (skillName === "stay-within-limits") {
+        return "When long-running or parallel work needs usage-limit checks, use the /stay-within-limits skill always.";
+    }
+    if (skillName === "visual-plan") {
+        return "When work needs an interactive visual plan before implementation, use the /visual-plan skill always.";
+    }
+    if (skillName === "visual-recap") {
+        return "When a PR, branch, commit, or diff needs an interactive visual recap, use the /visual-recap skill always.";
+    }
+    return null;
+}
+function selectedPlainSkillNamesForInstructionPrompt(targets, parsed) {
+    const names = new Set(parsed.plainSkillNames ?? []);
+    for (const target of targets) {
+        for (const name of publicSkillSelectionNames(target) ?? []) {
+            names.add(name);
+        }
+    }
+    return [...names];
+}
+function hasManagedInstructionBlock(skillNames) {
+    return skillNames.some((name) => Boolean(instructionContentForSkill(name)));
+}
 function runSkillsStatusOrUpdate(parsed, options, update) {
     const before = collectSkillInstallStates(parsed, options);
     const changed = update ? updateSkillInstallStates(before, parsed.dryRun) : [];
@@ -3752,9 +4046,19 @@ function readCliVersion() {
 }
 export async function runSkills(argv, options = {}) {
     const parsed = parseSkillsArgs(argv);
+    if (parsed.baseDir) {
+        options = { ...options, baseDir: path.resolve(parsed.baseDir) };
+    }
+    const clackForLog = parsed.printJson
+        ? undefined
+        : await import("@clack/prompts");
     const log = parsed.printJson
         ? undefined
-        : (message) => process.stdout.write(`${message}\n`);
+        : (message) => {
+            if (!message.trim())
+                return;
+            clackForLog?.log.info(message);
+        };
     if (parsed.command === "help") {
         process.stdout.write(`${HELP}\n`);
         return;
@@ -3764,6 +4068,7 @@ export async function runSkills(argv, options = {}) {
     // `npx @agent-native/skills@latest 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.
+    const previousDirect = process.env.AGENT_NATIVE_SKILLS_DIRECT;
     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
@@ -3780,7 +4085,7 @@ export async function runSkills(argv, options = {}) {
     try {
         telemetry.track("skills_cli started");
         if (parsed.command === "list") {
-            const skills = listSkills();
+            const skills = listSkills(optionsWithTelemetry);
             telemetry.track("skills_cli skills listed", {
                 availableCount: skills.length,
                 available: skills.map((skill) => skill.id).join(","),
@@ -3815,10 +4120,11 @@ export async function runSkills(argv, options = {}) {
             // 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,
+            selectedAll: targets.length === skillPromptOptions(options).length,
             preselected,
         });
-        const includesPlans = targetsIncludePlans(targets);
+        const includesPlans = targetsIncludePlans(targets) ||
+            planSkillNamesSelected(parsed.plainSkillNames);
         if (parsed.planMode && !includesPlans) {
             throw new Error("--mode only applies to visual-plan / visual-recap.");
         }
@@ -3857,7 +4163,8 @@ export async function runSkills(argv, options = {}) {
                 mode: parsed.planMode,
             });
         }
-        const clients = await resolveSkillsClients(parsed, optionsWithTelemetry);
+        const installsMcp = targetsInstallMcp(targets, parsed);
+        const clients = await resolveSkillsClients(parsed, optionsWithTelemetry, installsMcp);
         if (!clients) {
             telemetry.track("skills_cli cancelled", { step: "clients" });
             return;
@@ -3878,6 +4185,20 @@ export async function runSkills(argv, options = {}) {
             parsed.scope = scope;
         }
         telemetry.track("skills_cli scope selected", { scope: parsed.scope });
+        const instructionSkillNames = selectedPlainSkillNamesForInstructionPrompt(targets, parsed);
+        if (parsed.updateInstructions === undefined &&
+            hasManagedInstructionBlock(instructionSkillNames) &&
+            shouldPrompt(parsed, options)) {
+            const prompt = options.promptUpdateInstructions ?? promptForUpdateInstructions;
+            const choice = await prompt();
+            if (choice === null) {
+                telemetry.track("skills_cli cancelled", {
+                    step: "managed-instructions",
+                });
+                return;
+            }
+            parsed.updateInstructions = choice === true;
+        }
         // 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` +
@@ -3888,7 +4209,7 @@ export async function runSkills(argv, options = {}) {
                 return false;
             const only = builtInOnlySkillNames(target);
             return !only || only.includes("visual-recap");
-        });
+        }) || recapSkillNamesSelected(parsed.plainSkillNames);
         if (anyRecapTarget &&
             !parsed.withGithubAction &&
             !fs.existsSync(prVisualRecapWorkflowPath(recapBaseDir)) &&
@@ -4011,15 +4332,16 @@ export async function runSkills(argv, options = {}) {
         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`);
+            clack.log.info(line);
         }
         const slashCommands = completedSkills.map((name) => `/${name}`).join("  ");
-        const configuredEveryClient = CLIENTS.every((client) => clients.includes(client));
+        const configuredEveryClient = SKILLS_CLIENTS.every((client) => clients.includes(client));
         const clientHint = configuredEveryClient
             ? ""
             : "\n   Add another client later with --client <client> (e.g. --client claude-code).";
+        const reloadTarget = mcpClients.length > 0 ? "skill + MCP server" : "skill";
         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.` +
+            `\n   You may need to reload the client for the ${reloadTarget} to appear.` +
             clientHint);
     }
     catch (error) {
@@ -4032,6 +4354,12 @@ export async function runSkills(argv, options = {}) {
     }
     finally {
         await telemetry.flush();
+        if (previousDirect === undefined) {
+            delete process.env.AGENT_NATIVE_SKILLS_DIRECT;
+        }
+        else {
+            process.env.AGENT_NATIVE_SKILLS_DIRECT = previousDirect;
+        }
     }
 }
 //# sourceMappingURL=skills.js.map