@compilr-dev/cli 0.8.10 → 0.9.1

package/CHANGELOG.md

@@ -12,6 +12,41 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-09-20
+
+The published package had fallen a long way behind `main`: `0.8.10` on npm still
+declared `@compilr-dev/sdk ^0.18.11`. This release carries twenty commits of work that
+had been committed but never shipped.
+
+### Changed
+- **Skills and macros are now separate things, and the CLI says so.** A *macro* is a
+  shipped prompt you type (`/design`, `/prd`); a *skill* is a `SKILL.md` folder a model
+  chooses for itself. Every symbol, message and screen that conflated them has been
+  renamed — including the eight "skill not found" errors, which now say macro.
+- **`/skill` lost its Built-in tab.** It listed macros inside a manager for skills.
+  Forking a built-in moved to where creating begins: `n` → *from a command*, with the
+  same searchable list. Bindings are unchanged and still editable.
+- **`Space` in `/skill` now writes the two Anthropic fields** (`disable-model-invocation`,
+  `user-invocable`) instead of a non-standard `enabled` key, and removes `enabled` from
+  any file it touches. A skill shelved in the Desktop app previously read as *live* in
+  the terminal — the list and the resolver disagreed in front of you.
+- **Project editing gained five fields** — docs path, language, framework, package
+  manager and runtime — matching what the Desktop app edits. Both hosts now write through
+  one shared mapping.
+- **An emptied field clears the value.** It previously meant "leave alone", so a git
+  remote could be set from the CLI but never removed.
+
+### Added
+- Each agent is given the skills it may choose, rather than all of them.
+- An agent is warned when a macro needs tools it does not have.
+
+### Fixed
+- The seven wrapped macros compose their message through the SDK, so the CLI and the
+  Desktop app send a command the same way instead of drifting apart.
+
+---
+
+
 ## [0.6.2] — 2026-04-25
 
 ### Fixed

package/dist/agent.d.ts

@@ -8,6 +8,7 @@
 import { Agent } from '@compilr-dev/sdk';
 import type { AgentEvent, Tool, GuardrailTriggeredHandler } from '@compilr-dev/sdk';
 import type { PermissionHandler } from '@compilr-dev/agents';
+import type { CustomSkill } from '@compilr-dev/sdk';
 import type { EpisodeRecorder } from './episodes/index.js';
 /**
  * Supported providers (re-exported from models/provider-types)
@@ -96,6 +97,14 @@ export interface AgentOptions {
     toolFilter?: string[];
     /** MCP tools from external MCP servers */
     mcpTools?: Tool[];
+    /**
+     * Skills this agent may CHOOSE, already filtered for eligibility by the caller.
+     *
+     * Distinct from the slash commands a user types: the SDK turns these into an "Available
+     * Skills" catalogue (descriptions only) plus a `load_skill` tool. Filtering happens at the
+     * call site because only it knows which agent is being built — see `resolveSkillsForTeamAgent`.
+     */
+    skills?: CustomSkill[];
     /** Episode recorder for work history tracking */
     episodeRecorder?: EpisodeRecorder;
 }

package/dist/agent.js

