commandmate 0.11.4 → 0.12.1

package/dist/cli/commands/skill.js

@@ -0,0 +1,365 @@
+"use strict";
+/**
+ * skill Command - manage official Agent Skills from the CLI
+ * Issue #1237: a thin client over the Skill APIs (#1231/#1233/#1235/#1236)
+ *
+ *   commandmate skill list [--json]
+ *   commandmate skill info <skill-id> [--version <v>] [--json]
+ *   commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]
+ *   commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>]
+ *   commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]
+ *   commandmate skill status <skill-id> --worktree <id> [--json]
+ *
+ * The CLI never downloads, extracts, writes or deletes anything: it asks the
+ * server for a plan, shows it, and presents the token the server issued back to
+ * the server unchanged. It reconstructs no file list, no checksum and no path —
+ * those inputs are rejected by the API by design (#1233), and reproducing them
+ * here would create exactly the UI/CLI security drift the design forbids.
+ *
+ * `--json` prints the API response body verbatim, so the JSON contract is the
+ * API's. Every diagnostic, prompt and error goes to stderr, so a failed `--json`
+ * run leaves stdout empty rather than half-written.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSkillCommand = createSkillCommand;
+const commander_1 = require("commander");
+const types_1 = require("../types");
+const api_client_1 = require("../utils/api-client");
+const command_helpers_1 = require("../utils/command-helpers");
+const skill_format_1 = require("./skill-format");
+const skill_guards_1 = require("./skill-guards");
+/** Validated `<skill-id>` plus `--worktree`, or null when either was rejected. */
+function resolveTarget(skillId, worktree) {
+    if (!(0, skill_guards_1.isValidSkillId)(skillId)) {
+        (0, skill_guards_1.refuse)('Invalid Skill ID. Expected lowercase alphanumeric segments joined by hyphens.', types_1.ExitCode.CONFIG_ERROR);
+        return null;
+    }
+    if (!worktree) {
+        (0, skill_guards_1.refuse)('--worktree <id> is required. List candidates with: commandmate ls', types_1.ExitCode.CONFIG_ERROR);
+        return null;
+    }
+    if (!(0, api_client_1.isValidWorktreeId)(worktree)) {
+        (0, skill_guards_1.refuse)('Invalid worktree ID format.', types_1.ExitCode.CONFIG_ERROR);
+        return null;
+    }
+    return { skillId, worktreeId: worktree };
+}
+function catalogQuery(options) {
+    return options.prerelease ? '?prerelease=true' : '';
+}
+// =============================================================================
+// Read commands
+// =============================================================================
+async function listSkills(options) {
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const response = await client.get(`/api/skills${catalogQuery(options)}`);
+    const body = (0, api_client_1.assertResponseShape)(response, ['catalog', 'skills'], 'GET /api/skills');
+    const freshness = (0, skill_format_1.formatCatalogFreshness)(body.catalog);
+    if (freshness)
+        console.error(freshness);
+    console.log(options.json ? JSON.stringify(body, null, 2) : (0, skill_format_1.formatSkillTable)(body.skills));
+}
+async function showSkill(skillId, options) {
+    if (!(0, skill_guards_1.isValidSkillId)(skillId)) {
+        (0, skill_guards_1.refuse)('Invalid Skill ID. Expected lowercase alphanumeric segments joined by hyphens.', types_1.ExitCode.CONFIG_ERROR);
+        return;
+    }
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const response = await client.get(`/api/skills/${encodeURIComponent(skillId)}${catalogQuery(options)}`);
+    const body = (0, api_client_1.assertResponseShape)(response, ['catalog', 'skill'], `GET /api/skills/${skillId}`);
+    const freshness = (0, skill_format_1.formatCatalogFreshness)(body.catalog);
+    if (freshness)
+        console.error(freshness);
+    console.log(options.json ? JSON.stringify(body, null, 2) : (0, skill_format_1.formatSkillDetail)(body.skill, options.version));
+}
+/** Ask the server to build an Install Plan. The only inputs are what to install. */
+async function requestInstallPlan(client, target, options) {
+    const body = {};
+    if (options.version)
+        body.version = options.version;
+    if (options.prerelease)
+        body.includePrerelease = true;
+    const response = await client.post(`/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/plan`, body);
+    return (0, api_client_1.assertResponseShape)(response, ['plan'], 'POST .../skills/plan').plan;
+}
+/** Ask the server to build an Uninstall Plan. It takes no parameters at all. */
+async function requestUninstallPlan(client, target) {
+    const response = await client.post(`/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/uninstall-plan`);
+    return (0, api_client_1.assertResponseShape)(response, ['plan'], 'POST .../skills/uninstall-plan').plan;
+}
+async function planInstall(skillId, options) {
+    const target = resolveTarget(skillId, options.worktree);
+    if (!target)
+        return;
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const plan = await requestInstallPlan(client, target, options);
+    console.log(options.json ? JSON.stringify({ plan }, null, 2) : (0, skill_format_1.formatInstallPlan)(plan));
+    if (!plan.installable)
+        process.exit(types_1.SkillExitCode.BLOCKED);
+}
+/**
+ * Report whether one Skill is installed in one worktree.
+ *
+ * Derived from the uninstall preview, which is the only endpoint that reports
+ * installed state: it reads the on-disk receipt rather than the index, so what
+ * it reports is evidence rather than a claim. It writes nothing. There is no
+ * per-worktree listing endpoint yet, so `<skill-id>` is required.
+ */
+async function showStatus(skillId, options) {
+    const target = resolveTarget(skillId, options.worktree);
+    if (!target)
+        return;
+    const client = new api_client_1.ApiClient({ token: options.token });
+    let plan;
+    try {
+        plan = await requestUninstallPlan(client, target);
+    }
+    catch (error) {
+        // Not installed is an answer, not a failure: `status` must be usable as a
+        // precondition check without a script having to swallow an exit code.
+        if (error instanceof api_client_1.ApiError && error.apiCode === 'SKILL_UNINSTALL_NOT_INSTALLED') {
+            const notInstalled = { skillId: target.skillId, worktreeId: target.worktreeId, installed: false };
+            console.log(options.json
+                ? JSON.stringify(notInstalled, null, 2)
+                : `${target.skillId} is not installed in ${target.worktreeId}.`);
+            return;
+        }
+        throw error;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ installed: true, plan }, null, 2));
+        return;
+    }
+    console.log([
+        `${plan.skill.id} ${plan.skill.version} is installed in ${plan.target.worktreeId}.`,
+        `Install root: ${plan.target.installRoot}`,
+        `Risk:         ${plan.skill.effectiveRisk}`,
+        `Removable:    ${plan.removable ? 'yes' : 'no'}`,
+    ].join('\n'));
+}
+// =============================================================================
+// Write commands
+// =============================================================================
+async function installSkill(skillId, options) {
+    const target = resolveTarget(skillId, options.worktree);
+    if (!target)
+        return;
+    if (!options.version) {
+        (0, skill_guards_1.refuse)('--version <exact> is required for install. Inspect published versions with: commandmate skill info ' + skillId, types_1.ExitCode.CONFIG_ERROR);
+        return;
+    }
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const plan = await requestInstallPlan(client, target, options);
+    // --dry-run stops here by construction: the plan is the whole output and no
+    // token is ever presented back to the server.
+    if (options.dryRun) {
+        console.log(options.json ? JSON.stringify({ plan }, null, 2) : (0, skill_format_1.formatInstallPlan)(plan));
+        if (!plan.installable)
+            process.exit(types_1.SkillExitCode.BLOCKED);
+        return;
+    }
+    console.error((0, skill_format_1.formatInstallPlan)(plan));
+    if (!plan.installable) {
+        (0, skill_guards_1.refuse)('The Skill cannot be installed into this worktree; nothing was written.', types_1.SkillExitCode.BLOCKED);
+        return;
+    }
+    // Checked before the generic confirmation so `--yes` alone can never carry a
+    // high-risk install, in a TTY or out of one.
+    if (plan.requiresRiskAcknowledgement &&
+        !(0, skill_guards_1.riskAcknowledgementMatches)(options.ackRisk, plan.skill.id, plan.skill.version)) {
+        (0, skill_guards_1.refuse)(`${plan.skill.id} ${plan.skill.version} is high risk. Re-run with --ack-risk ${plan.skill.id}@${plan.skill.version} to acknowledge it explicitly.`, types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    const outcome = await (0, skill_guards_1.resolveWriteConfirmation)(`Install ${plan.skill.id} ${plan.skill.version} into ${plan.target.worktreeId} (${(0, skill_format_1.formatInstallRoots)(plan.target.installRoots, plan.target.installRoot)})?`, options);
+    if (outcome === 'non_interactive') {
+        (0, skill_guards_1.refuse)('Refusing to install without a confirmation. Pass --yes to install from a non-interactive environment.', types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    if (outcome === 'declined') {
+        (0, skill_guards_1.refuse)('Install declined; nothing was written.', types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    const response = await client.post(`/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/install`, {
+        planToken: plan.token,
+        version: plan.skill.version,
+        acknowledgeRisk: plan.requiresRiskAcknowledgement,
+    });
+    const body = (0, api_client_1.assertResponseShape)(response, ['operation', 'install'], 'POST .../skills/install');
+    if (options.json) {
+        console.log(JSON.stringify(body, null, 2));
+    }
+    else {
+        console.log(`Installed ${body.install?.skillId ?? target.skillId} ${body.install?.version ?? plan.skill.version} into ${(0, skill_format_1.formatInstallRoots)(body.install?.installRoots, body.install?.installRoot ?? plan.target.installRoot)}`);
+    }
+    if (body.operation.result === 'committed_reconciling') {
+        // The payload is on disk; saying "install failed" would contradict what the
+        // user can see. Report it as needing attention instead.
+        console.error(`Warning: the files landed but the operation did not finish cleanly (${body.operation.nextActionKey}). Reconciliation will converge it.`);
+        process.exit(types_1.SkillExitCode.COMMITTED_RECONCILING);
+    }
+}
+async function uninstallSkill(skillId, options) {
+    const target = resolveTarget(skillId, options.worktree);
+    if (!target)
+        return;
+    const client = new api_client_1.ApiClient({ token: options.token });
+    const plan = await requestUninstallPlan(client, target);
+    if (options.dryRun) {
+        console.log(options.json ? JSON.stringify({ plan }, null, 2) : (0, skill_format_1.formatUninstallPlan)(plan));
+        if (!plan.removable)
+            process.exit(types_1.SkillExitCode.BLOCKED);
+        return;
+    }
+    console.error((0, skill_format_1.formatUninstallPlan)(plan));
+    if (!plan.removable) {
+        (0, skill_guards_1.refuse)('The uninstall is blocked by the paths listed above; nothing was deleted.', types_1.SkillExitCode.BLOCKED);
+        return;
+    }
+    const outcome = await (0, skill_guards_1.resolveWriteConfirmation)(`Remove ${plan.skill.id} ${plan.skill.version} from ${plan.target.worktreeId} (${plan.target.installRoot})?`, options);
+    if (outcome === 'non_interactive') {
+        (0, skill_guards_1.refuse)('Refusing to uninstall without a confirmation. Pass --yes to uninstall from a non-interactive environment.', types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    if (outcome === 'declined') {
+        (0, skill_guards_1.refuse)('Uninstall declined; nothing was deleted.', types_1.SkillExitCode.CONFIRMATION_REQUIRED);
+        return;
+    }
+    const response = await client.post(`/api/worktrees/${encodeURIComponent(target.worktreeId)}/skills/${encodeURIComponent(target.skillId)}/uninstall`, { planToken: plan.token });
+    const body = (0, api_client_1.assertResponseShape)(response, ['operation', 'uninstall'], 'POST .../skills/uninstall');
+    if (options.json) {
+        console.log(JSON.stringify(body, null, 2));
+    }
+    else {
+        console.log(`Removed ${body.uninstall?.skillId ?? target.skillId} ${body.uninstall?.version ?? plan.skill.version} from ${plan.target.installRoot}`);
+    }
+    for (const entry of body.uninstall?.retained ?? []) {
+        console.error(`Retained: ${entry.path} (${entry.reason})`);
+    }
+    if (body.operation.result === 'committed_reconciling') {
+        console.error(`Warning: deletion had already begun when the operation ended (${body.operation.nextActionKey}). Reconciliation will converge it.`);
+        process.exit(types_1.SkillExitCode.COMMITTED_RECONCILING);
+    }
+}
+// =============================================================================
+// Wiring
+// =============================================================================
+function createSkillCommand() {
+    const skill = new commander_1.Command('skill');
+    skill.description('Manage official Agent Skills (catalog, install plan, install, uninstall)');
+    skill
+        .command('list')
+        .description('List Skills published in the official Catalog')
+        .option('--json', 'JSON output (the API response body, verbatim)')
+        .option('--prerelease', 'Include prerelease versions')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (options) => {
+        try {
+            await listSkills(options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
+    skill
+        .command('info')
+        .description('Show one Skill: capabilities, provider, versions and compatibility')
+        .argument('<skill-id>', 'Skill ID from the Catalog')
+        .option('--version <version>', 'Show only this published version')
+        .option('--json', 'JSON output (the API response body, verbatim)')
+        .option('--prerelease', 'Include prerelease versions')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (skillId, options) => {
+        try {
+            await showSkill(skillId, options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
+    skill
+        .command('plan')
+        .description('Preview installing a Skill into a worktree. Never writes.')
+        .argument('<skill-id>', 'Skill ID from the Catalog')
+        .option('--worktree <id>', 'Target worktree ID (see: commandmate ls)')
+        .option('--version <version>', 'Exact version to plan (default: the recommended version)')
+        .option('--json', 'JSON output (the API response body, verbatim)')
+        .option('--prerelease', 'Include prerelease versions when resolving --version')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (skillId, options) => {
+        try {
+            await planInstall(skillId, options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
+    skill
+        .command('install')
+        .description('Install a Skill into a worktree, after showing the plan and confirming')
+        .argument('<skill-id>', 'Skill ID from the Catalog')
+        .option('--worktree <id>', 'Target worktree ID (see: commandmate ls)')
+        .option('--version <version>', 'Exact version to install')
+        .option('--dry-run', 'Build and print the plan, then stop without writing')
+        .option('-y, --yes', 'Skip the confirmation prompt (required for non-interactive use)')
+        .option('--ack-risk <skill-id@version>', 'Explicitly acknowledge a high-risk Skill. Required in addition to --yes.')
+        .option('--json', 'JSON output (the API response body, verbatim)')
+        .option('--prerelease', 'Allow a prerelease --version')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (skillId, options) => {
+        try {
+            await installSkill(skillId, options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
+    skill
+        .command('uninstall')
+        .description('Remove an installed Skill from a worktree, after showing the plan and confirming')
+        .argument('<skill-id>', 'Installed Skill ID')
+        .option('--worktree <id>', 'Target worktree ID (see: commandmate ls)')
+        .option('--dry-run', 'Build and print the plan, then stop without deleting')
+        .option('-y, --yes', 'Skip the confirmation prompt (required for non-interactive use)')
+        .option('--json', 'JSON output (the API response body, verbatim)')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (skillId, options) => {
+        try {
+            await uninstallSkill(skillId, options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
+    skill
+        .command('status')
+        .description('Report whether a Skill is installed in a worktree, and whether it is removable')
+        .argument('<skill-id>', 'Skill ID to look for')
+        .option('--worktree <id>', 'Target worktree ID (see: commandmate ls)')
+        .option('--json', 'JSON output')
+        .option('--token <token>', command_helpers_1.TOKEN_WARNING)
+        .action(async (skillId, options) => {
+        try {
+            await showStatus(skillId, options);
+        }
+        catch (error) {
+            (0, skill_guards_1.handleSkillCommandError)(error);
+        }
+    });
+    skill.addHelpText('after', `
+Confirmation contract:
+  - Writes (install, uninstall) always build a plan first and print it.
+  - Without a TTY, a write requires --yes; a missing --yes is refused, never assumed.
+  - A high-risk Skill additionally requires --ack-risk <skill-id>@<version>.
+    --yes alone never carries a high-risk install.
+  - --dry-run stops at the plan and writes nothing.
+
+Exit codes:
+  0   success
+  1   the server or the Catalog could not be reached
+  2   invalid arguments, unknown Skill or unknown version
+  11  the worktree refused the operation (local change, conflict, lock, plan drift)
+  12  the write was never confirmed (no --yes, declined, or missing --ack-risk)
+  13  the files changed but the operation needs reconciliation
+`);
+    return skill;
+}

package/dist/cli/docs/agent-operations.d.ts

@@ -5,6 +5,6 @@
  * This content is embedded as a string constant so that it's available
  * even when installed via `npm install -g commandmate` (where docs/ is not included).
  */
-export declare const AGENT_OPERATIONS_GUIDE = "# CLI Agent Operations Guide\n\nOperate agent sessions from the CommandMate CLI.\nThese commands enable coding agents (Claude Code, Codex, etc.) to orchestrate other agents in parallel.\n\n## Prerequisites\n\n- CommandMate server must be running: commandmate start --daemon\n- Target worktrees must be registered (visible in browser UI sidebar)\n- Use CM_PORT env var to connect to a different port (default: 3000)\n- Use CM_AUTH_TOKEN env var for authenticated servers\n\n## Commands\n\n### commandmate ls\n  List worktrees with status.\n\n  commandmate ls                          # Table format (ID, NAME, STATUS, DEFAULT)\n  commandmate ls --json                   # JSON output (for agent consumption)\n  commandmate ls --quiet                  # IDs only, one per line (for piping)\n  commandmate ls --branch <prefix>        # Filter by branch name prefix\n  commandmate ls --id <prefix>            # Filter by worktree id prefix\n\n  Worktree ids are <repo>-<branch> slugs (e.g. anvil-develop). --id / --branch\n  front-match is case-sensitive and does NOT guarantee uniqueness (e.g.\n  --id anvil-develop also matches anvil-develop-2). --branch and --id combine\n  as AND. Use --id to disambiguate the same branch across repositories.\n\n  STATUS values:\n    idle     - Session not started\n    ready    - Session running, waiting for input (task completed)\n    running  - Agent executing a task\n    waiting  - Confirmation prompt active (Yes/No, etc.)\n\n### commandmate send <worktree-id> \"<message>\"\n  Send a message to an agent (async). Starts session automatically if not running.\n\n  Options:\n    --agent <id>           Agent type: claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity\n    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). See \"Multi-Session\" below.\n    --register             Register the --instance session into the agent-instance roster\n    --auto-yes             Enable auto-yes before sending\n    --duration <d>         Auto-yes duration: 1h, 3h, 8h (default: 1h)\n    --stop-pattern <p>     Auto-yes stop condition (regex)\n\n  Finding worktree IDs:\n    WT=$(commandmate ls --branch feature/101 --quiet)\n    WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)\n    commandmate send \"$WT\" \"Implement this\"\n\n### commandmate wait <worktree-id...>\n  Block until agent completes or prompt is detected.\n\n  Options:\n    --timeout <seconds>        Maximum wait time\n    --on-prompt <mode>         agent (default) or human\n    --stall-timeout <seconds>  Max time without output change\n\n  Exit codes:\n    0   - Completed (agent idle/ready)\n    10  - Prompt detected (--on-prompt agent mode)\n    124 - Timeout exceeded\n\n  --on-prompt modes:\n    agent  - Returns exit 10 immediately with prompt JSON on stdout\n    human  - Keeps blocking until human responds via browser UI\n\n  Prompt JSON output (exit 10):\n    {\"worktreeId\":\"...\",\"cliToolId\":\"claude\",\"type\":\"yes_no\",\"question\":\"...\",\"options\":[\"yes\",\"no\"],\"status\":\"pending\"}\n\n### commandmate respond <worktree-id> \"<answer>\"\n  Respond to an agent's prompt.\n\n  commandmate respond <id> \"yes\"          # Yes/No\n  commandmate respond <id> \"2\"            # Multiple choice (number)\n  commandmate respond <id> \"custom text\"  # Free text\n\n  Exit codes:\n    0  - Response sent\n    99 - Prompt already dismissed (prompt_no_longer_active)\n\n### commandmate capture <worktree-id>\n  Get current terminal output.\n\n  commandmate capture <id>                # Plain text\n  commandmate capture <id> --json         # JSON with status info\n  commandmate capture <id> --agent codex  # Specific agent\n\n### commandmate auto-yes <worktree-id>\n  Control auto-yes (automatic prompt response).\n\n  commandmate auto-yes <id> --enable                    # Enable (default 1h)\n  commandmate auto-yes <id> --enable --duration 3h      # With duration\n  commandmate auto-yes <id> --enable --stop-pattern \"error\"\n  commandmate auto-yes <id> --disable                   # Disable\n\n### commandmate instances <worktree-id> [action] [args]\n  Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).\n\n  commandmate instances <id>                            # List roster + running/auto-yes status\n  commandmate instances <id> --json                     # JSON output\n  commandmate instances <id> add --agent codex          # Add an instance (auto-generates ID, e.g. codex-2)\n  commandmate instances <id> add --agent codex --alias \"Review\" --id codex-3\n  commandmate instances <id> remove <instance-id>       # Remove from roster\n  commandmate instances <id> remove <instance-id> --kill  # Remove and kill its session\n  commandmate instances <id> alias <instance-id> \"New Name\"\n  commandmate instances <id> kill <instance-id>         # Kill only that instance's session\n\n  See \"Multi-Session\" below for the ID convention and roster semantics.\n\n## Multi-Session (1 agent, multiple sessions)\n\n  A worktree can run several sessions of the same CLI tool concurrently. Each\n  session is an \"instance\" identified by an instance ID:\n    <agent>        - the agent's primary instance (e.g. \"claude\")\n    <agent>-<n>    - an additional instance, n >= 2 (e.g. \"claude-2\", \"claude-3\")\n\n  --instance is accepted by send / wait / respond / capture / auto-yes.\n  send --instance auto-starts the session if it is not already running.\n\n  The roster (visible in the browser UI's Agent panel) is the list of known\n  instances with aliases and display order. Ad-hoc sessions started via\n  'send --instance' do NOT appear in the roster unless registered:\n    commandmate send <id> \"...\" --instance claude-2 --register\n  Without --register, the session still runs and responds to CLI commands,\n  but it will not show up in the UI sidebar/roster until added there or via\n  'commandmate instances <id> add'.\n\n  Per-instance auto-yes: --instance scopes --auto-yes/--duration/--stop-pattern\n  to that specific session, independent of other instances of the same agent.\n\n  commandmate instances <id>                        # discover valid --instance values\n  commandmate send <id> \"task\" --agent codex --instance codex-2 --auto-yes\n  commandmate wait <id> --instance codex-2 --timeout 600\n  commandmate capture <id> --agent codex --instance codex-2\n\n## All Exit Codes\n\n  0   SUCCESS          - Completed successfully\n  1   DEPENDENCY_ERROR - Server not running\n  2   CONFIG_ERROR     - Validation error (invalid agent, duration, etc.)\n  10  PROMPT_DETECTED  - Prompt detected during wait\n  99  UNEXPECTED_ERROR - Unexpected error / resource not found\n  124 TIMEOUT          - Wait timeout exceeded\n\n## Troubleshooting\n\n  Server not running:\n    commandmate start --daemon\n    CM_PORT=3011 commandmate ls        # Different port\n\n  Worktree not found:\n    commandmate ls --quiet             # Check registered IDs\n    curl -s -X POST http://localhost:3000/api/repositories/sync  # Sync new worktrees\n\n  Authentication:\n    CM_AUTH_TOKEN=your-token commandmate ls\n";
+export declare const AGENT_OPERATIONS_GUIDE = "# CLI Agent Operations Guide\n\nOperate agent sessions from the CommandMate CLI.\nThese commands enable coding agents (Claude Code, Codex, etc.) to orchestrate other agents in parallel.\n\n## Prerequisites\n\n- CommandMate server must be running: commandmate start --daemon\n- Target worktrees must be registered (visible in browser UI sidebar)\n- Use CM_PORT env var to connect to a different port (default: 3000)\n- Use CM_AUTH_TOKEN env var for authenticated servers\n\n## Commands\n\n### commandmate ls\n  List worktrees with status.\n\n  commandmate ls                          # Table format (ID, NAME, STATUS, DEFAULT)\n  commandmate ls --json                   # JSON output (for agent consumption)\n  commandmate ls --quiet                  # IDs only, one per line (for piping)\n  commandmate ls --branch <prefix>        # Filter by branch name prefix\n  commandmate ls --id <prefix>            # Filter by worktree id prefix\n\n  Worktree ids are <repo>-<branch> slugs (e.g. anvil-develop). --id / --branch\n  front-match is case-sensitive and does NOT guarantee uniqueness (e.g.\n  --id anvil-develop also matches anvil-develop-2). --branch and --id combine\n  as AND. Use --id to disambiguate the same branch across repositories.\n\n  STATUS values:\n    idle     - Session not started\n    ready    - Session running, waiting for input (task completed)\n    running  - Agent executing a task\n    waiting  - Confirmation prompt active (Yes/No, etc.)\n\n### commandmate send <worktree-id> \"<message>\"\n  Send a message to an agent (async). Starts session automatically if not running.\n\n  Options:\n    --agent <id>           Agent type: claude (default), codex, gemini, vibe-local, opencode, copilot, antigravity\n    --instance <id>        Agent instance ID: <agent> or <agent>-<n> (e.g. claude-2). See \"Multi-Session\" below.\n    --register             Register the --instance session into the agent-instance roster\n    --auto-yes             Enable auto-yes before sending\n    --duration <d>         Auto-yes duration: 1h, 3h, 8h (default: 1h)\n    --stop-pattern <p>     Auto-yes stop condition (regex)\n\n  Finding worktree IDs:\n    WT=$(commandmate ls --branch feature/101 --quiet)\n    WT=$(commandmate ls --id anvil- --quiet)   # disambiguate by repo (id prefix)\n    commandmate send \"$WT\" \"Implement this\"\n\n### commandmate wait <worktree-id...>\n  Block until agent completes or prompt is detected.\n\n  Options:\n    --timeout <seconds>        Maximum wait time\n    --on-prompt <mode>         agent (default) or human\n    --stall-timeout <seconds>  Max time without output change\n\n  Exit codes:\n    0   - Completed (agent idle/ready)\n    10  - Prompt detected (--on-prompt agent mode)\n    124 - Timeout exceeded\n\n  --on-prompt modes:\n    agent  - Returns exit 10 immediately with prompt JSON on stdout\n    human  - Keeps blocking until human responds via browser UI\n\n  Prompt JSON output (exit 10):\n    {\"worktreeId\":\"...\",\"cliToolId\":\"claude\",\"type\":\"yes_no\",\"question\":\"...\",\"options\":[\"yes\",\"no\"],\"status\":\"pending\"}\n\n### commandmate respond <worktree-id> \"<answer>\"\n  Respond to an agent's prompt.\n\n  commandmate respond <id> \"yes\"          # Yes/No\n  commandmate respond <id> \"2\"            # Multiple choice (number)\n  commandmate respond <id> \"custom text\"  # Free text\n\n  Exit codes:\n    0  - Response sent\n    99 - Prompt already dismissed (prompt_no_longer_active)\n\n### commandmate capture <worktree-id>\n  Get current terminal output.\n\n  commandmate capture <id>                # Plain text\n  commandmate capture <id> --json         # JSON with status info\n  commandmate capture <id> --agent codex  # Specific agent\n\n### commandmate auto-yes <worktree-id>\n  Control auto-yes (automatic prompt response).\n\n  commandmate auto-yes <id> --enable                    # Enable (default 1h)\n  commandmate auto-yes <id> --enable --duration 3h      # With duration\n  commandmate auto-yes <id> --enable --stop-pattern \"error\"\n  commandmate auto-yes <id> --disable                   # Disable\n\n### commandmate instances <worktree-id> [action] [args]\n  Discover and manage a worktree's agent-instance roster (1 agent, multiple sessions).\n\n  commandmate instances <id>                            # List roster + running/auto-yes status\n  commandmate instances <id> --json                     # JSON output\n  commandmate instances <id> add --agent codex          # Add an instance (auto-generates ID, e.g. codex-2)\n  commandmate instances <id> add --agent codex --alias \"Review\" --id codex-3\n  commandmate instances <id> remove <instance-id>       # Remove from roster\n  commandmate instances <id> remove <instance-id> --kill  # Remove and kill its session\n  commandmate instances <id> alias <instance-id> \"New Name\"\n  commandmate instances <id> kill <instance-id>         # Kill only that instance's session\n\n  See \"Multi-Session\" below for the ID convention and roster semantics.\n\n### commandmate skill <subcommand>\n  Manage official Agent Skills. Every subcommand is a thin client over the same\n  APIs the browser UI uses: the CLI never downloads, extracts, writes or deletes\n  anything itself, and never sends a filesystem path, artifact URL, file list or\n  checksum (the API rejects those outright).\n\n  commandmate skill list [--json] [--prerelease]\n  commandmate skill info <skill-id> [--version <v>] [--json]\n  commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]\n  commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>] [--json]\n  commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]\n  commandmate skill status <skill-id> --worktree <id> [--json]\n\n  Confirmation contract (writes = install / uninstall):\n    - A plan is always built and shown first. --dry-run stops there.\n    - Without a TTY, a write REQUIRES --yes. A missing --yes is refused, never\n      assumed: an environment that cannot prompt must not install silently.\n    - A high-risk Skill additionally requires --ack-risk <skill-id>@<version>\n      with the exact id and version. --yes alone never carries a high-risk\n      install, in a TTY or out of one.\n\n  Exit codes:\n    0   success\n    1   the server or the Catalog could not be reached (retryable)\n    2   invalid arguments, unknown Skill or unknown version\n    11  the worktree refused it (local change, conflict, lock, plan drift)\n    12  the write was never confirmed (no --yes, declined, or missing --ack-risk)\n    13  files changed but the operation needs reconciliation\n\n  --json prints the API response body verbatim on stdout; diagnostics, prompts\n  and errors always go to stderr, so a failed --json run leaves stdout empty.\n\n  'skill status' reports one Skill in one worktree, read from the install\n  receipt on disk. There is no per-worktree listing endpoint yet, so <skill-id>\n  is required.\n\n## Multi-Session (1 agent, multiple sessions)\n\n  A worktree can run several sessions of the same CLI tool concurrently. Each\n  session is an \"instance\" identified by an instance ID:\n    <agent>        - the agent's primary instance (e.g. \"claude\")\n    <agent>-<n>    - an additional instance, n >= 2 (e.g. \"claude-2\", \"claude-3\")\n\n  --instance is accepted by send / wait / respond / capture / auto-yes.\n  send --instance auto-starts the session if it is not already running.\n\n  The roster (visible in the browser UI's Agent panel) is the list of known\n  instances with aliases and display order. Ad-hoc sessions started via\n  'send --instance' do NOT appear in the roster unless registered:\n    commandmate send <id> \"...\" --instance claude-2 --register\n  Without --register, the session still runs and responds to CLI commands,\n  but it will not show up in the UI sidebar/roster until added there or via\n  'commandmate instances <id> add'.\n\n  Per-instance auto-yes: --instance scopes --auto-yes/--duration/--stop-pattern\n  to that specific session, independent of other instances of the same agent.\n\n  commandmate instances <id>                        # discover valid --instance values\n  commandmate send <id> \"task\" --agent codex --instance codex-2 --auto-yes\n  commandmate wait <id> --instance codex-2 --timeout 600\n  commandmate capture <id> --agent codex --instance codex-2\n\n## All Exit Codes\n\n  0   SUCCESS          - Completed successfully\n  1   DEPENDENCY_ERROR - Server not running\n  2   CONFIG_ERROR     - Validation error (invalid agent, duration, etc.)\n  10  PROMPT_DETECTED  - Prompt detected during wait\n  99  UNEXPECTED_ERROR - Unexpected error / resource not found\n  124 TIMEOUT          - Wait timeout exceeded\n\n## Troubleshooting\n\n  Server not running:\n    commandmate start --daemon\n    CM_PORT=3011 commandmate ls        # Different port\n\n  Worktree not found:\n    commandmate ls --quiet             # Check registered IDs\n    curl -s -X POST http://localhost:3000/api/repositories/sync  # Sync new worktrees\n\n  Authentication:\n    CM_AUTH_TOKEN=your-token commandmate ls\n";
 export declare const AGENT_OPERATIONS_SAMPLES = "# CLI Agent Operations - Workflow Samples\n\nCopy and adapt these patterns for your use case.\n\n## 1. Basic: send, wait, capture\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101 with TDD\"\n  commandmate wait \"$WT\" --timeout 600\n  commandmate capture \"$WT\"\n\n## 2. With Auto-Yes (unattended execution)\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Implement Issue #101\" --auto-yes --duration 3h\n  commandmate wait \"$WT\" --timeout 1800\n  commandmate auto-yes \"$WT\" --disable    # Disable for safety\n  commandmate capture \"$WT\" --json\n\n## 3. Prompt Response Loop\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n  commandmate send \"$WT\" \"Refactor this module\"\n\n  while true; do\n    commandmate wait \"$WT\" --timeout 600 --on-prompt agent\n    EXIT_CODE=$?\n\n    if [ $EXIT_CODE -eq 0 ]; then\n      echo \"Done\"\n      break\n    elif [ $EXIT_CODE -eq 10 ]; then\n      commandmate respond \"$WT\" \"yes\"\n    elif [ $EXIT_CODE -eq 124 ]; then\n      echo \"Timeout\"\n      break\n    fi\n  done\n\n  commandmate capture \"$WT\"\n\n## 4. Parallel Worktrees\n\n  WT1=$(commandmate ls --branch feature/101 --quiet)\n  WT2=$(commandmate ls --branch feature/102 --quiet)\n\n  commandmate send \"$WT1\" \"Implement #101\" --auto-yes\n  commandmate send \"$WT2\" \"Implement #102\" --auto-yes --agent codex\n\n  commandmate wait \"$WT1\" \"$WT2\" --timeout 1800\n\n  commandmate capture \"$WT1\" --json\n  commandmate capture \"$WT2\" --json\n\n## 5. Check status before sending\n\n  # Find worktrees and check status\n  commandmate ls --json | python3 -c \"\n  import sys, json\n  for wt in json.load(sys.stdin):\n      if wt['name'].startswith('feature/'):\n          print(f\\\"{wt['id']}  {wt['name']}\\\")\n  \"\n\n## 6. Error handling pattern\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  if [ -z \"$WT\" ]; then\n    echo \"Error: worktree not found\"\n    exit 1\n  fi\n\n  commandmate send \"$WT\" \"Fix the bug\" --auto-yes\n  commandmate wait \"$WT\" --timeout 600\n  EXIT_CODE=$?\n\n  case $EXIT_CODE in\n    0)   echo \"Success\"; commandmate capture \"$WT\" ;;\n    10)  echo \"Prompt detected\"; commandmate respond \"$WT\" \"yes\" ;;\n    124) echo \"Timeout\"; commandmate capture \"$WT\" --json ;;\n    *)   echo \"Error: exit $EXIT_CODE\" ;;\n  esac\n\n## 7. Multi-Session: run a second Codex session alongside the primary agent\n\n  WT=$(commandmate ls --branch feature/101 --quiet)\n\n  # Discover the roster before picking an --instance value\n  commandmate instances \"$WT\"\n\n  # Register a second Codex instance, then send/wait/capture scoped to it\n  commandmate instances \"$WT\" add --agent codex --alias \"Review\"\n  commandmate send \"$WT\" \"Review the diff\" --agent codex --instance codex-2 --auto-yes\n  commandmate wait \"$WT\" --instance codex-2 --timeout 600\n  commandmate capture \"$WT\" --agent codex --instance codex-2 --json\n\n  # Ad-hoc instance without pre-registering (still runs; register to show in UI)\n  commandmate send \"$WT\" \"Quick check\" --agent codex --instance codex-3 --register\n\n  # Clean up when done\n  commandmate instances \"$WT\" remove codex-2 --kill\n";
 //# sourceMappingURL=agent-operations.d.ts.map

package/dist/cli/docs/agent-operations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,ogOA6JlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,osGAsGpC,CAAC"}
+{"version":3,"file":"agent-operations.d.ts","sourceRoot":"","sources":["../../../src/cli/docs/agent-operations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,sBAAsB,u9RAiMlC,CAAC;AAEF,eAAO,MAAM,wBAAwB,osGAsGpC,CAAC"}

package/dist/cli/docs/agent-operations.js

@@ -118,6 +118,42 @@ These commands enable coding agents (Claude Code, Codex, etc.) to orchestrate ot
 
   See "Multi-Session" below for the ID convention and roster semantics.
 
+### commandmate skill <subcommand>
+  Manage official Agent Skills. Every subcommand is a thin client over the same
+  APIs the browser UI uses: the CLI never downloads, extracts, writes or deletes
+  anything itself, and never sends a filesystem path, artifact URL, file list or
+  checksum (the API rejects those outright).
+
+  commandmate skill list [--json] [--prerelease]
+  commandmate skill info <skill-id> [--version <v>] [--json]
+  commandmate skill plan <skill-id> --worktree <id> [--version <v>] [--json]
+  commandmate skill install <skill-id> --worktree <id> --version <exact> [--dry-run] [--yes] [--ack-risk <id>@<version>] [--json]
+  commandmate skill uninstall <skill-id> --worktree <id> [--dry-run] [--yes] [--json]
+  commandmate skill status <skill-id> --worktree <id> [--json]
+
+  Confirmation contract (writes = install / uninstall):
+    - A plan is always built and shown first. --dry-run stops there.
+    - Without a TTY, a write REQUIRES --yes. A missing --yes is refused, never
+      assumed: an environment that cannot prompt must not install silently.
+    - A high-risk Skill additionally requires --ack-risk <skill-id>@<version>
+      with the exact id and version. --yes alone never carries a high-risk
+      install, in a TTY or out of one.
+
+  Exit codes:
+    0   success
+    1   the server or the Catalog could not be reached (retryable)
+    2   invalid arguments, unknown Skill or unknown version
+    11  the worktree refused it (local change, conflict, lock, plan drift)
+    12  the write was never confirmed (no --yes, declined, or missing --ack-risk)
+    13  files changed but the operation needs reconciliation
+
+  --json prints the API response body verbatim on stdout; diagnostics, prompts
+  and errors always go to stderr, so a failed --json run leaves stdout empty.
+
+  'skill status' reports one Skill in one worktree, read from the install
+  receipt on disk. There is no per-worktree listing endpoint yet, so <skill-id>
+  is required.
+
 ## Multi-Session (1 agent, multiple sessions)
 
   A worktree can run several sessions of the same CLI tool concurrently. Each

package/dist/cli/program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AA0D5C;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAkKtC"}
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../src/cli/program.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AA4D5C;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,OAAO,CA4KtC"}

package/dist/cli/program.js

@@ -26,6 +26,8 @@ const auto_yes_1 = require("./commands/auto-yes");
 const report_1 = require("./commands/report");
 // Issue #1000: Agent-instance roster management (discover/add/remove/alias/kill)
 const instances_1 = require("./commands/instances");
+// Issue #1237: Skill management as a thin client over the Skill APIs
+const skill_1 = require("./commands/skill");
 // Issue #1195: Guided quickstart for bare `npx commandmate`
 const quickstart_1 = require("./commands/quickstart");
 const prompt_1 = require("./utils/prompt");
@@ -67,6 +69,13 @@ function buildProgram() {
     program
         .name('commandmate')
         .description('Git worktree management with Claude CLI and tmux sessions')
+        // Issue #1462: parse root options only before the command name, then hand the
+        // rest to the matched subcommand. Without this, commander's default lets the
+        // root's `--version` flag (from .version() below) swallow a subcommand's
+        // `--version <v>` in space form (`skill install X --version 0.1.0`), printing
+        // the CLI version and exiting 0 — a silent no-op. Positional parsing leaves
+        // options after the command name for the subcommand that owns them.
+        .enablePositionalOptions()
         .version(pkg.version)
         // Issue #1195: commander drops its implicit `help [command]` as soon as a root action
         // exists, so it is re-enabled explicitly to keep `commandmate help <cmd>` working
@@ -199,6 +208,8 @@ function buildProgram() {
     program.addCommand((0, report_1.createReportCommand)());
     // Issue #1000: Agent-instance roster management
     program.addCommand((0, instances_1.createInstancesCommand)());
+    // Issue #1237: Skill management (catalog / plan / install / uninstall / status)
+    program.addCommand((0, skill_1.createSkillCommand)());
     // Issue #264: AI Tool Integration help section
     program.addHelpText('after', `
 AI Tool Integration: