@agent-native/core 0.35.2 → 0.36.0

package/dist/cli/skills.js

@@ -15,13 +15,13 @@ const HELP = `agent-native skills
 
 Usage:
   agent-native skills list
-  agent-native skills add assets|design-exploration|visual-plans|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--yes] [--dry-run] [--json]
+  agent-native skills add assets|design-exploration|plans|visual-plan|ui-plan|visualize-plan|context-xray [--client codex|claude-code|claude-code-cli|cowork|all] [--scope user|project] [--mcp-url <url>] [--yes] [--dry-run] [--json]
   agent-native skills add <manifest-or-app-dir> [--client ...] [--yes]
 
 Examples:
   agent-native skills add assets
   agent-native skills add design-exploration
-  agent-native skills add visual-plans
+  agent-native skills add plans
   agent-native skills add context-xray --client all
   agent-native skills add assets --client claude-code
   agent-native skills add assets --mcp-url https://my-app.ngrok-free.dev
@@ -188,21 +188,50 @@ iteration, or a human-in-the-loop choice among design directions.
 const VISUAL_PLANS_SKILL_MD = `---
 name: visual-plans
 description: >-
-  Use Visual Plans for coding-agent work that needs an interactive HTML plan,
-  diagrams, wireframes, prototype options, annotations, implementation tasks,
-  feedback, and proof gates through the hosted Visual Plans MCP app.
+  Use Agent-Native Plans when coding-agent work needs an interactive HTML plan
+  document with diagrams, wireframes, mockups, prototypes, annotations, and
+  comments.
 metadata:
   visibility: exported
 ---
 
-# Visual Plans
+# Agent-Native Plans
 
-Use Visual Plans as HTML plan mode for coding work. The point is not to create a
-prettier Markdown plan. The point is to give the user something visual to react
-to before the agent edits code: diagrams, wireframes, option cards, clickable
-prototype sketches, assumptions, tasks, annotations, and proof gates.
+Agent-Native Plans is HTML plan mode for coding agents. Generate the kind of
+plan you would normally write in Markdown, but as a scannable HTML plan
+document with visual blocks mixed in: diagrams, wireframes, mockups, prototype
+options, tradeoff cards, file/symbol implementation maps, code previews, and
+annotation prompts. It is a plan document, not a marketing page.
 
-Text is the fallback layer. Default to visual artifacts.
+The goal is impatient review. The user should be able to react to visuals first
+and read prose only where it helps.
+
+Install with the Agent-Native CLI. It adds the skills and the MCP connector:
+
+\`\`\`bash
+npx @agent-native/core@latest skills add plans
+\`\`\`
+
+Then start typing \`/visual-plan\` for a fresh general plan, \`/ui-plan\` for a
+UI-first high-fidelity plan, or \`/visualize-plan\` to turn an existing Codex,
+Claude Code, Markdown, or pasted plan into a visual companion. The hosted MCP
+app opens inline where supported and falls back to a browser link everywhere
+else.
+
+## Slash Commands
+
+- \`/visual-plan\`: create a fresh rich HTML plan before implementation. Include
+  a docs-level plan, visual architecture/flow diagrams, detailed wireframes or
+  mockups when UI is involved, an implementation map with files/symbols/snippets,
+  tradeoffs, open questions, and clear feedback prompts.
+- \`/ui-plan\`: create a UI-first high-fidelity HTML plan before implementation.
+  Use an optional top pan/zoom wireframe or diagram canvas when visuals clarify
+  the flow, then continue as a refined Notion-like document with rich tabs,
+  comments/drawing prompts, code tabs, and agent handoff notes.
+- \`/visualize-plan\`: import an existing Codex, Claude Code, Markdown, or pasted
+  text plan and turn it into a visual companion. Preserve the plan's intent,
+  then add diagrams, wireframes, option cards, file/symbol maps, and annotation
+  prompts.
 
 ## When To Use
 
@@ -212,74 +241,317 @@ Create or update a visual plan when:
   diagrams, wireframes, mockups, prototype options, comments, or annotations;
 - work is multi-file, ambiguous, long-running, risky, or UI-heavy;
 - the user needs to react quickly to direction rather than read prose;
-- the task touches auth, billing, migrations, public APIs, tests, production
-  config, data, security, permissions, or deploy behavior;
-- you would otherwise proceed on a material assumption;
-- you are about to claim the work is complete and need proof gates checked.
+- architecture, data flow, UI direction, options, or open questions would be
+  clearer visually;
+- you need the user to react before implementation.
 
-Do not log every trivial inference. An assumption is material when changing it
-would affect user-visible behavior, data model, permissions, billing, public API
-shape, migrations/backfills/data loss, test strategy, architecture boundaries,
-deployment/configuration, file scope, or the definition of done.
+The companion \`visualize-plan\` skill is installed with this one. Use it when
+the user already has a Codex, Claude Code, Markdown, or pasted text plan and
+wants a visual companion instead of a fresh plan.
 
 ## Core Workflow
 
-1. Call \`create-visual-plan\` with the goal, source, repo path, and initial
-   plan nodes before implementation.
-2. Surface the returned Visual Plans link or inline MCP App. In CLI hosts, tell
-   the user to open the link and review the visual plan.
-3. Prefer diagrams, wireframes, UI mockups, option cards, and small interactive
-   prototypes over paragraphs.
-4. Call \`get-plan-feedback\` before editing, after review, after any long pause,
+1. Call \`create-visual-plan\` with the title, brief, source, repo path, and plan
+   sections before implementation.
+2. Put the best possible plan document in \`html\` when you can. It should feel
+   like a bespoke HTML version of a strong Markdown implementation plan, not a
+   dashboard or landing page.
+3. Surface the returned Plans link or inline MCP App. In CLI hosts, ask the user
+   to review the plan visually.
+4. Prefer diagrams, wireframes, UI mockups, option cards, implementation maps,
+   and small interactive prototypes over paragraphs.
+5. Call \`get-plan-feedback\` before editing, after review, after any long pause,
    and before the final response.
-5. If the user comments, accepts, rejects, corrects, or requests proof, consume
-   the structured feedback and update the implementation plan accordingly.
-6. If new facts require a change after approval, create an amendment or
-   deviation with \`update-visual-plan\` instead of drifting silently.
-7. Attach command/test/log/diff/screenshot/design artifacts with
-   \`record-plan-evidence\`. Agent claims are not proof.
-8. Export an HTML/JSON/Markdown receipt with \`export-visual-plan\` when the
+6. Incorporate comments/corrections with \`update-visual-plan\`; update the HTML
+   document when feedback changes the direction.
+7. Export an HTML/JSON/Markdown receipt with \`export-visual-plan\` when the
    user wants a shareable summary.
 
 ## Visual Defaults
 
-- UI work gets wireframes or prototype options before coding.
+- Use implementation-plan structure first: objective, scope/non-goals, proposed
+  approach, phases or steps, files/symbols/snippets, risks, open questions, and
+  validation.
+- UI work gets detailed wireframes, mockups, or prototype options before coding.
+- Use \`/ui-plan\` when UI direction is the center of the work. \`/visual-plan\`
+  stays the general plan command for architecture, backend, refactors, and
+  mixed implementation planning.
+- Wireframes should be concrete enough to critique: layout regions, controls,
+  states, empty/loading/error paths, review affordances, and copy placeholders.
 - Backend/refactor work gets architecture and data-flow diagrams.
 - Complex tradeoffs get two or three option cards with consequences.
-- Assumptions are shown as reviewable visual callouts, not hidden prose.
-- Proof gates stay compact: what must pass, current evidence, and missing proof.
-- Long prose is collapsed behind the visual plan.
+- Open questions are surfaced as visual callouts, not buried in paragraphs.
+- Long prose is split into readable document sections with clear headings.
+- Visuals should be review aids, not decoration. Avoid decorative hero art,
+  gradient/hero backgrounds, brand/logo chrome, nav bars, slogans, fluffy value
+  props, huge landing-page H1s, or marketing-style cards unless the user
+  explicitly asks.
+- Implementation plans include a file map: file path, symbols/components to
+  touch, reason for the change, risk/coordination notes when relevant, and short
+  syntax-highlighted snippets for the code shape the agent expects to modify.
+- File previews should be concise and reviewable. Do not paste entire large
+  files; show the key region, public API, component boundary, schema, action, or
+  selector that matters for review.
+- Include README-like detail when helpful: command names, tool behavior,
+  install flow, MCP/link fallback, data shape, and what is in or out of scope.
+- Comments, corrections, replacements, and annotations should feel
+  plannotator-style: fast to mark up, structured enough for the agent to
+  consume, and easy to share when the user chooses.
 
 ## Tool Guidance
 
-- \`create-visual-plan\`: start one visual plan per agent task/run.
-- \`update-visual-plan\`: bulk add/update plan nodes, options, assumptions,
-  decisions, tasks, risks, deviations, annotations, and proof gates.
-- \`get-visual-plan\` and \`get-plan-review-queue\`: read current plan state.
+- \`create-visual-plan\`: start one HTML plan per agent task/run.
+- \`create-ui-plan\`: start a UI-first plan with high-fidelity screen/state tabs.
+- \`visualize-plan\`: create a visual companion from an existing text plan.
+- \`update-visual-plan\`: revise the plan document, sections, status, or comments.
+- \`get-visual-plan\`: read the current plan document and annotations.
 - \`get-plan-feedback\`: read unconsumed human feedback. Use it frequently.
-- \`record-plan-progress\`: update phase/status and mark feedback consumed only
-  after you incorporated it.
-- \`record-plan-evidence\`: attach artifacts and provenance. Use high trust for
-  captured commands/tests/CI, human_confirmed for explicit human confirmation,
-  and low trust for agent-only statements.
-- \`analyze-visual-plan\`: import pasted Markdown/text and create possible
-  visual plan nodes. Treat detections as possible, not authoritative.
+- \`export-visual-plan\`: export HTML, Markdown fallback, and structured JSON.
+
+## HTML Guidance
+
+- Prefer semantic HTML with scoped CSS inside the document.
+- Match Agent-Native's dark, restrained theme unless the user asks otherwise.
+- Keep the first viewport legible and plan-like: title, brief, concise scope,
+  and a useful diagram/checklist/table when it helps.
+- Use tabs, accordions, or small interactions only when they make review faster.
+- Do not paste huge HTML into chat. Store it in Plans and surface the MCP app or
+  link.
 
 ## Guardrails
 
 - Keep it simple. Do not build a ten-tab dashboard unless the user asks.
-- Before high-risk actions, create a blocking review item or ask the user
-  directly.
-- Never modify tests merely to make implementation pass unless the visual plan
-  explicitly approves test expectation changes.
-- If proof is missing, say so. Do not call the task complete just because code
-  was changed.
 - Do not hand-roll MCP HTTP requests with curl. Use host-exposed tools after
   restart/reload, or use the returned browser/deep-link fallback.
 - Hosted default: connect
-  \`https://plans.agent-native.com/_agent-native/mcp\`. Do not put shared
+  \`https://plan.agent-native.com/_agent-native/mcp\`. Do not put shared
   secrets in skill files.
 `;
+const UI_PLAN_SKILL_MD = `---
+name: ui-plan
+description: >-
+  Use Agent-Native Plans for UI-first planning with an optional top pan/zoom
+  wireframe canvas, a refined Notion-like document, rich tabs, diagrams,
+  comments, drawing, and agent handoff.
+metadata:
+  visibility: exported
+---
+
+# UI Plan
+
+Use \`/ui-plan\` when the task is primarily about product UI, user flows,
+interaction states, component layout, responsive behavior, or visual direction.
+This is a specialized Agent-Native Plans workflow: the reviewable UI comes
+first, and implementation details come after the user has something concrete to
+react to.
+
+\`/visual-plan\` remains the general rich planning command for architecture,
+backend, refactors, migrations, and mixed work. Use \`/visualize-plan\` when a
+text plan already exists and should become an HTML companion.
+
+## UI-First Workflow
+
+1. Call \`create-ui-plan\` with a UI-specific title, brief, source, repo path,
+   and a complete bespoke \`html\` document whenever possible.
+2. When the plan has meaningful UI flows, screens, or diagrams, make the top
+   of the document a bounded pan/zoom sketch canvas with the key artboards,
+   connectors, margin notes, and commentable visual anchors.
+3. Continue below the canvas as a restrained, Notion-like interactive document:
+   clear prose, horizontal state tabs, inline wireframes, sketchy diagrams,
+   tables, vertical code tabs, and concise implementation notes.
+4. Skip the top canvas when wireframes or diagrams would not clarify the work;
+   in that case, keep the plan as a clean rich document.
+5. Put files, symbols, data/actions, migrations, risks, and validation lower in
+   the document after the visual review area.
+6. Call \`get-plan-feedback\` before implementation, after review, after a long
+   pause, and before the final response. Apply changes with
+   \`update-visual-plan\`.
+
+## Mockup Quality Bar
+
+- Build high-fidelity screen sections with realistic spacing, controls,
+  hierarchy, text, and state-specific content. Avoid vague gray boxes.
+- Show the actual workflow the user will use: navigation, toolbar actions,
+  forms, dialogs, empty states, error recovery, loading affordances, and
+  confirmation/success states.
+- Include desktop and mobile/responsive states when layout decisions could
+  change. Put them in tabs or adjacent panels rather than burying them in prose.
+- Use concrete labels and copy placeholders that expose content length,
+  truncation, disabled states, and destructive actions.
+- Make state tabs span the plan content width. Small cards are fine for repeated
+  items, but the primary UI preview should not be trapped in a tiny thumbnail.
+- Keep visuals review-focused, not decorative. Do not make a marketing page,
+  hero section, brand deck, or abstract mood board unless the user asks.
+
+## State Tabs
+
+When showing multiple UI states, use the Plans tab attributes so the iframe
+runtime wires up the interaction:
+
+- Put \`data-plan-tabs\` on the tab group.
+- Put \`data-tab-target\` on each tab button.
+- Put matching \`data-tab-panel\` values on panels.
+
+Good state tab sets include:
+
+- \`Default\`, \`Loading\`, \`Empty\`, \`Error\`
+- \`List\`, \`Detail\`, \`Edit\`, \`Confirm\`
+- \`Desktop\`, \`Tablet\`, \`Mobile\`
+- \`Owner\`, \`Reviewer\`, \`Signed out\`
+
+## UI Flow Document
+
+Generated \`/ui-plan\` documents use one default shape: an optional Figma-style
+pan/zoom visual preface followed by a refined Notion-like document. There is no
+mode boolean. Provide \`states\` and \`components\` when the top canvas will help
+the reviewer understand the flow; omit them when the plan should be
+document-only. You may pass \`sketchiness\` from \`0\` to \`100\`; omit it for the
+default hand-drawn strength.
+
+The document below the canvas should still include the same planning substance:
+screen states, component notes, implementation map, review prompts, comments,
+drawing-friendly space, and agent handoff. Treat it like a designer handed over
+a Figma file plus a crisp product spec: the reviewer should understand the UI
+flow from a bird's-eye view, then keep scrolling into a clean interactive
+document with notes explaining how the screens work together.
+
+## Comments, Drawing, And Handoff
+
+- Add visible annotation prompts beside the mockups: "Comment on layout",
+  "Circle unclear copy", "Mark missing state", or "Pick this option".
+- Leave enough whitespace around key UI regions for drawing and callouts.
+- Label important regions so comments can reference them without ambiguity.
+- Include an "Agent Handoff" section after the mockups that summarizes the
+  chosen UI direction, unresolved visual questions, and feedback that must be
+  read before code changes.
+- Never claim feedback has been applied until \`get-plan-feedback\` or the user
+  has supplied the feedback in chat.
+
+## Implementation Details Lower Down
+
+After the visual canvas and document review blocks, include a concise
+implementation section:
+
+- file paths and symbols/components to touch;
+- data/actions/hooks/routes needed for the UI;
+- state ownership, optimistic updates, and sync expectations;
+- accessibility, responsive, and keyboard considerations;
+- test and verification plan;
+- short code-shape snippets only where they clarify the implementation.
+
+Do not paste whole files or let implementation prose crowd out the mockups.
+The purpose of \`/ui-plan\` is to get visual direction approved before the agent
+starts editing.
+
+## Tool Guidance
+
+- \`create-ui-plan\`: create the UI-first HTML plan.
+- \`update-visual-plan\`: revise mockups, state tabs, comments, or handoff notes.
+- \`get-visual-plan\`: inspect the current plan and annotations.
+- \`get-plan-feedback\`: read unconsumed reviewer comments before coding.
+- \`export-visual-plan\`: export a review receipt when needed.
+
+Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`.
+`;
+const VISUALIZE_PLAN_SKILL_MD = `---
+name: visualize-plan
+description: >-
+  Convert an existing Codex, Claude Code, Markdown, or pasted plan into a
+  Agent-Native Plans HTML companion with diagrams, wireframes, annotations, and
+  feedback.
+metadata:
+  visibility: exported
+---
+
+# Visualize Plan
+
+Use this as the visual companion for an existing text plan. The native Codex or
+Claude Code plan can stay exactly where it is; Agent-Native Plans turns it into
+an interactive HTML review surface with diagrams, wireframes, prototype options,
+annotations, questions, and feedback.
+
+This is for impatient review. Default to things the user can scan and react to.
+It should still read like a plan, not a marketing page.
+
+Install with the Agent-Native CLI if Plans is not already available:
+
+\`\`\`bash
+npx @agent-native/core@latest skills add plans
+\`\`\`
+
+That installs \`/visual-plan\`, \`/ui-plan\`, and \`/visualize-plan\` plus the
+MCP connector.
+
+## When To Use
+
+Use \`visualize-plan\` when:
+
+- the user has an existing Codex, Claude Code, Markdown, or pasted plan;
+- the user asks to visualize, annotate, plannotate, mock up, diagram, or make a
+  plan easier to review;
+- the plan is long enough that the user may not read it closely;
+- UI direction, architecture, data flow, risky assumptions, or open questions
+  would be clearer visually;
+- the user wants feedback on wireframes, design/prototype options, diagrams, or
+  tradeoffs before implementation.
+
+If there is no existing plan text available, ask for it, use \`visual-plans\`
+to create a fresh general plan, or use \`ui-plan\` when the work is UI-heavy and
+should start with high-fidelity state mockups.
+
+## Workflow
+
+1. Gather the existing plan text from the user's paste, a referenced file, or
+   the recent agent-visible plan. Do not invent a source plan.
+2. Call \`visualize-plan\` with \`planText\`, \`title\`, \`goal\`, \`source\`,
+   and \`repoPath\` when available.
+3. Surface the returned Plans link or inline MCP App.
+4. Enrich the imported plan with \`update-visual-plan\` when helpful:
+   - diagrams for architecture, data flow, state machines, or dependencies;
+   - detailed wireframes/mockups for user-visible UI changes, including layout,
+     controls, states, empty/loading/error paths, and copy placeholders;
+   - two or three option cards when there are real tradeoffs;
+   - small prototype sketches for interactions, states, or animation choices;
+   - reviewable assumptions and open questions;
+5. Ask the user to react in the visual plan. Then call \`get-plan-feedback\`
+   before implementing, after review, and before final response.
+6. Treat the imported text as source material. Structured Plans state is
+   canonical for feedback, assumptions, and decisions.
+
+If there is no existing plan text and the work is UI-heavy, use \`/ui-plan\`
+instead so full-width state mockups, comments/drawing affordances, and agent
+handoff come before file implementation details.
+
+## Visual Defaults
+
+- Keep the first screen simple and plan-like: title, brief, concise scope, and
+  one useful diagram/checklist/table when it helps.
+- Prefer one strong diagram or wireframe over a wall of sections.
+- Preserve the source plan's implementation substance: phases or steps,
+  files/symbols/snippets, risks, open questions, and validation.
+- Hide long prose behind disclosure controls or source references when it helps
+  review speed.
+- Add README-like detail when the source is too terse: slash commands, tool
+  behavior, install flow, MCP/link fallback, data shape, and scope.
+- Avoid decorative hero art, gradient/hero backgrounds, logos, nav bars,
+  slogans, fluffy value props, huge landing-page H1s, and marketing-style cards
+  unless the user explicitly asks.
+- Visuals should be review aids, not decoration.
+- Label inferred items as possible, not confirmed.
+- Ask for feedback with targeted prompts: "Which option?", "Is this flow
+  right?", "What assumption is wrong?", "What should change?"
+- Preserve native-agent momentum: this companion should make the plan easier to
+  approve or revise, not force a giant planning ceremony.
+
+## Guardrails
+
+- Do not replace a native plan unless the user asks. Build beside it.
+- Do not pretend the companion has feedback until \`get-plan-feedback\` returns
+  it or the user pastes it back.
+- Do not use visual polish as a substitute for clarity. The point is review.
+- Do not hand-roll MCP HTTP requests with curl. Use host-exposed tools after
+  restart/reload, or use the returned browser/deep-link fallback.
+`;
 const BUILT_IN_APP_SKILLS = {
     assets: {
         skillName: "assets",
@@ -369,19 +641,23 @@ const BUILT_IN_APP_SKILLS = {
     },
     "visual-plans": {
         skillName: "visual-plans",
+        extraSkills: {
+            "ui-plan": UI_PLAN_SKILL_MD,
+            "visualize-plan": VISUALIZE_PLAN_SKILL_MD,
+        },
         manifest: normalizeAppSkillManifest({
             schemaVersion: 1,
             id: "visual-plans",
-            displayName: "Visual Plans",
-            description: "Review coding-agent plans as interactive HTML with diagrams, wireframes, annotations, and proof gates.",
+            displayName: "Agent-Native Plans",
+            description: "Generate and review coding-agent plans as interactive HTML with diagrams, wireframes, prototypes, annotations, and feedback.",
             hosted: {
-                url: "https://plans.agent-native.com",
-                mcpUrl: "https://plans.agent-native.com/_agent-native/mcp",
+                url: "https://plan.agent-native.com",
+                mcpUrl: "https://plan.agent-native.com/_agent-native/mcp",
             },
-            mcp: { serverName: "agent-native-visual-plans" },
+            mcp: { serverName: "agent-native-plans" },
             auth: {
                 mode: "oauth",
-                setup: "Authenticate with the Visual Plans MCP connector in the host app. No shared secrets are stored in skill files.",
+                setup: "Install with the Agent-Native CLI to add /visual-plan, /ui-plan, and /visualize-plan skills plus the Plans MCP connector. Authenticate only for hosted/account-backed sharing.",
             },
             surfaces: [
                 {
@@ -389,6 +665,17 @@ const BUILT_IN_APP_SKILLS = {
                     action: "create-visual-plan",
                     path: "/plans",
                 },
+                {
+                    id: "ui-plan",
+                    action: "create-ui-plan",
+                    path: "/plans",
+                    description: "Create a UI-first Agent-Native plan with an optional top pan/zoom wireframe canvas and a refined rich document below.",
+                },
+                {
+                    id: "visualize-plan",
+                    action: "visualize-plan",
+                    path: "/plans",
+                },
             ],
             skills: [
                 {
@@ -396,6 +683,16 @@ const BUILT_IN_APP_SKILLS = {
                     visibility: "exported",
                     exportAs: "visual-plans",
                 },
+                {
+                    path: "skills/ui-plan",
+                    visibility: "exported",
+                    exportAs: "ui-plan",
+                },
+                {
+                    path: "skills/visualize-plan",
+                    visibility: "exported",
+                    exportAs: "visualize-plan",
+                },
             ],
             hostAdapters: [
                 "codex-plugin",
@@ -459,18 +756,16 @@ const BUILT_IN_APP_SKILL_ALIASES = {
     "agent-native-design-exploration": "design",
     "visual-plans": "visual-plans",
     "visual-plan": "visual-plans",
+    "ui-plan": "visual-plans",
+    "ui-plans": "visual-plans",
+    "visualize-plan": "visual-plans",
+    "visualize-plans": "visual-plans",
     plans: "visual-plans",
     plan: "visual-plans",
     "html-plan": "visual-plans",
     "plan-mode": "visual-plans",
     plannotate: "visual-plans",
     plannotator: "visual-plans",
-    contracts: "visual-plans",
-    contract: "visual-plans",
-    proof: "visual-plans",
-    "proof-check": "visual-plans",
-    "assumption-review": "visual-plans",
-    "agent-native-contracts": "visual-plans",
     "agent-native-visual-plans": "visual-plans",
     "context-xray": "context-xray",
     "local-context-xray": "context-xray",
@@ -488,10 +783,10 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
     ],
     "visual-plans": [
         "plans",
+        "ui-plan",
+        "visualize-plan",
         "html-plan",
         "plannotate",
-        "contracts",
-        "proof-check",
     ],
     "context-xray": ["xray", "context-window", "context-usage"],
 };
@@ -519,6 +814,12 @@ function isKnownSkill(value) {
 function isLocalOnlyBuiltInSkill(entry) {
     return Boolean(entry && "localOnly" in entry && entry.localOnly);
 }
+function builtInExtraSkills(entry) {
+    return "extraSkills" in entry && entry.extraSkills ? entry.extraSkills : {};
+}
+function builtInSkillNames(entry) {
+    return [entry.skillName, ...Object.keys(builtInExtraSkills(entry))];
+}
 function normalizeClientIds(values) {
     if (!Array.isArray(values))
         return [];
@@ -707,6 +1008,7 @@ function loadSkillTarget(target) {
     const knownTarget = normalizeKnownSkillTarget(target);
     if (knownTarget) {
         const builtIn = BUILT_IN_APP_SKILLS[knownTarget];
+        const skillNames = builtInSkillNames(builtIn);
         return {
             id: builtIn.manifest.id,
             displayName: builtIn.manifest.displayName,
@@ -715,11 +1017,17 @@ function loadSkillTarget(target) {
                 file: `<built-in:${builtIn.manifest.id}>`,
                 dir: process.cwd(),
             },
-            skillNames: [builtIn.skillName],
+            skillNames,
             materializeInstructions(outDir) {
-                const skillDir = path.join(outDir, "skills", builtIn.skillName);
-                fs.mkdirSync(skillDir, { recursive: true });
-                fs.writeFileSync(path.join(skillDir, "SKILL.md"), builtIn.skillMarkdown, "utf-8");
+                const skills = {
+                    [builtIn.skillName]: builtIn.skillMarkdown,
+                    ...builtInExtraSkills(builtIn),
+                };
+                for (const [skillName, skillMarkdown] of Object.entries(skills)) {
+                    const skillDir = path.join(outDir, "skills", skillName);
+                    fs.mkdirSync(skillDir, { recursive: true });
+                    fs.writeFileSync(path.join(skillDir, "SKILL.md"), skillMarkdown, "utf-8");
+                }
                 return outDir;
             },
         };