@@ -310,6 +310,7 @@ export function createAgent(options = {}) {
         // so the agent calls into the CLI's existing terminal overlays
         // (showAskUserOverlayV2 / showAskUserSimpleOverlayV2) plus the
         // background-agent question-routing path.
+        skills: options.skills,
         capabilities: (options.enableMetaTools && !options.minimal && !options.noTools)
             ? {
                 enabled: true,

package/dist/commands-v2/handlers/project.js

@@ -10,14 +10,14 @@ import { setCurrentProject, getCurrentProject } from '../../tools/project-db.js'
 import { getSkillPrompt } from '../../repl-helpers.js';
 import { getModelTier, modelMeetsTier } from '../../utils/model-tiers.js';
 import { getCurrentProjectIdForTracking, handleProjectSwitch, saveCurrentTeam } from './session.js';
-import { loadCapabilitiesForSkill } from '../../multi-agent/capability-loader.js';
-import { normalizeRoleName } from '@compilr-dev/sdk';
+import { loadCapabilitiesForMacro } from '../../multi-agent/capability-loader.js';
+import { normalizeRoleName, buildMacroInvocation } from '@compilr-dev/sdk';
 /**
  * Load capabilities for a skill and warn about forbidden packs.
  * Called before queuing a skill-driven agent message.
  */
-function loadSkillCapabilities(skillName, ctx) {
-    const result = loadCapabilitiesForSkill(skillName);
+function loadMacroCapabilities(skillName, ctx) {
+    const result = loadCapabilitiesForMacro(skillName);
     if (!result)
         return; // No capability loading active or no requirements
     if (result.forbidden.length > 0) {
@@ -417,37 +417,28 @@ export const designCommand = {
             }
         }
         // Load capabilities for the design skill
-        loadSkillCapabilities('design', ctx);
+        loadMacroCapabilities('design', ctx);
         // Get design skill prompt
         const designPrompt = getSkillPrompt('design');
         if (!designPrompt) {
-            ctx.ui.print({ type: 'error', message: 'Design skill not found.' });
+            ctx.ui.print({ type: 'error', message: 'Design macro not found.' });
             return true;
         }
-        // Build full message for agent with project context
-        const fullMessage = `I want to design my project and create the backlog.
-
-## PROJECT CONTEXT (IMPORTANT)
-- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
-- This is a NEW project being designed from scratch
-- Do NOT scan the filesystem - the current directory is NOT the project
-- Do NOT use detect_project, glob, read_file, or ls tools
-- Focus ONLY on gathering requirements via ask_user questions
-
-## DOCUMENT STORAGE (CRITICAL)
-Save all documents and backlog items using the database - do NOT write files directly.
-- For backlog items: \`workitem_add({ type: "feature", title: "...", description: "...", priority: "high" })\`
-- For documents: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
-- The database is the source of truth for all project documents
-- Do NOT use write_file or edit tools for documentation
-
-${designPrompt}
-
-Please start by using todo_write to track the design phases, then begin with Phase 1: Vision. Use the ask_user tool to gather information efficiently.`;
+        /*
+          ⚠️ COMPOSED IN THE SDK, NOT HERE. This block used to be ~20 lines of project context written
+          inline — and Desktop's /design sent the macro prompt with none of it, so the same command
+          produced an agent that interviewed you and filled the backlog here, and one that went
+          looking for source files there. The text is unchanged; it just lives where both hosts reach
+          it. Byte-identical output is asserted in the SDK's macro-invocation tests.
+        */
+        const invocation = buildMacroInvocation('design', designPrompt, {
+            project: { id: currentProject.id, name: currentProject.name },
+        });
         // Queue message for agent
         ctx.queueAgentMessage({
-            message: fullMessage,
-            displayMessage: 'Start the design process for my project.',
+            macro: 'design',
+            message: invocation.message,
+            displayMessage: invocation.displayMessage,
         });
         return true;
     },
@@ -468,36 +459,20 @@ export const sketchCommand = {
             return Promise.resolve(true);
         }
         // Load capabilities for the sketch skill
-        loadSkillCapabilities('sketch', ctx);
+        loadMacroCapabilities('sketch', ctx);
         // Get sketch skill prompt
         const sketchPrompt = getSkillPrompt('sketch');
         if (!sketchPrompt) {
-            ctx.ui.print({ type: 'error', message: 'Sketch skill not found.' });
+            ctx.ui.print({ type: 'error', message: 'Sketch macro not found.' });
             return Promise.resolve(true);
         }
-        // Build full message for agent with project context
-        const fullMessage = `I want to quickly outline my project.
-
-## PROJECT CONTEXT (IMPORTANT)
-- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
-- This is a NEW project being designed from scratch
-- Do NOT scan the filesystem - the current directory is NOT the project
-- Do NOT use detect_project, glob, read_file, or ls tools
-- Focus ONLY on gathering requirements via ask_user questions
-
-## DOCUMENT STORAGE (CRITICAL)
-Save all documents and backlog items using the database - do NOT write files directly.
-- For backlog items: \`workitem_add({ type: "feature", title: "...", description: "..." })\`
-- For documents: \`project_document_add({ doc_type: "prd", title: "...", content: "..." })\`
-- Do NOT use write_file or edit tools for documentation
-
-${sketchPrompt}
-
-Please start by asking me about the type of application I'm building using the ask_user_simple tool.`;
-        // Queue message for agent
+        const invocation = buildMacroInvocation('sketch', sketchPrompt, {
+            project: { id: currentProject.id, name: currentProject.name },
+        });
         ctx.queueAgentMessage({
-            message: fullMessage,
-            displayMessage: 'Quick project outline.',
+            macro: 'sketch',
+            message: invocation.message,
+            displayMessage: invocation.displayMessage,
         });
         return Promise.resolve(true);
     },
@@ -561,40 +536,20 @@ export const refineCommand = {
         }
         // Get appropriate skill prompt and load capabilities
         const skillName = isFocusedRefine ? 'refine-item' : 'refine';
-        loadSkillCapabilities(skillName, ctx);
+        loadMacroCapabilities(skillName, ctx);
         const refinePrompt = getSkillPrompt(skillName);
         if (!refinePrompt) {
-            ctx.ui.print({ type: 'error', message: `${skillName} skill not found.` });
+            ctx.ui.print({ type: 'error', message: `${skillName} macro not found.` });
             return true;
         }
-        // Build message based on mode
-        const userIntent = isFocusedRefine
-            ? `I want to refine backlog item ${itemId}.`
-            : 'I want to refine my project requirements.';
-        const agentInstructions = isFocusedRefine
-            ? `Please use workitem_query to find item "${itemId}", then guide me through refining it using workitem_update.`
-            : 'Please start by using workitem_query with limit:10 to get an overview, then ask me what I\'d like to focus on using ask_user_simple.';
-        const fullMessage = `${userIntent}
-
-## PROJECT CONTEXT (IMPORTANT)
-- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
-- Do NOT scan the filesystem - the current directory is NOT the project
-- Do NOT use detect_project, glob, read_file, or ls tools
-- Use ONLY database tools to access project data
-
-## DOCUMENT STORAGE (CRITICAL)
-Use database tools for all updates - do NOT write files directly.
-- Use \`workitem_query\` to read items
-- Use \`workitem_update\` to modify items
-- Do NOT use write_file or edit tools
-
-${refinePrompt}
-
-${agentInstructions}`;
-        // Queue message for agent
+        const invocation = buildMacroInvocation(skillName, refinePrompt, {
+            project: { id: currentProject.id, name: currentProject.name },
+            refineItemId: isFocusedRefine ? itemId : undefined,
+        });
         ctx.queueAgentMessage({
-            message: fullMessage,
-            displayMessage: userIntent,
+            macro: skillName,
+            message: invocation.message,
+            displayMessage: invocation.displayMessage,
         });
         return true;
     },
@@ -692,10 +647,10 @@ export const buildCommand = {
             }
         }
         // Load capabilities and get build skill prompt
