@agent-native/skills 0.2.1 → 0.2.3

package/dist/index.js

@@ -3,7 +3,6 @@ import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { resolveAppForSkill } from "./built-in-apps.js";
 import { registerMcpServer } from "./connect.js";
@@ -26,6 +25,7 @@ Options:
   --with-github-action        Add .github/workflows/pr-visual-recap.yml when visual-recap is installed
   --force                     Overwrite a different existing PR Visual Recap workflow
   --no-mcp                    Install skill files only; skip registering the app's MCP server
+  --no-connect                Register MCP where possible but skip inline browser/device authentication
   -y, --yes                   Use defaults in non-interactive mode
   --dry-run                   Print intended writes without changing files
   --json                      Print the result as JSON
@@ -119,6 +119,10 @@ export function parseSkillsCliArgs(argv) {
             out.mcp = false;
         else if (arg === "--mcp")
             out.mcp = true;
+        else if (arg === "--no-connect" || arg === "--skip-connect")
+            out.connect = false;
+        else if (arg === "--connect")
+            out.connect = true;
         else if (arg.startsWith("-"))
             throw new Error(`Unknown option: ${arg}`);
         else if (!out.source)
@@ -167,6 +171,8 @@ function toCoreSkillsArgv(parsed) {
         out.push("--force");
     if (parsed.mcp === false)
         out.push("--no-mcp");
+    if (parsed.connect === false)
+        out.push("--no-connect");
     if (parsed.updateInstructions === true)
         out.push("--update-instructions");
     if (parsed.updateInstructions === false)
@@ -230,6 +236,9 @@ export async function runSkillsCli(argv, options = {}) {
                 source.cleanup?.();
             }
         }
+        const stdoutLog = parsed.printJson || options.log
+            ? options.log
+            : (message) => process.stdout.write(`${message}\n`);
         const result = await installSkills({
             source: skillSource,
             skillNames: parsed.skillNames,
@@ -244,8 +253,15 @@ export async function runSkillsCli(argv, options = {}) {
             instructionFiles: parsed.instructionFiles,
             withGithubAction: parsed.withGithubAction,
             force: parsed.force,
-            log: parsed.printJson ? undefined : options.log,
+            connect: parsed.connect,
+            quiet: parsed.printJson,
+            log: parsed.printJson ? undefined : stdoutLog,
             isInteractive: options.isInteractive,
+            promptSkills: options.promptSkills,
+            promptClients: options.promptClients,
+            promptScope: options.promptScope,
+            promptUpdateInstructions: options.promptUpdateInstructions,
+            promptGithubAction: options.promptGithubAction,
             telemetry,
             mcp: parsed.mcp,
         });
@@ -260,28 +276,10 @@ export async function runSkillsCli(argv, options = {}) {
             process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
             return;
         }
-        const verb = parsed.dryRun ? "Would install" : "Installed";
-        process.stdout.write([
-            `${verb} ${result.skills.join(", ")} for ${result.clients.join(", ")} (${result.scope}).`,
-            result.written.length
-                ? `Skill files: ${result.written.join(", ")}`
-                : "",
-            result.instructionFiles.length
-                ? `Managed instructions: ${result.instructionFiles.join(", ")}`
-                : "",
-            result.githubActionPath
-                ? `PR Visual Recap workflow: ${result.githubActionPath}`
-                : "",
-            ...result.mcpServers.flatMap((server) => [
-                `MCP server "${server.serverName}" ${parsed.dryRun ? "would be registered" : "registered"} for ${server.clients.join(", ")}${server.files.length ? `:\n  ${server.files.join("\n  ")}` : ""}`,
-                ...server.guidance.map((line) => `  ${line}`),
-            ]),
-            parsed.dryRun
-                ? ""
-                : "Restart or reload selected agent clients if needed.",
-        ]
-            .filter(Boolean)
-            .join("\n") + "\n");
+        await printInstallResult(result, {
+            baseDir: parsed.baseDir ?? options.baseDir ?? process.cwd(),
+            dryRun: parsed.dryRun,
+        });
     }
     catch (error) {
         telemetry.track("skills_cli failed", {
@@ -352,98 +350,126 @@ export async function installSkills(options) {
         });
         const scope = await resolveSelectedScope(options);
         options.telemetry?.track("skills_cli scope selected", { scope });
+        const skillNames = selected.map((skill) => skill.name);
+        const instructionBlocks = managedInstructionBlocksForSkills(skillNames);
+        const shouldUpdateInstructions = await shouldUpdateManagedInstructions(instructionBlocks, options);
+        const shouldWriteGithubAction = selected.some((skill) => skill.name === "visual-recap") &&
+            (options.withGithubAction ||
+                (await shouldPromptGithubAction(options, baseDir)));
+        const mcpApps = options.mcp === false ? [] : mcpAppsForSkills(skillNames);
+        const progress = await createInstallProgress(options, 1 +
+            (shouldUpdateInstructions ? 1 : 0) +
+            (shouldWriteGithubAction ? 1 : 0) +
+            mcpApps.length);
         const written = [];
-        for (const client of clients) {
-            const root = installRootForClient(client, scope, baseDir);
-            for (const skill of selected) {
-                const destination = path.join(root, skill.name);
-                written.push(destination);
-                if (!options.dryRun) {
-                    fs.rmSync(destination, { recursive: true, force: true });
-                    fs.mkdirSync(path.dirname(destination), { recursive: true });
-                    fs.cpSync(skill.dir, destination, { recursive: true });
+        let instructionFiles = [];
+        let githubActionPath;
+        const mcpServers = [];
+        try {
+            progress?.start("Installing skill files...");
+            for (const client of clients) {
+                const root = installRootForClient(client, scope, baseDir);
+                for (const skill of selected) {
+                    const destination = path.join(root, skill.name);
+                    written.push(destination);
+                    if (!options.dryRun) {
+                        fs.rmSync(destination, { recursive: true, force: true });
+                        fs.mkdirSync(path.dirname(destination), { recursive: true });
+                        fs.cpSync(skill.dir, destination, { recursive: true });
+                    }
                 }
             }
-        }
-        options.telemetry?.track("skills_cli install completed", {
-            skills: selected.map((skill) => skill.name).join(","),
-            clients: clients.join(","),
-            scope,
-            writtenCount: written.length,
-            dryRun: Boolean(options.dryRun),
-        });
-        const instructionFiles = await maybeUpdateInstructions(selected.map((skill) => skill.name), baseDir, options);
-        if (instructionFiles.length) {
-            options.telemetry?.track("skills_cli instructions updated", {
-                fileCount: instructionFiles.length,
+            progress?.advance("Skill files installed");
+            options.telemetry?.track("skills_cli install completed", {
+                skills: skillNames.join(","),
+                clients: clients.join(","),
+                scope,
+                writtenCount: written.length,
+                dryRun: Boolean(options.dryRun),
             });
-        }
-        const githubActionPath = selected.some((skill) => skill.name === "visual-recap") &&
-            (options.withGithubAction ||
-                (await shouldPromptGithubAction(options, baseDir)))
-            ? writePrVisualRecapWorkflow(baseDir, options)
-            : undefined;
-        if (githubActionPath) {
-            options.telemetry?.track("skills_cli github action added");
-        }
-        // 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.
-        const mcpServers = [];
-        if (options.mcp !== false) {
-            const mcpClients = clients.map((client) => client === "claude-code" ? "claude-code" : "codex");
-            const seenApps = new Set();
-            for (const skill of selected) {
-                const app = resolveAppForSkill(skill.name);
-                if (!app || seenApps.has(app.appId))
-                    continue;
-                seenApps.add(app.appId);
-                if (options.dryRun) {
-                    mcpServers.push({
-                        serverName: app.serverName,
-                        mcpUrl: app.mcpUrl,
-                        clients,
-                        files: [],
-                        authenticated: false,
-                        guidance: [],
+            if (shouldUpdateInstructions) {
+                progress?.message("Updating managed instructions...");
+                instructionFiles = writeManagedInstructions(instructionBlocks, baseDir, clients, scope, options);
+                progress?.advance("Managed instructions updated");
+                if (instructionFiles.length) {
+                    options.telemetry?.track("skills_cli instructions updated", {
+                        fileCount: instructionFiles.length,
                     });
-                    continue;
                 }
-                const registration = await registerMcpServer({
-                    descriptor: {
-                        serverName: app.serverName,
-                        mcpUrl: app.mcpUrl,
-                        aliases: app.aliases,
-                        authMode: app.authMode,
-                        hostedUrl: app.hostedUrl,
-                    },
-                    clients: mcpClients,
-                    scope,
-                    baseDir,
-                    interactive: isInteractive(options),
-                    log,
-                });
-                mcpServers.push({
-                    serverName: app.serverName,
-                    mcpUrl: app.mcpUrl,
-                    clients,
-                    files: [...new Set(registration.written.map((entry) => entry.file))],
-                    authenticated: registration.authenticated,
-                    guidance: registration.guidance,
-                });
-                options.telemetry?.track("skills_cli mcp registered", {
-                    serverName: app.serverName,
-                    clients: clients.join(","),
-                    authenticated: registration.authenticated,
-                });
             }
+            if (shouldWriteGithubAction) {
+                progress?.message("Writing PR Visual Recap workflow...");
+                githubActionPath = writePrVisualRecapWorkflow(baseDir, options);
+                progress?.advance("PR Visual Recap workflow ready");
+                if (githubActionPath) {
+                    options.telemetry?.track("skills_cli github action added");
+                }
+            }
+            // 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.
+            if (mcpApps.length > 0) {
+                const mcpClients = clients.map((client) => client === "claude-code" ? "claude-code" : "codex");
+                for (const app of mcpApps) {
+                    progress?.message(`Registering ${app.displayName} MCP server...`);
+                    if (!options.dryRun) {
+                        const registration = await registerMcpServer({
+                            descriptor: {
+                                serverName: app.serverName,
+                                mcpUrl: app.mcpUrl,
+                                aliases: app.aliases,
+                                authMode: app.authMode,
+                                hostedUrl: app.hostedUrl,
+                            },
+                            clients: mcpClients,
+                            scope,
+                            baseDir,
+                            interactive: options.connect !== false && isInteractive(options),
+                            log,
+                            deviceFlowTimeoutMs: options.deviceFlowTimeoutMs,
+                        });
+                        mcpServers.push({
+                            serverName: app.serverName,
+                            mcpUrl: app.mcpUrl,
+                            clients,
+                            registeredClients: unique(registration.written.map((entry) => entry.client)),
+                            files: [
+                                ...new Set(registration.written.map((entry) => entry.file)),
+                            ],
+                            authenticated: registration.authenticated,
+                            guidance: registration.guidance,
+                        });
+                        options.telemetry?.track("skills_cli mcp registered", {
+                            serverName: app.serverName,
+                            clients: clients.join(","),
+                            authenticated: registration.authenticated,
+                        });
+                    }
+                    else {
+                        mcpServers.push({
+                            serverName: app.serverName,
+                            mcpUrl: app.mcpUrl,
+                            clients,
+                            registeredClients: clients,
+                            files: [],
+                            authenticated: false,
+                            guidance: [],
+                        });
+                    }
+                    progress?.advance(`${app.displayName} MCP server ready`);
+                }
+            }
+            progress?.stop("Installation complete");
+        }
+        catch (err) {
+            progress?.error("Installation failed");
+            throw err;
         }
-        log(`Resolved ${selected.length} skill${selected.length === 1 ? "" : "s"} from ${source.root}.`);
         return {
             source: source.root,
-            skills: selected.map((skill) => skill.name),
+            skills: skillNames,
             clients,
             scope,
             written,
@@ -471,6 +497,7 @@ function defaultArgs(command) {
         instructionFiles: [],
         withGithubAction: false,
         force: false,
+        connect: true,
         mcp: true,
     };
 }
@@ -506,6 +533,157 @@ function normalizeSkillName(value) {
 function unique(values) {
     return [...new Set(values)];
 }
+function plural(count, singular, pluralForm = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+function shortenPathForOutput(file, baseDir) {
+    const resolved = path.resolve(file);
+    const home = process.env.HOME || os.homedir();
+    if (resolved === home || resolved.startsWith(`${home}${path.sep}`)) {
+        return `~${resolved.slice(home.length)}`;
+    }
+    const base = path.resolve(baseDir);
+    const relative = path.relative(base, resolved);
+    if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) {
+        return `.${path.sep}${relative}`;
+    }
+    return file;
+}
+function summarizePaths(files, baseDir, max = 4) {
+    const shortened = unique(files).map((file) => shortenPathForOutput(file, baseDir));
+    if (shortened.length <= max)
+        return shortened.join(", ");
+    return `${shortened.slice(0, max).join(", ")} +${shortened.length - max} more`;
+}
+async function createInstallProgress(options, max) {
+    if (options.quiet || !isInteractive(options) || max <= 0)
+        return null;
+    const clack = await import("@clack/prompts");
+    const progress = clack.progress({ max, indicator: "timer" });
+    let active = false;
+    return {
+        start(message) {
+            active = true;
+            progress.start(message);
+        },
+        message(message) {
+            if (active)
+                progress.message(message);
+        },
+        advance(message) {
+            if (active)
+                progress.advance(1, message);
+        },
+        stop(message) {
+            if (!active)
+                return;
+            progress.stop(message);
+            active = false;
+        },
+        error(message) {
+            if (!active)
+                return;
+            progress.error(message);
+            active = false;
+        },
+    };
+}
+function mcpAppsForSkills(skillNames) {
+    const apps = [];
+    const seen = new Set();
+    for (const skillName of skillNames) {
+        const app = resolveAppForSkill(skillName);
+        if (!app || seen.has(app.appId))
+            continue;
+        seen.add(app.appId);
+        apps.push(app);
+    }
+    return apps;
+}
+function mcpStatus(server, dryRun) {
+    if (dryRun)
+        return `would register for ${server.clients.join(", ")}`;
+    const registered = server.registeredClients;
+    const pending = server.clients.filter((client) => !registered.includes(client));
+    const parts = [];
+    if (registered.length > 0) {
+        parts.push(`${server.authenticated ? "registered and authenticated" : "registered"} for ${registered.join(", ")}`);
+    }
+    if (pending.length > 0) {
+        parts.push(`authentication pending for ${pending.join(", ")}`);
+    }
+    return (parts.join("; ") ||
+        `authentication pending for ${server.clients.join(", ")}`);
+}
+async function printInstallResult(result, options) {
+    const clack = await import("@clack/prompts");
+    const verb = options.dryRun ? "Would install" : "Installed";
+    const summary = [
+        `Skills        ${result.skills.join(", ") || "none"}`,
+        `Agents        ${result.clients.join(", ") || "none"}`,
+        `Scope         ${result.scope}`,
+        result.written.length
+            ? `Skill folders ${plural(result.written.length, "folder")} (${summarizePaths(result.written, options.baseDir)})`
+            : "",
+    ].filter(Boolean);
+    clack.note(summary.join("\n"), verb);
+    if (result.instructionFiles.length) {
+        clack.note(summarizePaths(result.instructionFiles, options.baseDir), "Managed instructions");
+    }
+    if (result.githubActionPath) {
+        clack.note(shortenPathForOutput(result.githubActionPath, options.baseDir), "PR Visual Recap workflow");
+    }
+    if (result.mcpServers.length) {
+        const mcpLines = result.mcpServers.map((server) => {
+            const status = mcpStatus(server, options.dryRun);
+            const files = server.files.length
+                ? ` (${summarizePaths(server.files, options.baseDir, 2)})`
+                : "";
+            return `${server.serverName}: ${status}${files}`;
+        });
+        clack.note(mcpLines.join("\n"), "MCP");
+        const guidance = result.mcpServers.flatMap((server) => server.guidance);
+        if (guidance.length) {
+            clack.note(guidance.join("\n"), "Next steps");
+        }
+    }
+    if (!options.dryRun) {
+        clack.note("Restart or reload selected agent clients if needed.", "Reload");
+    }
+    clack.outro(`${options.dryRun ? "Dry run complete" : "All set"} ✅`);
+}
+function compactPromptHint(value) {
+    const hint = value?.replace(/\s+/g, " ").trim() ?? "";
+    if (!hint)
+        return "Skill from BuilderIO/skills.";
+    if (hint.length <= 96)
+        return hint;
+    return `${hint.slice(0, 93).trimEnd()}...`;
+}
+function skillPromptOptions(entries) {
+    return entries.map((entry) => ({
+        value: entry.name,
+        label: entry.name,
+        hint: compactPromptHint(entry.description),
+    }));
+}
+async function promptForSkills(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.multiselect({
+        message: "Which skills do you want to install?\n" +
+            "  (space toggles, enter confirms)",
+        options: context.options,
+        initialValues: context.initialSkills,
+        required: true,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    if (!Array.isArray(result))
+        return [];
+    return result.filter((value) => typeof value === "string");
+}
 async function resolveSelectedSkills(entries, options) {
     const byName = new Map(entries.map((entry) => [entry.name, entry]));
     const requested = unique((options.skillNames ?? []).map(normalizeSkillName));
@@ -520,47 +698,87 @@ async function resolveSelectedSkills(entries, options) {
     }
     if (!isInteractive(options) || options.yes)
         return entries;
-    const answer = await promptLine([
-        "Which skills do you want to install?",
-        ...entries.map((entry, index) => `  ${index + 1}. ${entry.name}${entry.description ? ` - ${entry.description}` : ""}`),
-        "Enter numbers or names separated by commas, or press Enter for all: ",
-    ].join("\n"));
-    const trimmed = answer.trim();
-    if (!trimmed)
-        return entries;
-    const selectedNames = trimmed
-        .split(",")
-        .map((part) => part.trim())
-        .filter(Boolean)
-        .map((part) => {
-        const asNumber = Number(part);
-        if (Number.isInteger(asNumber) &&
-            asNumber >= 1 &&
-            asNumber <= entries.length) {
-            return entries[asNumber - 1].name;
-        }
-        return normalizeSkillName(part);
+    const prompt = options.promptSkills ?? promptForSkills;
+    const selectedNames = await prompt({
+        initialSkills: entries.map((entry) => entry.name),
+        options: skillPromptOptions(entries),
     });
+    if (!selectedNames || selectedNames.length === 0) {
+        throw new Error("Cancelled.");
+    }
     return resolveSelectedSkills(entries, {
         ...options,
         skillNames: selectedNames,
     });
 }
+async function promptForScope(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.select({
+        message: "Where do you want to install these skills?",
+        options: [
+            {
+                value: "project",
+                label: "Project",
+                hint: "This repo only (.agents / .claude in the current directory)",
+            },
+            {
+                value: "user",
+                label: "User",
+                hint: "Your home directory (~/.codex, ~/.claude), across projects",
+            },
+        ],
+        initialValue: context.initialScope,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    return result === "user" ? "user" : "project";
+}
 async function resolveSelectedScope(options) {
     if (options.scope)
         return options.scope;
     if (!isInteractive(options) || options.yes)
         return "user";
-    const answer = await promptLine([
-        "Where do you want to install these skills?",
-        "  1. project - this repo only (.agents / .claude in the current directory)",
-        "  2. user    - your home directory, available across all projects",
-        "Enter project or user [project]: ",
-    ].join("\n"));
-    const trimmed = answer.trim().toLowerCase();
-    if (trimmed === "2" || trimmed === "user" || trimmed === "u")
-        return "user";
-    return "project";
+    const prompt = options.promptScope ?? promptForScope;
+    const selected = await prompt({ initialScope: "project" });
+    if (!selected)
+        throw new Error("Cancelled.");
+    return selected;
+}
+function clientPromptOptions() {
+    return [
+        {
+            value: "codex",
+            label: "Codex",
+            hint: "Install into Codex skill directories",
+        },
+        {
+            value: "claude-code",
+            label: "Claude Code",
+            hint: "Install into Claude Code skill directories",
+        },
+    ];
+}
+function normalizePromptClients(values) {
+    if (!Array.isArray(values))
+        return [];
+    return unique(values.filter((value) => value === "codex" || value === "claude-code"));
+}
+async function promptForClients(context) {
+    const clack = await import("@clack/prompts");
+    const result = await clack.multiselect({
+        message: "Install these skills for which local agents?\n" +
+            "  (space toggles, enter confirms)",
+        options: context.options,
+        initialValues: context.initialClients,
+        required: true,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Cancelled.");
+        return null;
+    }
+    return normalizePromptClients(result);
 }
 async function resolveSelectedClients(options) {
     const requested = unique(options.clients ?? []);
@@ -568,9 +786,14 @@ async function resolveSelectedClients(options) {
         return requested;
     if (!isInteractive(options) || options.yes)
         return CLIENTS;
-    const answer = await promptLine("Install for which clients? Enter codex, claude-code, or all [all]: ");
-    const trimmed = answer.trim();
-    return trimmed ? unique(normalizeClients(trimmed)) : CLIENTS;
+    const prompt = options.promptClients ?? promptForClients;
+    const selected = await prompt({
+        initialClients: CLIENTS,
+        options: clientPromptOptions(),
+    });
+    if (!selected || selected.length === 0)
+        throw new Error("Cancelled.");
+    return selected;
 }
 function isInteractive(options) {
     if (options.isInteractive)
@@ -579,18 +802,6 @@ function isInteractive(options) {
         return false;
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
-async function promptLine(question) {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    try {
-        return await rl.question(question);
-    }
-    finally {
-        rl.close();
-    }
-}
 function installRootForClient(client, scope, baseDir) {
     const home = process.env.HOME || os.homedir();
     if (scope === "project") {
@@ -647,14 +858,34 @@ function skillEntry(dir) {
         return null;
     const body = fs.readFileSync(skillFile, "utf-8");
     const frontmatter = body.match(/^---\n([\s\S]*?)\n---/);
-    const name = frontmatter?.[1]
-        ?.match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1]
-        ?.trim() ?? path.basename(dir);
-    const description = frontmatter?.[1]
-        ?.match(/^description:\s*(?:>-\s*)?(.+)$/m)?.[1]
-        ?.trim();
+    const name = frontmatterField(frontmatter?.[1], "name") ?? path.basename(dir);
+    const description = frontmatterField(frontmatter?.[1], "description");
     return { name: normalizeSkillName(name), dir, description };
 }
+function frontmatterField(frontmatter, field) {
+    if (!frontmatter)
+        return undefined;
+    const lines = frontmatter.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i += 1) {
+        const match = lines[i].match(new RegExp(`^${field}:\\s*(.*)$`));
+        if (!match)
+            continue;
+        const raw = match[1].trim();
+        if (raw === ">-" || raw === ">" || raw === "|-" || raw === "|") {
+            const block = [];
+            for (let j = i + 1; j < lines.length; j += 1) {
+                const line = lines[j];
+                if (line.trim() && !/^\s/.test(line))
+                    break;
+                block.push(line.replace(/^\s+/, ""));
+            }
+            const value = raw.startsWith("|") ? block.join("\n") : block.join(" ");
+            return value.replace(/\s+/g, " ").trim() || undefined;
+        }
+        return raw.replace(/^["']|["']$/g, "").trim() || undefined;
+    }
+    return undefined;
+}
 async function materializeSource(input) {
     const local = path.resolve(input);
     if (fs.existsSync(local))
@@ -729,70 +960,49 @@ function parseGitHubSource(input) {
 }
 function instructionContentForSkill(skillName) {
     if (skillName === "quick-recap") {
-        return `## Quick Recap Status Block
-
-Every response that completes a unit of work must end with one final status line:
-
-\`\`\`md
-🟢 Actual concise status sentence
-\`\`\`
-
-Use 🟢 when the requested work is finished. Use 🟡 when non-routine follow-up work or a manual step remains, and name that pending item. Use 🔴 only when blocked on user input. Keep the status line under 100 characters. Put the status line at the very end of the response. Do not add \`---\`, spacer lines, or any content after it.
-
-Examples:
-
-\`\`\`md
-🟢 Updated quick recap docs with output examples
-\`\`\`
-
-\`\`\`md
-🟡 Code updated, set PROVIDER_WEBHOOK_SECRET before testing webhooks
-\`\`\`
-
-\`\`\`md
-🔴 Need the production API key to continue
-\`\`\``;
+        return "When writing final response status indicators, use the /quick-recap skill always.";
     }
     if (skillName === "efficient-fable") {
-        return `## Efficient Fable
-
-When operating as Claude Fable or another explicitly Fable-class expensive model, preserve Fable for the judgment layer: decomposition, architecture and product tradeoffs, synthesis, risk calls, and final review. Delegate token-heavy research, coding, testing, file inventory, repetitive edits, and independent implementation slices to cheaper subagents when available. Write delegated prompts as self-contained handoff packets with objective, scope, out-of-scope areas, expected evidence, verification commands, and stop conditions. For testing, Fable should suggest the validation direction and important scripts or browser checks, then lighter agents can run them, reduce logs, collect screenshots, and report exact failures and likely causes. Treat delegated reports as leads: Fable should verify important cited files, failures, and high-risk diffs before relying on them. Do not make unsupported quality or speed guarantees; frame savings as workload-dependent.`;
+        return "When operating as Claude Fable, use the /efficient-fable skill always.";
     }
     if (skillName === "efficient-frontier") {
-        return `## Efficient Frontier
-
-When running any high-cost frontier model on a codebase-heavy task, act as the orchestrator and reviewer. Split independent research, search, summarization, coding, and testing work into cheaper/faster subagents when the host supports them, then spend frontier-model tokens on the plan, tradeoffs, integration decisions, validation strategy, and final quality pass. Delegated prompts should be self-contained: objective, repo path, scope, out-of-scope areas, expected evidence, verification commands, and stop conditions. For testing-heavy work, the frontier model should choose the scripts or browser flows that matter while lighter agents run checks, reduce output, and return the concrete signal. Treat delegated findings as leads and verify important claims before presenting them as facts.`;
+        return "When using a high-cost frontier model for codebase-heavy work, use the /efficient-frontier skill always.";
     }
     if (skillName === "stay-within-limits") {
-        return `## Stay Within Limits
-
-Before starting long-running or parallel agent work, and between waves, check current 5-hour and weekly usage limits with the host's usage tool. For Claude Code, use npx -y ccusage@latest blocks --active --json when no better first-party signal is available. Keep waves to at most 3 parallel subagents by default. If either active 5-hour or weekly window is at or above 95%, do not launch more work; pause until the window clears. When a wake/resume tool is available, schedule a self-contained wake prompt for min(3600, secondsUntilWindowClears), re-check the actual block/window on wake, reschedule if still over budget, and only continue when safely below the threshold. The wake prompt should restate the remaining plan, usage check, wave throttle, verification steps, and any delegation scope or stop conditions needed for the next wave. Check between waves, not mid-wave.`;
+        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;
 }
-async function maybeUpdateInstructions(skillNames, baseDir, options) {
-    const blocks = skillNames
+function managedInstructionBlocksForSkills(skillNames) {
+    return skillNames
         .map((name) => instructionContentForSkill(name))
         .filter((block) => Boolean(block));
+}
+async function shouldUpdateManagedInstructions(blocks, options) {
     if (blocks.length === 0)
-        return [];
+        return false;
     let shouldUpdate = options.updateInstructions;
-    if (shouldUpdate === undefined) {
-        if (options.yes)
-            shouldUpdate = true;
-        else if (isInteractive(options)) {
-            const answer = await promptLine("Add managed AGENTS.md / CLAUDE.md instructions for always-on behavior? [Y/n] ");
-            shouldUpdate = !/^n/i.test(answer.trim());
-        }
-        else {
-            shouldUpdate = false;
-        }
-    }
-    if (!shouldUpdate)
+    if (shouldUpdate !== undefined)
+        return shouldUpdate;
+    if (options.yes)
+        return true;
+    if (!isInteractive(options))
+        return false;
+    const prompt = options.promptUpdateInstructions ?? promptForUpdateInstructions;
+    return (await prompt()) === true;
+}
+function writeManagedInstructions(blocks, baseDir, clients, scope, options) {
+    if (blocks.length === 0)
         return [];
-    const files = resolveInstructionFiles(baseDir, options.instructionFiles);
+    const files = resolveInstructionFiles(baseDir, options.instructionFiles, clients, scope);
     const content = `${MANAGED_INSTRUCTIONS_START}
-${blocks.join("\n\n")}
+${blocks.join("\n")}
 ${MANAGED_INSTRUCTIONS_END}`;
     for (const file of files) {
         if (options.dryRun)
@@ -801,10 +1011,30 @@ ${MANAGED_INSTRUCTIONS_END}`;
     }
     return files;
 }
-function resolveInstructionFiles(baseDir, explicit) {
+async function maybeUpdateInstructions(skillNames, baseDir, options) {
+    const blocks = managedInstructionBlocksForSkills(skillNames);
+    const clients = options.clients?.length ? options.clients : CLIENTS;
+    const scope = options.scope ?? "user";
+    if (!(await shouldUpdateManagedInstructions(blocks, options)))
+        return [];
+    return writeManagedInstructions(blocks, baseDir, clients, scope, options);
+}
+function resolveInstructionFiles(baseDir, explicit, clients, scope) {
     if (explicit && explicit.length > 0) {
         return explicit.map((file) => path.resolve(baseDir, file));
     }
+    if (scope === "user") {
+        const home = process.env.HOME || os.homedir();
+        const files = [];
+        if (clients.includes("codex")) {
+            const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
+            files.push(path.join(codexHome, "AGENTS.md"));
+        }
+        if (clients.includes("claude-code")) {
+            files.push(path.join(home, ".claude", "CLAUDE.md"));
+        }
+        return unique(files);
+    }
     const candidates = ["AGENTS.md", "CLAUDE.md"].map((file) => path.join(baseDir, file));
     const existing = candidates.filter((file) => fs.existsSync(file));
     return existing.length > 0 ? existing : [path.join(baseDir, "AGENTS.md")];
@@ -829,8 +1059,36 @@ async function shouldPromptGithubAction(options, baseDir) {
     if (fs.existsSync(path.join(baseDir, ".github", "workflows", "pr-visual-recap.yml"))) {
         return false;
     }
-    const answer = await promptLine("Add the optional PR Visual Recap GitHub Action? [y/N] ");
-    return /^y/i.test(answer.trim());
+    const prompt = options.promptGithubAction ?? promptForGithubAction;
+    return ((await prompt({
+        workflowPath: path.join(".github", "workflows", "pr-visual-recap.yml"),
+    })) === true);
+}
+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 behavior?",
+        initialValue: true,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Skipped instruction update.");
+        return null;
+    }
+    return Boolean(result);
+}
+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" +
+            `  Writes ${context.workflowPath}.`,
+        initialValue: false,
+    });
+    if (clack.isCancel(result)) {
+        clack.cancel("Skipped PR Visual Recap workflow.");
+        return null;
+    }
+    return Boolean(result);
 }
 const PR_VISUAL_RECAP_REUSABLE_WORKFLOW = `name: PR Visual Recap