@agent-native/core 0.51.14 → 0.52.0

package/dist/cli/skills.js

@@ -19,9 +19,9 @@ const HELP = `npx @agent-native/core@latest skills
 
 Usage:
   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] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
+  npx @agent-native/core@latest skills status [assets|design-exploration|visual-plan|visual-recap|context-xray] [--client codex|claude-code|pi|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|pi|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|cursor|opencode|github-copilot|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--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:
@@ -44,11 +44,14 @@ 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, 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
+wall on the first tool call. Hosted installs can configure Claude Code, Codex,
+Claude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code; local-files
+instruction installs target the shared .agents skill path used by Codex, Pi,
+Cursor, OpenCode, Copilot, and similar agents, plus Claude Code's native skill
+path when selected. Pass --client to narrow it. Authentication reuses
+"npx @agent-native/core@latest connect": OAuth-capable clients (Claude Code,
+Cursor, OpenCode, GitHub Copilot / VS Code) get URL-only entries and authenticate
+inside that host, 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.
 
@@ -71,7 +74,7 @@ MDX folders, and local preview.
 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 "npx @agent-native/core@latest recap setup" / "npx @agent-native/core@latest recap doctor" to configure and
-verify GitHub Actions.
+verify GitHub Actions. Docs: https://www.agent-native.com/docs/pr-visual-recap.
 
 The status/update commands inspect copied Agent Native skill folders and refresh
 their instruction files from the current @agent-native/core package.`;
@@ -1334,8 +1337,8 @@ The local-files contract is:
 - Write the plan as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
   optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
   \`.plan-state.json\`.
-- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan\` after
-  writing or updating the folder. Report the returned local URL or the
+- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan --open\`
+  after writing or updating the folder. Report the returned local URL or the
   \`/local-plans/<slug>\` route if the local Plan app is running with the same
   \`PLAN_LOCAL_DIR\`.
 - Do **not** call \`create-visual-plan\`, \`create-ui-plan\`,
@@ -1483,8 +1486,8 @@ In local-files mode:
   optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
   \`.plan-state.json\`. Set \`kind: "recap"\` and \`localOnly: true\` in
   frontmatter/state when authoring the source.
-- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind recap\` after
-  writing or updating the folder. Report the returned local URL or the
+- Run \`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind recap --open\`
+  after writing or updating the folder. Report the returned local URL or the
   \`/local-plans/<slug>\` route if the local Plan app is running with the same
   \`PLAN_LOCAL_DIR\`.
 - Do **not** call \`create-visual-recap\`, \`create-visual-plan\`,
@@ -2111,7 +2114,7 @@ export const BUILT_IN_APP_SKILLS = {
             mcp: { serverName: "plan", aliases: ["agent-native-plans"] },
             auth: {
                 mode: "oauth",
-                setup: "Install with the Agent-Native CLI to add the /visual-plan and /visual-recap skills plus the Plan MCP connector. Authenticate only for hosted/account-backed sharing.",
+                setup: "The marketplace plugin uses hosted Agent-Native Plans by default. To choose local-files or self-hosted mode, install with the Agent-Native CLI. Authenticate only for hosted/account-backed sharing.",
             },
             surfaces: [
                 {
@@ -2239,20 +2242,45 @@ const CLIENT_LABELS = {
     "claude-code-cli": "Claude Code CLI",
     codex: "Codex",
     cowork: "Claude Cowork",
+    cursor: "Cursor",
+    opencode: "OpenCode",
+    "github-copilot": "GitHub Copilot / VS Code",
 };
 const CLIENT_HINTS = {
     "claude-code": ".mcp.json or ~/.claude.json",
     "claude-code-cli": ".mcp.json or ~/.claude.json",
     codex: "$CODEX_HOME/config.toml or ~/.codex/config.toml",
     cowork: "~/.cowork/mcp.json",
+    cursor: ".cursor/mcp.json or ~/.cursor/mcp.json",
+    opencode: "opencode.json or ~/.config/opencode/opencode.json",
+    "github-copilot": ".vscode/mcp.json or VS Code user mcp.json",
+};
+const SKILLS_CLIENTS = [
+    "claude-code",
+    "codex",
+    "cowork",
+    "cursor",
+    "opencode",
+    "github-copilot",
+];
+const SKILL_INSTRUCTION_CLIENTS = [
+    "codex",
+    "claude-code",
+    "pi",
+];
+const SKILL_INSTRUCTION_CLIENT_LABELS = {
+    "claude-code": "Claude Code",
+    "claude-code-cli": "Claude Code",
+    codex: "Shared .agents skills",
+    cowork: "MCP only",
+    pi: "Pi",
 };
-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",
+    "claude-code": "Also write Claude Code's native .claude/skills and commands files.",
+    "claude-code-cli": "Also write Claude Code's native .claude/skills and commands files.",
+    codex: "Project scope writes .agents skills/commands for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents; user scope writes Codex's ~/.codex skills/commands.",
     cowork: "MCP only",
+    pi: "Project scope writes .agents/skills plus .pi/prompts; user scope writes ~/.agents/skills plus ~/.pi/agent/prompts.",
 };
 function normalizeKnownSkillTarget(value) {
     const key = value?.trim().toLowerCase();
@@ -2322,7 +2350,7 @@ Default storage for this installation: local files. Create and update plans and
 recaps as MDX folders under \`plans/<slug>/\`. Before authoring structured MDX,
 run \`npx @agent-native/core@latest plan blocks --out plan-blocks.md\` and read
 the no-auth block catalog; it sends no plan content. Then run
-\`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan|recap\`,
+\`npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan|recap --open\`,
 and report the local preview URL or path. No sharing, all local. Use a hosted
 or self-hosted Plan MCP connector only if the user explicitly asks to publish or
 share.`;