-        loadSkillCapabilities('build', ctx);
+        loadMacroCapabilities('build', ctx);
         let buildPrompt = getSkillPrompt('build');
         if (!buildPrompt) {
-            ctx.ui.print({ type: 'error', message: 'Build skill not found.' });
+            ctx.ui.print({ type: 'error', message: 'Build macro not found.' });
             return true;
         }
         // Replace {{projectPath}} and item placeholders with actual values
@@ -706,48 +661,20 @@ export const buildCommand = {
             .replace(/\{\{item_type\}\}/g, selectedItem.type)
             .replace(/\{\{item_priority\}\}/g, selectedItem.priority)
             .replace(/\{\{item_description\}\}/g, selectedItem.description ?? 'No description provided');
-        // Build full message for agent with explicit project path context
-        const fullMessage = `I want to implement backlog item ${selectedItem.itemId}: "${selectedItem.title}".
-
-## PROJECT CONTEXT (CRITICAL)
-- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
-- **Project Directory: ${currentProject.path}**
-- ALL files MUST be created/modified in this directory
-
-## WORK ITEM DETAILS
-- Item ID: ${selectedItem.itemId}
-- Type: ${selectedItem.type}
-- Priority: ${selectedItem.priority}
-- Description: ${selectedItem.description ?? 'No description provided'}
-
-## TOOL RESTRICTIONS (CRITICAL)
-- Do NOT use detect_project or find_project_root
-- Do NOT scan filesystem to detect project type
-- The project path above is the ONLY source of truth for where to create/modify files
-- Use \`project_document_get\` to read PRD and architecture docs from the database
-- Use \`workitem_query\` to read related backlog items from the database
-- Use \`workitem_update\` to update the item status when done
-
-## FILE OPERATIONS (CRITICAL)
-When creating or modifying files:
-- Use absolute paths starting with: ${currentProject.path}/
-- Example: write_file({ path: "${currentProject.path}/src/index.ts", ... })
-- NEVER use relative paths
-- IGNORE the current working directory (cwd) - it may be different from the project!
-- The user may have started the CLI from a different folder
-
-${buildPrompt}
-
-Please start by:
-1. Using todo_write to plan the implementation steps
-2. Reading project documents from the database (project_document_list, project_document_get)
-3. Updating the work item status to 'in_progress' using workitem_update
-4. Implementing the feature
-5. Updating the work item status to 'completed' when done`;
-        // Queue message for agent
+        const invocation = buildMacroInvocation('build', buildPrompt, {
+            project: { id: currentProject.id, name: currentProject.name, path: currentProject.path },
+            workItem: {
+                itemId: selectedItem.itemId,
+                type: selectedItem.type,
+                priority: selectedItem.priority,
+                title: selectedItem.title,
+                description: selectedItem.description ?? undefined,
+            },
+        });
         ctx.queueAgentMessage({
-            message: fullMessage,
-            displayMessage: `Build ${selectedItem.itemId}: ${selectedItem.title}`,
+            macro: 'build',
+            message: invocation.message,
+            displayMessage: invocation.displayMessage,
         });
         return true;
     },
@@ -771,41 +698,22 @@ export const noteCommand = {
             return Promise.resolve(true);
         }
         // Load capabilities and get session-notes skill prompt
-        loadSkillCapabilities('session-notes', ctx);
+        loadMacroCapabilities('session-notes', ctx);
         const notePrompt = getSkillPrompt('session-notes');
         if (!notePrompt) {
-            ctx.ui.print({ type: 'error', message: 'Session-notes skill not found.' });
+            ctx.ui.print({ type: 'error', message: 'Session-notes macro not found.' });
             return Promise.resolve(true);
         }
         // Check for optional title argument
         const noteTitle = args.trim();
-        // Build title instruction based on whether title was provided
-        const titleInstruction = noteTitle
-            ? `The session title is: "${noteTitle}"`
-            : 'Please ask me for a title using ask_user_simple, or generate one from the session summary.';
-        // Build full message for agent
-        const fullMessage = `I want to create a session note capturing what we've done.
-
-## PROJECT CONTEXT
-- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
-
-## DOCUMENT STORAGE (CRITICAL)
-Save session notes using the database - do NOT write files directly.
-- Tool: \`project_document_add({ doc_type: "session-note", title: "...", content: "..." })\`
-- The database is the source of truth for all project documents
-- Do NOT use write_file or edit tools for documentation
-
-${notePrompt}
-
-${titleInstruction}
-
-Review the conversation context to understand what was accomplished, then create the session note.`;
-        // Queue message for agent
+        const invocation = buildMacroInvocation('session-notes', notePrompt, {
+            project: { id: currentProject.id, name: currentProject.name },
+            noteTitle: noteTitle || undefined,
+        });
         ctx.queueAgentMessage({
-            message: fullMessage,
-            displayMessage: noteTitle
-                ? `Create session note: "${noteTitle}"`
-                : 'Create a session note for this session.',
+            macro: 'session-notes',
+            message: invocation.message,
+            displayMessage: invocation.displayMessage,
         });
         return Promise.resolve(true);
     },
