@agent-native/core 0.51.9 → 0.51.11

package/dist/cli/skills.js

@@ -1889,6 +1889,10 @@ A few recap-specific authoring rules the registry table cannot encode:
   shared optional \`summary\` / \`editable\` envelope; give a block a heading by
   placing a \`rich-text\` block with a Markdown \`###\` heading directly above it
   (blocks no longer take a \`title\`).
+- Every capitalized block component must be self-closing (\`<RichText ... />\`) or
+  explicitly closed around children (\`<RichText ...>...</RichText>\`). Never
+  leave a bare opening tag like \`<RichText ...>\` in a paragraph; MDX treats it
+  as unclosed JSX and import fails before the recap can render.
 - \`Endpoint\`: prose \`description\` is the MDX **children** (body between the
   tags), not an attribute; for a WebSocket upgrade use \`method="GET"\`. Each
   request/response \`example\` is a JSON **string** (the renderer parses it into
@@ -2635,12 +2639,19 @@ function clientPromptOptions() {
         hint: 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",
@@ -2651,9 +2662,58 @@ 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 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");
@@ -2783,6 +2843,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({
@@ -2844,12 +2916,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", {
@@ -2857,22 +2983,12 @@ async function resolveSkillTargets(parsed, options) {
         available: promptOptions.map((option) => option.value).join(","),
     });
     const selected = await prompt({
-        initialTargets: ["visual-plan", "visual-recap"],
+        initialTargets: DEFAULT_SKILL_PROMPT_TARGETS,
         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];
@@ -2928,6 +3044,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];
         }
@@ -2938,6 +3062,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)
@@ -2954,6 +3080,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")
@@ -3230,6 +3368,12 @@ function agentNativeSkillsInstallArgs(parsed, target, clients) {
         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 ?? []) {
@@ -3241,6 +3385,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) {
@@ -3248,11 +3394,12 @@ 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 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.");
     }
@@ -3265,15 +3412,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: [],
@@ -3356,6 +3505,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"))
@@ -3651,15 +3808,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 {
@@ -3692,6 +3863,39 @@ function planModeSummary(mode) {
         return "Self-hosted/custom Plan app";
     return "Hosted Plans - shareable links and comments";
 }
+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) : [];
@@ -3748,6 +3952,9 @@ function readCliVersion() {
 }
 export async function runSkills(argv, options = {}) {
     const parsed = parseSkillsArgs(argv);
+    if (parsed.baseDir) {
+        options = { ...options, baseDir: path.resolve(parsed.baseDir) };
+    }
     const log = parsed.printJson
         ? undefined
         : (message) => process.stdout.write(`${message}\n`);
@@ -3760,6 +3967,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
@@ -3776,7 +3984,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(","),
@@ -3811,10 +4019,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.");
         }
@@ -3874,6 +4083,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` +
@@ -3884,7 +4107,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)) &&
@@ -4028,6 +4251,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