@@ -2420,17 +2448,68 @@ function writeSkillFolder(dir, bundle, installedAt = new Date().toISOString()) {
 function builtInSkillsRootForAgent(agent, scope, baseDir) {
     const home = homeDir() ?? baseDir;
     if (scope === "project") {
-        return agent === "codex"
-            ? path.join(baseDir, ".agents", "skills")
-            : path.join(baseDir, ".claude", "skills");
+        if (agent === "codex")
+            return path.join(baseDir, ".agents", "skills");
+        if (agent === "pi")
+            return path.join(baseDir, ".agents", "skills");
+        return path.join(baseDir, ".claude", "skills");
     }
     if (agent === "codex") {
         return process.env.CODEX_HOME
             ? path.join(process.env.CODEX_HOME, "skills")
             : path.join(home, ".codex", "skills");
     }
+    if (agent === "pi") {
+        return path.join(home, ".agents", "skills");
+    }
     return path.join(home, ".claude", "skills");
 }
+function builtInCommandsRootForAgent(agent, scope, baseDir) {
+    const home = homeDir() ?? baseDir;
+    if (scope === "project") {
+        if (agent === "codex")
+            return path.join(baseDir, ".agents", "commands");
+        if (agent === "pi")
+            return path.join(baseDir, ".pi", "prompts");
+        return path.join(baseDir, ".claude", "commands");
+    }
+    if (agent === "codex") {
+        return process.env.CODEX_HOME
+            ? path.join(process.env.CODEX_HOME, "commands")
+            : path.join(home, ".codex", "commands");
+    }
+    if (agent === "pi") {
+        const piHome = process.env.PI_CODING_AGENT_DIR || path.join(home, ".pi", "agent");
+        return path.join(piHome, "prompts");
+    }
+    return path.join(home, ".claude", "commands");
+}
+function slashCommandForBuiltInSkill(skillName) {
+    if (skillName === "visual-plan") {
+        return `---
+description: Create an interactive Agent-Native visual plan for the current task.
+argument-hint: [optional request or scope]
+---
+
+Use the visual-plan skill for this task. Treat any arguments as the user's
+requested plan scope or focus:
+
+$ARGUMENTS
+`;
+    }
+    if (skillName === "visual-recap") {
+        return `---
+description: Create an interactive Agent-Native visual recap for a PR, branch, commit, or diff.
+argument-hint: [PR, branch, commit, diff, or scope]
+---
+
+Use the visual-recap skill. Treat any arguments as the recap target or focus:
+
+$ARGUMENTS
+`;
+    }
+    return null;
+}
 /**
  * Write a built-in skill's instruction folders straight into each client's
  * skills directory. Built-in skills ship their SKILL.md inside this package, so
@@ -2445,11 +2524,21 @@ function installBuiltInInstructions(input) {
     const written = [];
     for (const agent of input.skillsAgents) {
         const root = builtInSkillsRootForAgent(agent, input.scope, input.baseDir);
+        const commandsRoot = builtInCommandsRootForAgent(agent, input.scope, input.baseDir);
         for (const bundle of bundles) {
             const dir = path.join(root, bundle.skillName);
             if (!input.dryRun)
                 writeSkillFolder(dir, bundle);
             written.push(dir);
+            const command = slashCommandForBuiltInSkill(bundle.skillName);
+            if (command) {
+                const commandPath = path.join(commandsRoot, `${bundle.skillName}.md`);
+                if (!input.dryRun) {
+                    fs.mkdirSync(path.dirname(commandPath), { recursive: true });
+                    fs.writeFileSync(commandPath, command, "utf-8");
+                }
+                written.push(commandPath);
+            }
         }
     }
     return written;
@@ -2508,6 +2597,10 @@ function skillSearchRoots(input) {
         if (hasClient("claude-code") || hasClient("claude-code-cli")) {
             add(path.join(input.baseDir, ".claude", "skills"), "project", "claude-code");
         }
+        if (hasClient("pi")) {
+            add(path.join(input.baseDir, ".agents", "skills"), "project", "pi");
+            add(path.join(input.baseDir, ".pi", "skills"), "project", "pi");
+        }
         if (includeAll)
             add(path.join(input.baseDir, "skills"), "project", "repo");
     }
@@ -2522,6 +2615,12 @@ function skillSearchRoots(input) {
         if (hasClient("claude-code") || hasClient("claude-code-cli")) {
             add(home ? path.join(home, ".claude", "skills") : undefined, "user", "claude-code");
         }
+        if (hasClient("pi")) {
+            const piHome = process.env.PI_CODING_AGENT_DIR ||
+                (home ? path.join(home, ".pi", "agent") : undefined);
+            add(home ? path.join(home, ".agents", "skills") : undefined, "user", "pi");
+            add(piHome ? path.join(piHome, "skills") : undefined, "user", "pi");
+        }
     }
     const seen = new Set();
     return roots.filter((entry) => {
@@ -2551,7 +2650,7 @@ function scopeFilterForStatus(parsed) {
         : ["project", "user"];
 }
 function clientFilterForStatus(parsed) {
-    return parsed.clientExplicit ? resolveClients(parsed.client) : [];
+    return parsed.clientExplicit ? resolveSkillsClientArg(parsed.client) : [];
 }
 function collectSkillInstallStates(parsed, options) {
     const appSkillIds = targetIdsForStatus(parsed);
@@ -2640,11 +2739,28 @@ function normalizeClientIds(values) {
     }
     return out;
 }
-function normalizeSkillsClientIds(values) {
+function isMcpClientId(value) {
+    return CLIENTS.includes(value);
+}
+function normalizeSkillInstructionClientIds(values) {
+    if (!Array.isArray(values))
+        return [];
     const seen = new Set();
     const out = [];
-    for (const client of normalizeClientIds(values)) {
-        const normalized = client === "claude-code-cli" ? "claude-code" : client;
+    for (const value of values) {
+        if (typeof value !== "string")
+            continue;
+        const id = value.toLowerCase();
+        let normalized = null;
+        if (id === "pi") {
+            normalized = "pi";
+        }
+        else if (CLIENTS.includes(id)) {
+            const client = id;
+            normalized = client === "claude-code-cli" ? "claude-code" : client;
+        }
+        if (!normalized)
+            continue;
         if (seen.has(normalized))
             continue;
         seen.add(normalized);
@@ -2652,22 +2768,37 @@ function normalizeSkillsClientIds(values) {
     }
     return out;
 }
-function resolveSkillsClientArg(client) {
-    return normalizeSkillsClientIds(resolveClients(client));
+function resolveSkillsClientArg(client, installsMcp = false) {
+    if (installsMcp)
+        return normalizeSkillInstructionClientIds(resolveClients(client));
+    const values = client.split(",").flatMap((raw) => {
+        const id = raw.trim().toLowerCase();
+        if (!id)
+            return [];
+        if (id === "all")
+            return SKILL_INSTRUCTION_CLIENTS;
+        if (id === "pi")
+            return ["pi"];
+        return resolveClients(id);
+    });
+    return normalizeSkillInstructionClientIds(values);
 }
 function skillsClients(installsMcp) {
     return installsMcp ? SKILLS_CLIENTS : SKILL_INSTRUCTION_CLIENTS;
 }
 function filterSkillsClients(clients, installsMcp) {
-    if (installsMcp)
-        return clients;
+    if (installsMcp) {
+        return clients.filter((client) => isMcpClientId(client) && SKILLS_CLIENTS.includes(client));
+    }
     return clients.filter((client) => SKILL_INSTRUCTION_CLIENTS.includes(client));
 }
 function clientPromptOptions(installsMcp) {
     return skillsClients(installsMcp).map((client) => ({
         value: client,
-        label: CLIENT_LABELS[client],
-        hint: installsMcp
+        label: installsMcp && isMcpClientId(client)
+            ? CLIENT_LABELS[client]
+            : SKILL_INSTRUCTION_CLIENT_LABELS[client],
+        hint: installsMcp && isMcpClientId(client)
             ? CLIENT_HINTS[client]
             : SKILL_INSTRUCTION_CLIENT_HINTS[client],
     }));
@@ -2702,6 +2833,13 @@ const BUILT_IN_SKILL_PROMPT_OPTIONS = [
     },
 ];
 const DEFAULT_SKILL_PROMPT_TARGETS = ["visual-plan", "visual-recap"];
+function hiddenBuiltInSkillTargets(options) {
+    return new Set((options.hiddenBuiltInSkillTargets ?? []).map((target) => target.trim().toLowerCase()));
+}
+function builtInSkillPromptOptions(options) {
+    const hidden = hiddenBuiltInSkillTargets(options);
+    return BUILT_IN_SKILL_PROMPT_OPTIONS.filter((entry) => !hidden.has(entry.value));
+}
 function publicSkillEntries(options) {
     if (options.catalogMode !== "all")
         return [];
@@ -2732,7 +2870,7 @@ function publicSkillPromptOptions(options) {
 }
 function skillPromptOptions(options = {}) {
     return [
-        ...BUILT_IN_SKILL_PROMPT_OPTIONS,
+        ...builtInSkillPromptOptions(options),
         ...publicSkillPromptOptions(options),
     ];
 }
@@ -2760,6 +2898,7 @@ function prVisualRecapWorkflowPath(baseDir) {
 function prVisualRecapWorkflowDisplayPath() {
     return path.join(".github", "workflows", "pr-visual-recap.yml");
 }
+const PR_VISUAL_RECAP_DOCS_URL = "https://www.agent-native.com/docs/pr-visual-recap";
 function prVisualRecapInstallCommand() {
     return "npx @agent-native/core@latest skills add visual-recap --with-github-action";
 }
@@ -2773,6 +2912,7 @@ async function promptForGithubAction(context) {
             "  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" +
+            `  Learn more: ${PR_VISUAL_RECAP_DOCS_URL}\n` +
             `  Writes ${context.workflowPath}; ${context.setupCommand} finishes the GitHub secrets.`,
         initialValue: false,
     });
@@ -2796,9 +2936,9 @@ 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" +
+        ? "Install the MCP connector for which clients?\n" +
             "  (space toggles, enter confirms; saved for next time)"
-        : "Install skill instructions for which local agents?\n" +
+        : "Where should the skill instructions be written?\n" +
             "  (space toggles, enter confirms; saved for next time)";
     const result = await clack.multiselect({
         message,
@@ -2810,7 +2950,7 @@ async function promptForClients(context) {
         clack.cancel("Cancelled.");
         return null;
     }
-    return normalizeClientIds(result);
+    return normalizeSkillInstructionClientIds(result);
 }
 async function promptForScope(context) {
     const clack = await import("@clack/prompts");
@@ -2843,7 +2983,7 @@ async function promptForPlanMode(context) {
         options: [
             {
                 value: "hosted",
-                label: "Hosted Plans, shareable links",
+                label: "Hosted Plans, shareable links (recommended)",
                 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.",
             },
             {
@@ -2917,15 +3057,17 @@ async function promptForSkills(context) {
 }
 async function resolveSkillsClients(parsed, options, installsMcp) {
     if (parsed.clientExplicit || !shouldPrompt(parsed, options)) {
-        const clients = filterSkillsClients(resolveSkillsClientArg(parsed.client), installsMcp);
+        const clients = filterSkillsClients(resolveSkillsClientArg(parsed.client, installsMcp), installsMcp);
         if (clients.length === 0) {
-            throw new Error("Local-file skill instructions only support Codex or Claude Code clients.");
+            throw new Error(installsMcp
+                ? "MCP setup supports Claude Code, Codex, Claude Cowork, Cursor, OpenCode, or GitHub Copilot / VS Code clients. Use --mode local-files or --no-mcp for Pi."
+                : "Skill instructions use shared .agents for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents, or Claude Code's native files.");
         }
         return clients;
     }
     const initialClients = skillsClients(installsMcp);
     const prompt = options.promptClients ?? promptForClients;
-    const selected = normalizeSkillsClientIds(await prompt({
+    const selected = normalizeSkillInstructionClientIds(await prompt({
         initialClients,
         options: clientPromptOptions(installsMcp),
         installsMcp,
@@ -2934,7 +3076,7 @@ async function resolveSkillsClients(parsed, options, installsMcp) {
         return null;
     if (!parsed.dryRun) {
         try {
-            writeConnectClientPreferences(selected);
+            writeConnectClientPreferences(selected.filter(isMcpClientId));
         }
         catch { }
     }
@@ -3225,6 +3367,8 @@ function skillsAgentsForClients(clients) {
         if (client === "claude-code" || client === "claude-code-cli") {
             agents.add("claude-code");
         }
+        if (client === "pi")
+            agents.add("pi");
     }
     return [...agents];
 }
@@ -3237,7 +3381,7 @@ function commandString(cmd, args) {
     return [cmd, ...args].map(shellArg).join(" ");
 }
 function clientArgForClients(clients) {
-    if (clients.length === CLIENTS.length)
+    if (clients.length === CLIENTS.length && clients.every(isMcpClientId))
         return "all";
     if (clients.length === 1)
         return clients[0];
@@ -3272,7 +3416,8 @@ function preserveMcpUrlAppPathOverride(target, input) {
     };
 }
 function dryRunInstallCommand(parsed, target) {
-    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
+    const clients = parsed.clients ??
+        resolveSkillsClientArg(parsed.client, targetInstallsMcp(target, parsed));
     const args = [
         "@agent-native/core@latest",
         "skills",
@@ -3410,6 +3555,7 @@ function agentNativeSkillsInstallArgs(parsed, target, clients, baseDir) {
         "--yes",
         "@agent-native/skills@latest",
         "add",
+        "--quiet",
         "--copy",
         target,
         "--client",
@@ -3457,12 +3603,12 @@ async function addPlainSkillRepo(parsed, options) {
     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.");
+        throw new Error("Plain skill repositories install through shared .agents for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents, or Claude Code's native files.");
     }
     const args = agentNativeSkillsInstallArgs(parsed, target, clients, options.baseDir);
     if (!parsed.dryRun) {
         const code = await (options.runCommand ?? runCommand)("npx", args, {
-            stdio: parsed.yes ? "silent" : "inherit",
+            stdio: "silent",
         });
         if (code !== 0)
             throw new Error(`npx @agent-native/skills@latest add exited with ${code}.`);
@@ -3622,7 +3768,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 ?? resolveSkillsClientArg(parsed.client);
+        const clients = (parsed.clients ?? resolveSkillsClientArg(parsed.client)).filter(isMcpClientId);
         const skillsAgents = skillsAgentsForClients(clients);
         if (parsed.dryRun) {
             const githubActionPath = parsed.withGithubAction && knownTarget === "visual-plans"
@@ -3677,7 +3823,11 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     if (parsed.mcpUrl) {
         installTarget = withMcpUrlOverride(installTarget, parsed.mcpUrl);
     }
-    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client);
+    const clients = parsed.clients ?? resolveSkillsClientArg(parsed.client, shouldRegisterMcp);
+    const mcpClients = clients.filter(isMcpClientId);
+    if (shouldRegisterMcp && mcpClients.length === 0) {
+        throw new Error("MCP setup supports Claude Code, Codex, Claude Cowork, Cursor, OpenCode, or GitHub Copilot / VS Code clients. Use --mode local-files or --no-mcp for Pi.");
+    }
     installTarget = preserveMcpUrlAppPathOverride(installTarget, parsed.mcpUrl);
     const skillsAgents = skillsAgentsForClients(clients);
     if (parsed.dryRun) {
@@ -3702,7 +3852,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 mcpUrl: knownTarget === "visual-plans" && planMode === "local-files"
                     ? ""
                     : installTarget.loaded.manifest.hosted.mcpUrl,
-                mcpClients: shouldRegisterMcp ? clients : [],
+                mcpClients: shouldRegisterMcp ? mcpClients : [],
                 dryRun: true,
                 commands: [dryRunInstallCommand(parsed, target)],
                 githubActionPath,
@@ -3720,12 +3870,12 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     let instructionsWritten;
     let connected = false;
     let connectCommand;
-    let registeredMcpClients = shouldRegisterMcp ? clients : [];
+    let registeredMcpClients = shouldRegisterMcp ? mcpClients : [];
     try {
         if (parsed.instructions) {
             if (skillsAgents.length === 0) {
                 if (!shouldRegisterMcp) {
-                    throw new Error("Skill instructions can only be installed for Codex or Claude Code clients. Use an MCP-capable client or omit --instructions-only.");
+                    throw new Error("Skill instructions use shared .agents for Codex, Pi, Cursor, OpenCode, Copilot, and similar agents, or Claude Code's native files. Use an MCP-capable client or omit --instructions-only.");
                 }
             }
             else if (knownTarget) {
@@ -3755,6 +3905,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                     "--yes",
                     "@agent-native/skills@latest",
                     "add",
+                    "--quiet",
                     instructionSource,
                     "--copy",
                     ...installTarget.skillNames.flatMap((skill) => ["--skill", skill]),
@@ -3784,7 +3935,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
             commands.push(`npx @agent-native/core@latest app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`);
             if (!parsed.dryRun) {
                 const ensureResult = await ensureAppSkill(installTarget.loaded, {
-                    clients,
+                    clients: mcpClients,
                     scope: parsed.scope,
                     baseDir: options.baseDir,
                     yes: parsed.yes || Boolean(knownTarget),
@@ -3800,16 +3951,16 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 // does not hit an OAuth wall on the first tool call. `--no-connect`
                 // opts out; non-interactive shells get the exact command to run.
                 if (parsed.connect) {
-                    const result = await connectAfterEnsure(installTarget, clients, parsed, options);
+                    const result = await connectAfterEnsure(installTarget, mcpClients, parsed, options);
                     connected = result.connected;
                     connectCommand = result.connectCommand || undefined;
                     if (connected)
-                        registeredMcpClients = clients;
+                        registeredMcpClients = mcpClients;
                     if (connectCommand)
                         commands.push(connectCommand);
                 }
                 else {
-                    const pendingClients = clients.filter((client) => !registeredMcpClients.includes(client));
+                    const pendingClients = mcpClients.filter((client) => !registeredMcpClients.includes(client));
                     if (pendingClients.length > 0) {
                         connectCommand = connectCommandFor(installTarget.loaded.manifest.hosted.url, pendingClients, parsed.scope);
                         commands.push(connectCommand);
@@ -3835,6 +3986,7 @@ export async function addAgentNativeSkill(parsed, options = {}) {
                 const choice = await prompt({
                     workflowPath: prVisualRecapWorkflowDisplayPath(),
                     setupCommand: prVisualRecapSetupCommand(),
+                    docsUrl: PR_VISUAL_RECAP_DOCS_URL,
                 });
                 if (choice === null) {
                     options.telemetry?.track("skills_cli cancelled", {
@@ -3892,8 +4044,11 @@ export async function addAgentNativeSkill(parsed, options = {}) {
     }
 }
 function listSkills(options = {}) {
+    const hidden = hiddenBuiltInSkillTargets(options);
     return [
-        ...Object.values(BUILT_IN_APP_SKILLS).map((entry) => ({
+        ...Object.values(BUILT_IN_APP_SKILLS)
+            .filter((entry) => !hidden.has(entry.skillName))
+            .map((entry) => ({
             id: entry.manifest.id,
             aliases: BUILT_IN_APP_SKILL_DISPLAY_ALIASES[entry.manifest.id] ?? [],
             name: entry.manifest.displayName,
@@ -3946,6 +4101,15 @@ function planModeSummary(mode) {
         return "Self-hosted/custom Plan app";
     return "Hosted Plans - shareable links and comments";
 }
+function skillInstructionAgentLabel(agent) {
+    if (agent === "codex")
+        return SKILL_INSTRUCTION_CLIENT_LABELS.codex;
+    if (agent === "claude-code")
+        return SKILL_INSTRUCTION_CLIENT_LABELS["claude-code"];
+    if (agent === "pi")
+        return SKILL_INSTRUCTION_CLIENT_LABELS.pi;
+    return agent;
+}
 function targetInstallsMcp(target, parsed) {
     if (!parsed.mcp)
         return false;
@@ -4223,6 +4387,7 @@ export async function runSkills(argv, options = {}) {
             const choice = await prompt({
                 workflowPath: prVisualRecapWorkflowDisplayPath(),
                 setupCommand: prVisualRecapSetupCommand(),
+                docsUrl: PR_VISUAL_RECAP_DOCS_URL,
             });
             if (choice === null) {
                 telemetry.track("skills_cli cancelled", { step: "github-action" });
@@ -4278,7 +4443,7 @@ export async function runSkills(argv, options = {}) {
         ];
         const localCommands = [
             ...new Set(results
-                .filter((result) => result.local)
+                .filter((result) => result.local && result.scriptPath)
                 .flatMap((result) => result.commands)),
         ];
         const planModes = [
@@ -4316,10 +4481,10 @@ export async function runSkills(argv, options = {}) {
         const clack = await import("@clack/prompts");
         const summary = [
             skillsAgents.length
-                ? `Skill instructions   ${skillsAgents.join(", ")}`
+                ? `Skill instructions   ${skillsAgents.map(skillInstructionAgentLabel).join(", ")}`
                 : "Skill instructions   skipped",
             mcpClients.length
-                ? `MCP config           ${mcpClients.join(", ")}`
+                ? `MCP config           ${mcpClients.map((client) => CLIENT_LABELS[client]).join(", ")}`
                 : "MCP config           not required",
             mcpUrls.length ? `MCP URL              ${mcpUrls.join(", ")}` : "",
             planModes.length