@@ -830,39 +738,22 @@ export const prdCommand = {
             return Promise.resolve(true);
         }
         // Load capabilities and get PRD skill prompt
-        loadSkillCapabilities('prd', ctx);
+        loadMacroCapabilities('prd', ctx);
         const prdPrompt = getSkillPrompt('prd');
         if (!prdPrompt) {
-            ctx.ui.print({ type: 'error', message: 'PRD skill not found.' });
+            ctx.ui.print({ type: 'error', message: 'PRD macro not found.' });
             return Promise.resolve(true);
         }
         // Check for optional section argument
         const section = args.trim().toLowerCase();
-        const validSections = ['vision', 'scope', 'technical', 'success'];
-        const sectionInstruction = validSections.includes(section)
-            ? `The user wants to update the "${section}" section specifically.`
-            : 'Ask the user which section they want to update using ask_user_simple.';
-        // Build full message for agent with project context
-        const fullMessage = `I want to update the Product Requirements Document.
-
-## DOCUMENT STORAGE (CRITICAL)
-Save PRD updates using the database - do NOT write files directly.
-- Project: ${currentProject.name} (ID: ${String(currentProject.id)})
-- Tool: \`project_document_add({ doc_type: "prd", title: "Product Requirements Document", content: "..." })\`
-- The database is the source of truth for all project documents
-- Do NOT use write_file or edit tools for documentation
-
-${prdPrompt}
-
-${sectionInstruction}
-
-Start by reading the existing PRD from the database using project_document_get({ doc_type: "prd" }). If no document exists yet, create a new one.`;
-        // Queue message for agent
+        const invocation = buildMacroInvocation('prd', prdPrompt, {
+            project: { id: currentProject.id, name: currentProject.name },
+            section: section || undefined,
+        });
         ctx.queueAgentMessage({
-            message: fullMessage,
-            displayMessage: section
-                ? `Update PRD: ${section} section`
-                : 'Update the Product Requirements Document',
+            macro: 'prd',
+            message: invocation.message,
+            displayMessage: invocation.displayMessage,
         });
         return Promise.resolve(true);
     },
@@ -956,46 +847,23 @@ export const scaffoldCommand = {
             skillName = 'scaffold';
         }
         // Load capability packs for this skill
-        loadSkillCapabilities(skillName, ctx);
+        loadMacroCapabilities(skillName, ctx);
         // Get skill prompt and replace path placeholder
         let scaffoldPrompt = getSkillPrompt(skillName);
         if (!scaffoldPrompt) {
-            ctx.ui.print({ type: 'error', message: `${skillName} skill not found.` });
+            ctx.ui.print({ type: 'error', message: `${skillName} macro not found.` });
             return true;
         }
         scaffoldPrompt = scaffoldPrompt.replace(/\{\{projectPath\}\}/g, currentProject.path);
-        const closingInstruction = skillName === 'factory-scaffold'
-            ? 'Start by checking the Application Model with app_model_get. If no model exists, read the PRD with project_document_get and build the model incrementally using app_model_update. Then generate with factory_scaffold.'
-            : 'Start by reading the project documents from the database using project_document_list and project_document_get. Then create a plan with todo_write before generating files.';
-        // Build full message for agent with explicit project path context
-        const fullMessage = `I want to create the project scaffold/foundation.
-
-## PROJECT CONTEXT (CRITICAL)
-- Project Name: ${currentProject.name} (ID: ${String(currentProject.id)})
-- **Project Directory: ${currentProject.path}**
-- ALL files MUST be created in this directory
-${factoryContext}
-## TOOL RESTRICTIONS (CRITICAL)
-- Do NOT use detect_project or find_project_root
-- Do NOT scan filesystem to detect project type
-- The project path above is the ONLY source of truth for where to create files
-- Use \`project_document_get\` to read PRD and architecture docs from the database
-- Use \`workitem_query\` to read backlog items from the database
-
-## FILE CREATION (CRITICAL)
-When creating files:
-- Use absolute paths starting with: ${currentProject.path}/
-- Example: write_file({ path: "${currentProject.path}/package.json", ... })
-- NEVER use relative paths
-- IGNORE the current working directory (cwd) - it may be different from the project!
-- The user may have started the CLI from a different folder
-
-${scaffoldPrompt}
-
-${closingInstruction}`;
-        // Queue message for agent
+        const invocation = buildMacroInvocation(skillName, scaffoldPrompt, {
+            project: { id: currentProject.id, name: currentProject.name, path: currentProject.path },
+            scaffold: { factoryContext, isFactory: skillName === 'factory-scaffold' },
+        });
         ctx.queueAgentMessage({
-            message: fullMessage,
+            macro: skillName,
+            message: invocation.message,
+            // ⚠️ The CLI's own line, not the SDK's: it distinguishes three cases from app-model state
+            // that only this host has looked up. The MESSAGE is shared; this label is presentation.
             displayMessage: hasAppModel
                 ? 'Generate project from Application Model.'
                 : prdMentionsEntities
@@ -1038,10 +906,10 @@ export const archCommand = {
             return true;
         }
         // Load capabilities and get architecture skill prompt
-        loadSkillCapabilities('architecture', ctx);
+        loadMacroCapabilities('architecture', ctx);
         const archPrompt = getSkillPrompt('architecture');
         if (!archPrompt) {
-            ctx.ui.print({ type: 'error', message: 'Architecture skill not found.' });
+            ctx.ui.print({ type: 'error', message: 'Architecture macro not found.' });
             return true;
         }
         // Build the document type description for display
@@ -1059,23 +927,14 @@ export const archCommand = {
         const finalPrompt = archPrompt
             .replace('{{doc_type}}', archChoice.type)
             .replace('{{#if custom_topic}}Custom Topic: {{custom_topic}}{{/if}}', archChoice.customTopic ? `Custom Topic: ${archChoice.customTopic}` : '');
-        // Build full message for agent with project context
-        const fullMessage = `I want to create architecture documentation.
-
-## DOCUMENT STORAGE (CRITICAL)
-Save architecture documentation using the database - do NOT write files directly.
-- Project: ${currentProject.name} (ID: ${String(currentProject.id)})
-- Tool: \`project_document_add({ doc_type: "architecture", title: "...", content: "..." })\`
-- The database is the source of truth for all project documents
-- Do NOT use write_file or edit tools for documentation
-
-${finalPrompt}
-
-Please start by using project_document_list to find any existing PRD, and workitem_query to understand the project backlog. Then use ask_user to gather the information needed for this ${archChoice.type} document.`;
-        // Queue message for agent
+        const invocation = buildMacroInvocation('architecture', finalPrompt, {
+            project: { id: currentProject.id, name: currentProject.name },
+            architecture: { docType: archChoice.type, displayType },
+        });
         ctx.queueAgentMessage({
-            message: fullMessage,
-            displayMessage: `Create ${displayType} documentation.`,
+            macro: 'architecture',
+            message: invocation.message,
+            displayMessage: invocation.displayMessage,
         });
         return true;
     },

package/dist/commands-v2/handlers/skill.js

@@ -7,29 +7,30 @@
  * Spec: project-docs/00-requirements/compilr-dev-cli/skills-overlay-spec.md
  */
 import { promises as fs } from 'node:fs';
+import { getCliSkillSources } from '../../repl-helpers.js';
 import { SkillsOverlayV2 } from '../../ui/overlay/impl/skills-overlay-v2.js';
 import { SkillDetailOverlayV2 } from '../../ui/overlay/impl/skill-detail-overlay-v2.js';
 import { getCurrentProject } from '../../tools/project-db.js';
 const skillCommand = {
     name: 'skill',
     aliases: ['skills'],
-    description: 'Manage custom and built-in skills',
+    description: 'Manage your skills and their slash-command bindings',
     details: 'Browse, create, edit, and manage user-authored skills. Skills are ' +
         'folders with SKILL.md (Anthropic Agent Skills format). Custom skills ' +
-        'can be scoped to a project or user. Built-in SDK skills are read-only.',
+        'can be scoped to a project or user. Built-in commands are not skills ' +
+        'and are not listed here — fork one from "New skill → from a command".',
     examples: [
         { code: '/skill', description: 'Open Skills overlay' },
         { code: '/skills', description: 'Alias for /skill' },
     ],
     interactions: [
-        '←→ Switch tabs (Custom / Built-in)',
+        '←→ Switch tabs (Custom / Bindings)',
         '↑↓ or j/k Navigate skills',
         'Enter Open skill (view/edit/diff)',
-        'n Create new skill',
-        'f Fork SDK skill',
+        'n Create new skill (blank, or forked from a command)',
         'b Bind slash command',
         'u Unbind slash command',
-        'Space Enable/disable skill',
+        'Space Shelve / restore (writes the two Anthropic switches)',
         'd Delete skill',
         'r Rename skill',
         '/ Search skills',
@@ -39,6 +40,9 @@ const skillCommand = {
         const project = getCurrentProject();
         const overlay = new SkillsOverlayV2({
             projectPath: project?.path ?? undefined,
+            // The same sources the resolver gets, so what this overlay LISTS and what
+            // getSkillPrompt will RUN cannot disagree.
+            skillSources: getCliSkillSources(),
             onOpenDetail: async (filePath, skillName, scope, forkedFrom, boundCommands) => {
                 const content = await fs.readFile(filePath, 'utf-8');
                 const detail = new SkillDetailOverlayV2({

package/dist/commands-v2/handlers/team.d.ts

@@ -3,7 +3,25 @@
  *
  * Commands for managing multi-agent teams.
  */
-import type { CommandHandlerV2 } from '../types.js';
+import type { CommandHandlerV2, CommandContextV2 } from '../types.js';
+import type { AgentTeam } from '../../multi-agent/index.js';
 export declare const teamCommand: CommandHandlerV2;
+/**
+ * Edit an existing team agent.
+ *
+ * ⚠️ THE INSTRUCTIONS FIELD IS NOT THE SAME FIELD FOR BOTH AGENT KINDS, and reading the
+ * wrong one moves the user's data. A custom agent's live `systemPromptAddition` is the
+ * whole GENERATED prompt ("You are a X specialized in Y. …"), not the instructions the
+ * user typed — those live on the `CustomAgentDefinition` on disk. So:
+ *
+ *   custom agent → read/write `CustomAgentDefinition.systemPromptAddition`, then
+ *                  regenerate the live prompt around it
+ *   role agent   → read/write the live `TeamAgent.systemPromptAddition`, which for that
+ *                  kind genuinely IS free text
+ *
+ * Loading one and saving the other is an asymmetric round trip: it does not look like a
+ * bug until the data has already moved.
+ */
+export declare function handleEditAgent(ctx: CommandContextV2, team: AgentTeam, agentId: string): Promise<void>;
 export declare const artifactCommand: CommandHandlerV2;
 export declare const teamCommands: CommandHandlerV2[];