@aopslabs/aops 0.2.0

package/dist/commands/skill.js

@@ -0,0 +1,1211 @@
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { logError, logSuccess } from '@aopslabs/xf-cli-ui';
+import { applyCommonOptions, compactPayload, normalizeNonEmpty } from '../utils/command.js';
+import { invokeHostedToolWithApiState, parseJsonInput, requireApiState, unwrapHostedToolResult, } from '../utils/agent-gateway.js';
+import { resolveOwnerScopeIdFromBinding, resolveOwnerScopeIdFromProjectRecord, resolveProjectBindingContext, } from '../utils/project-context.js';
+import { buildHostedSugarEnvelope, buildOperatorCookbook, ensureDestructiveWrite, ensureGuardedWrite, missingScopeIdMessage, resolveNextVersionNumber, } from '../utils/hosted-sugar.js';
+import { GUIDE_PATHS } from '../utils/guide-paths.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function unwrapResultData(result) {
+    if (isRecord(result) && Object.prototype.hasOwnProperty.call(result, 'data')) {
+        return result.data;
+    }
+    return result;
+}
+function unwrapListItems(result) {
+    const data = unwrapResultData(result);
+    if (Array.isArray(data)) {
+        return data.filter((entry) => isRecord(entry));
+    }
+    if (isRecord(data) && Array.isArray(data.items)) {
+        return data.items.filter((entry) => isRecord(entry));
+    }
+    if (Array.isArray(result)) {
+        return result.filter((entry) => isRecord(entry));
+    }
+    return [];
+}
+function collectRepeatedOption(value, previous = []) {
+    const normalized = normalizeNonEmpty(value);
+    return normalized ? [...previous, normalized] : previous;
+}
+function toInteger(value, label) {
+    if (typeof value === 'number' && Number.isInteger(value))
+        return value;
+    const normalized = normalizeNonEmpty(value);
+    if (!normalized)
+        throw new Error(`${label} must be an integer.`);
+    const parsed = Number.parseInt(normalized, 10);
+    if (!Number.isInteger(parsed))
+        throw new Error(`${label} must be an integer.`);
+    return parsed;
+}
+export function resolveSkillDiscoveryInput(params) {
+    const query = normalizeNonEmpty(params.query);
+    if (!query)
+        throw new Error('Provide --query <text> or -q <text>.');
+    if (query.length > 256 || Buffer.byteLength(query, 'utf8') > 256) {
+        throw new Error('--query must be at most 256 characters and 256 UTF-8 bytes.');
+    }
+    const limit = params.limit === undefined ? undefined : toInteger(params.limit, '--limit');
+    if (limit !== undefined && (limit < 1 || limit > 5)) {
+        throw new Error('--limit must be between 1 and 5.');
+    }
+    const scopeResolution = normalizeNonEmpty(params.scopeResolution);
+    if (scopeResolution && scopeResolution !== 'explicit' && scopeResolution !== 'cascade') {
+        throw new Error('--scope-resolution must be explicit or cascade.');
+    }
+    return compactPayload({
+        query,
+        scopeId: normalizeNonEmpty(params.scopeId),
+        scopeResolution,
+        limit,
+    });
+}
+export function formatSkillSearchResult(result) {
+    if (!isRecord(result))
+        return 'No published hosted skill matched the query.';
+    const candidates = Array.isArray(result.candidates)
+        ? result.candidates.filter((candidate) => isRecord(candidate))
+        : [];
+    if (candidates.length === 0) {
+        const query = normalizeNonEmpty(result.query);
+        return query
+            ? `No published hosted skill matched "${query}".`
+            : 'No published hosted skill matched the query.';
+    }
+    return candidates.map((candidate, index) => {
+        const name = normalizeNonEmpty(candidate.name) ?? '(unnamed skill)';
+        const shortDescription = normalizeNonEmpty(candidate.shortDescription);
+        const exactRef = normalizeNonEmpty(candidate.exactRef) ?? normalizeNonEmpty(candidate.versionId) ?? '(no ref)';
+        const rationale = normalizeNonEmpty(candidate.rationale);
+        return [
+            `${index + 1}. ${name}${shortDescription ? ` — ${shortDescription}` : ''}`,
+            `   ref: ${exactRef}`,
+            ...(rationale ? [`   match: ${rationale}`] : []),
+        ].join('\n');
+    }).join('\n');
+}
+function toStringArray(values) {
+    return Array.isArray(values)
+        ? values.map((entry) => normalizeNonEmpty(entry)).filter((entry) => Boolean(entry))
+        : [];
+}
+function slugifyProjectSelector(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80);
+}
+function matchesHostedProjectSlugSelector(row, selector) {
+    const normalizedSelector = slugifyProjectSelector(selector);
+    if (!normalizedSelector)
+        return false;
+    const aliases = [
+        normalizeNonEmpty(row.slug),
+        normalizeNonEmpty(row.projectSlug),
+        normalizeNonEmpty(row.name),
+    ];
+    return aliases.some((alias) => alias ? slugifyProjectSelector(alias) === normalizedSelector : false);
+}
+function stripRepoProjectSelectors(options) {
+    const { projectId: _projectId, projectName: _projectName, projectSlug: _projectSlug, ...rest } = options;
+    return rest;
+}
+function stripHostedProjectSlug(options) {
+    const cleaned = { ...options };
+    for (const key of ['hostedProjectSlug', 'projectSlug', 'preview', 'apply', 'confirm', 'idempotencyKey', 'input']) {
+        delete cleaned[key];
+    }
+    return cleaned;
+}
+function parseJsonSeed(input, label = '--input') {
+    const normalized = normalizeNonEmpty(input);
+    if (!normalized)
+        return {};
+    const parsed = parseJsonInput(normalized, label);
+    if (!isRecord(parsed))
+        throw new Error(`${label} must be a JSON object or @file.json object.`);
+    return parsed;
+}
+function parseUnknownJsonInput(input, label) {
+    const normalized = normalizeNonEmpty(input);
+    if (!normalized)
+        return undefined;
+    return parseJsonInput(normalized, label);
+}
+function readTextInput(input) {
+    if (typeof input !== 'string')
+        return undefined;
+    const trimmed = input.trim();
+    if (!trimmed)
+        return undefined;
+    if (trimmed.startsWith('@')) {
+        const filePath = trimmed.slice(1).trim();
+        if (!filePath)
+            throw new Error('Expected a file path after @.');
+        return readFileSync(filePath, 'utf8');
+    }
+    return input;
+}
+function resolveStringField(explicit, seed, key) {
+    return normalizeNonEmpty(explicit) ?? normalizeNonEmpty(seed[key]);
+}
+function resolveStringArrayField(explicit, seed, key) {
+    const explicitValues = toStringArray(explicit);
+    if (explicitValues.length > 0)
+        return explicitValues;
+    const seededValues = toStringArray(seed[key]);
+    return seededValues.length > 0 ? seededValues : undefined;
+}
+function resolveIntegerField(explicit, seed, key, label) {
+    if (explicit !== undefined && explicit !== null && explicit !== '')
+        return toInteger(explicit, label);
+    if (seed[key] !== undefined && seed[key] !== null && seed[key] !== '')
+        return toInteger(seed[key], label);
+    return undefined;
+}
+function resolveTextField(explicit, seed, key) {
+    const explicitValue = readTextInput(explicit);
+    if (explicitValue !== undefined)
+        return explicitValue;
+    return typeof seed[key] === 'string' ? seed[key] : undefined;
+}
+function resolveUnknownField(explicit, seed, key, label) {
+    const explicitValue = parseUnknownJsonInput(explicit, label);
+    if (explicitValue !== undefined)
+        return explicitValue;
+    return seed[key];
+}
+function extractId(value) {
+    return normalizeNonEmpty(value);
+}
+function collectSkillArtifacts(result) {
+    const root = unwrapResultData(result) ?? (isRecord(result) ? result : {});
+    const artifacts = {};
+    const push = (key, value) => {
+        const normalized = extractId(value);
+        if (normalized)
+            artifacts[key] = normalized;
+    };
+    push('skillId', root.skillId);
+    if (!artifacts.skillId && !normalizeNonEmpty(root.skillId) && !normalizeNonEmpty(root.content)) {
+        push('skillId', root.id);
+    }
+    push('currentVersionId', root.currentVersionId);
+    push('skillVersionId', root.skillVersionId);
+    if (!artifacts.skillVersionId && (normalizeNonEmpty(root.skillId) || normalizeNonEmpty(root.content))) {
+        push('skillVersionId', root.id);
+    }
+    return Object.keys(artifacts).length > 0 ? artifacts : undefined;
+}
+function summarizeContent(value) {
+    const content = normalizeNonEmpty(value);
+    if (!content)
+        return undefined;
+    return compactPayload({
+        omitted: true,
+        bytes: Buffer.byteLength(content, 'utf8'),
+        lines: content.split(/\r\n|\r|\n/).length,
+    });
+}
+function summarizeSkillVersionRecord(value) {
+    if (!isRecord(value))
+        return value;
+    const { content, ...rest } = value;
+    return compactPayload({
+        ...rest,
+        contentSummary: summarizeContent(content),
+    });
+}
+function summarizeSkillCurrentResult(result) {
+    if (!isRecord(result))
+        return result;
+    return compactPayload({
+        ...result,
+        currentVersion: summarizeSkillVersionRecord(result.currentVersion),
+        summary: {
+            mode: 'skill-current-summary',
+            omitted: ['currentVersion.content'],
+            fullRecordHint: 'Use `aops-cli skill current --id <skill-id> --json` for full content.',
+        },
+    });
+}
+function summarizeSkillInspectResult(result) {
+    if (!isRecord(result))
+        return result;
+    const versions = Array.isArray(result.versions)
+        ? result.versions.map(summarizeSkillVersionRecord)
+        : result.versions;
+    return compactPayload({
+        ...result,
+        versions,
+        currentVersion: summarizeSkillVersionRecord(result.currentVersion),
+        summary: {
+            ...(isRecord(result.summary) ? result.summary : {}),
+            mode: 'skill-inspect-summary',
+            omitted: ['versions[].content', 'currentVersion.content'],
+            fullRecordHint: 'Use `aops-cli skill inspect --id <skill-id> --json` for full content.',
+        },
+    });
+}
+function summarizeSkillVersionListResult(result) {
+    if (Array.isArray(result))
+        return result.map(summarizeSkillVersionRecord);
+    if (!isRecord(result))
+        return result;
+    const data = Array.isArray(result.data)
+        ? result.data.map(summarizeSkillVersionRecord)
+        : result.data;
+    const items = Array.isArray(result.items)
+        ? result.items.map(summarizeSkillVersionRecord)
+        : result.items;
+    return compactPayload({
+        ...result,
+        data,
+        items,
+        summary: {
+            ...(isRecord(result.summary) ? result.summary : {}),
+            mode: 'skill-version-list-summary',
+            omitted: ['data[].content', 'items[].content'],
+            fullRecordHint: 'Use `aops-cli skill version list --skill-id <skill-id> --json` for full content.',
+        },
+    });
+}
+function buildGatewayOptions(options, resolvedContext) {
+    const baseOptions = stripHostedProjectSlug(options);
+    if (normalizeNonEmpty(options.hostedProjectSlug)) {
+        return {
+            ...baseOptions,
+            projectId: normalizeNonEmpty(resolvedContext.projectId),
+            projectName: undefined,
+            scopeId: normalizeNonEmpty(resolvedContext.scopeId),
+        };
+    }
+    return {
+        ...baseOptions,
+        projectId: normalizeNonEmpty(options.projectId) ?? normalizeNonEmpty(resolvedContext.projectId),
+        projectName: normalizeNonEmpty(options.projectName) ?? normalizeNonEmpty(resolvedContext.projectName),
+    };
+}
+async function hydrateProjectContext(apiState, options, resolvedContext) {
+    const projectId = normalizeNonEmpty(resolvedContext.projectId);
+    if (!projectId)
+        return resolvedContext;
+    if (normalizeNonEmpty(options.scopeId)) {
+        return resolvedContext;
+    }
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        toolId: 'agentspace.project.get-by-id',
+        input: { id: projectId },
+    });
+    const result = unwrapHostedToolResult(payload);
+    const project = unwrapResultData(result);
+    if (!isRecord(project))
+        return resolvedContext;
+    const scopeId = resolveOwnerScopeIdFromProjectRecord(project, resolvedContext.scopeId);
+    const projectName = normalizeNonEmpty(project.name) ?? resolvedContext.projectName;
+    return {
+        ...resolvedContext,
+        scopeId,
+        projectName,
+    };
+}
+async function listHostedProjectsForSlug(apiState, options, resolvedContext, input) {
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(stripRepoProjectSelectors(options), resolvedContext),
+        tenantId: options.tenantId,
+        locale: options.locale,
+        fallbackLocale: options.fallbackLocale,
+        timeoutMs: options.timeoutMs,
+        apiBaseUrl: options.apiBaseUrl,
+        accessToken: options.accessToken,
+        refreshToken: options.refreshToken,
+        toolId: 'agentspace.project.list-projects',
+        input,
+    });
+    return unwrapListItems(unwrapHostedToolResult(payload));
+}
+async function resolveHostedProjectBySlug(apiState, options, resolvedContext, selector) {
+    const slug = normalizeNonEmpty(selector);
+    if (!slug)
+        return resolvedContext;
+    const filteredRows = await listHostedProjectsForSlug(apiState, options, resolvedContext, {
+        filter: { slug },
+        options: { limit: 20 },
+    });
+    const fallbackRows = filteredRows.length > 0
+        ? []
+        : await listHostedProjectsForSlug(apiState, options, resolvedContext, {
+            filter: {},
+            options: { limit: 500 },
+        });
+    const rows = filteredRows.length > 0 ? filteredRows : fallbackRows;
+    const matches = rows.filter((row) => matchesHostedProjectSlugSelector(row, slug));
+    if (matches.length === 0) {
+        throw new Error(`Hosted project slug "${slug}" was not found.`);
+    }
+    if (matches.length > 1) {
+        const ids = matches
+            .map((project) => `${normalizeNonEmpty(project.slug) ?? normalizeNonEmpty(project.name) ?? '(unnamed)'} (${normalizeNonEmpty(project.id) ?? normalizeNonEmpty(project.projectId) ?? normalizeNonEmpty(project.scopeId) ?? 'no-id'})`)
+            .join(', ');
+        throw new Error(`Hosted project slug "${slug}" is ambiguous: ${ids}.`);
+    }
+    const project = matches[0];
+    const projectId = normalizeNonEmpty(project.id) ?? normalizeNonEmpty(project.projectId) ?? normalizeNonEmpty(project.scopeId);
+    const scopeId = normalizeNonEmpty(project.scopeId) ?? projectId;
+    if (!projectId && !scopeId) {
+        throw new Error(`Hosted project slug "${slug}" resolved without a project id.`);
+    }
+    return {
+        ...resolvedContext,
+        projectId: projectId ?? scopeId,
+        scopeId: scopeId ?? projectId,
+        projectName: normalizeNonEmpty(project.name),
+        projectSlug: normalizeNonEmpty(project.slug) ?? normalizeNonEmpty(project.projectSlug) ?? slug,
+    };
+}
+async function resolveSkillContext(options, apiState) {
+    const hostedProjectSlug = normalizeNonEmpty(options.hostedProjectSlug);
+    const bindingOptions = hostedProjectSlug ? stripRepoProjectSelectors(options) : options;
+    const resolved = await resolveProjectBindingContext(bindingOptions, {
+        requireProject: false,
+    });
+    const scopeId = normalizeNonEmpty(bindingOptions.scopeId) ?? resolveOwnerScopeIdFromBinding(resolved);
+    const baseContext = {
+        ...resolved,
+        scopeId,
+    };
+    if (hostedProjectSlug) {
+        return resolveHostedProjectBySlug(apiState, options, baseContext, hostedProjectSlug);
+    }
+    return hydrateProjectContext(apiState, options, baseContext);
+}
+function buildResolvedContextRecord(context) {
+    return compactPayload({
+        repoRoot: context.repoRoot,
+        configPath: context.configPath,
+        configFound: context.configFound,
+        scopeId: context.scopeId,
+        projectId: context.projectId,
+        projectName: context.projectName,
+        projectSlug: context.projectSlug,
+    });
+}
+const buildEnvelope = buildHostedSugarEnvelope;
+function ensureSkillId(id, label = '--id') {
+    const resolved = normalizeNonEmpty(id);
+    if (!resolved)
+        throw new Error(`Provide ${label}.`);
+    return resolved;
+}
+function requireScopeId(context, seed) {
+    const scopeId = normalizeNonEmpty(context.scopeId) ?? normalizeNonEmpty(seed.scopeId);
+    if (!scopeId) {
+        throw new Error(missingScopeIdMessage('Skill create'));
+    }
+    return scopeId;
+}
+function requireProjectId(options, context, seed) {
+    const projectId = normalizeNonEmpty(options.projectId) ??
+        normalizeNonEmpty(context.projectId) ??
+        normalizeNonEmpty(seed.projectId);
+    if (!projectId) {
+        throw new Error('Skill version commands require repo-bound project context or --project-id.');
+    }
+    return projectId;
+}
+function isSkillVersionConflictMessage(message) {
+    const normalized = message.toLowerCase();
+    return (normalized.includes('api 409') ||
+        normalized.includes('agentspace_operation_failed.conflict') ||
+        (normalized.includes('skill-version') && normalized.includes('unique')));
+}
+function formatSkillVersionCreateError(message, hint) {
+    if (hint.skillId && hint.version !== undefined && isSkillVersionConflictMessage(message)) {
+        return `skill version ${hint.version} already exists for skill ${hint.skillId}; pass --version ${hint.version + 1} or omit to auto-resolve`;
+    }
+    return message;
+}
+async function invokeSkillTool(apiState, options, resolvedContext, params) {
+    ensureGuardedWrite(options, 'This command mutates hosted skill state.');
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        tenantId: options.tenantId,
+        locale: options.locale,
+        fallbackLocale: options.fallbackLocale,
+        timeoutMs: options.timeoutMs,
+        apiBaseUrl: options.apiBaseUrl,
+        accessToken: options.accessToken,
+        refreshToken: options.refreshToken,
+        toolId: params.toolId,
+        input: params.input,
+        preview: options.preview,
+        apply: options.apply,
+        confirm: options.confirm,
+        idempotencyKey: options.idempotencyKey,
+    });
+    const result = unwrapHostedToolResult(payload);
+    if (options.json) {
+        console.log(JSON.stringify(buildEnvelope({
+            command: params.command,
+            toolId: params.toolId,
+            resolvedContext: buildResolvedContextRecord(resolvedContext),
+            input: params.input,
+            artifacts: collectSkillArtifacts(result),
+            result,
+        }), null, 2));
+        return;
+    }
+    logSuccess(params.successText);
+    console.log(JSON.stringify(result, null, 2));
+}
+export async function runSkillList(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const input = {
+            filter: compactPayload({
+                scopeId: normalizeNonEmpty(resolvedContext.scopeId),
+                scopeResolution: options.scopeResolution,
+                name: normalizeNonEmpty(options.name),
+                tags: options.tag && options.tag.length > 0 ? options.tag : undefined,
+            }),
+            options: compactPayload({
+                limit: options.limit !== undefined ? toInteger(options.limit, '--limit') : undefined,
+            }),
+        };
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.skill.list-skills',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'skill.list',
+                toolId: 'agentspace.skill.list-skills',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                result,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Skill list loaded.');
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+async function runSkillDiscovery(mode, options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const input = resolveSkillDiscoveryInput({
+            query: options.query ?? options.q,
+            limit: options.limit,
+            scopeId: resolvedContext.scopeId,
+            scopeResolution: options.scopeResolution,
+        });
+        const toolId = `agentspace.skill.${mode}`;
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId,
+            input,
+        });
+        const hostedResult = unwrapHostedToolResult(payload);
+        const result = unwrapResultData(hostedResult) ?? hostedResult;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: `skill.${mode}`,
+                toolId,
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                result,
+            }), null, 2));
+            return;
+        }
+        if (mode === 'ask' && isRecord(result) && normalizeNonEmpty(result.answer)) {
+            logSuccess('Hosted skill recommendation ready.');
+            console.log(normalizeNonEmpty(result.answer));
+            return;
+        }
+        const count = isRecord(result) && Number.isInteger(result.count) ? Number(result.count) : 0;
+        if (count > 0)
+            logSuccess(`${count} hosted skill${count === 1 ? '' : 's'} matched.`);
+        console.log(formatSkillSearchResult(result));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillSearch(options = {}) {
+    return runSkillDiscovery('search', options);
+}
+export async function runSkillAsk(options = {}) {
+    return runSkillDiscovery('ask', options);
+}
+export async function runSkillGet(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const id = ensureSkillId(options.id);
+        const input = { id };
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.skill.get-skill',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'skill.get',
+                toolId: 'agentspace.skill.get-skill',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                artifacts: collectSkillArtifacts(result),
+                result,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Skill loaded.');
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillCreate(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const seed = parseJsonSeed(options.input);
+        const name = resolveStringField(options.name, seed, 'name');
+        if (!name)
+            throw new Error('Skill create requires --name or input.name.');
+        const input = {
+            data: compactPayload({
+                scopeId: requireScopeId(resolvedContext, seed),
+                name,
+                description: resolveStringField(options.description, seed, 'description'),
+                shortDescription: resolveStringField(options.shortDescription, seed, 'shortDescription'),
+                tags: resolveStringArrayField(options.tag, seed, 'tags'),
+            }),
+        };
+        await invokeSkillTool(apiState, options, resolvedContext, {
+            command: 'skill.create',
+            toolId: 'agentspace.skill.create',
+            input,
+            successText: 'Skill created.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillUpdate(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const seed = parseJsonSeed(options.input);
+        const id = ensureSkillId(resolveStringField(options.id, seed, 'id'));
+        const patch = compactPayload({
+            name: resolveStringField(options.name, seed, 'name'),
+            description: resolveStringField(options.description, seed, 'description'),
+            shortDescription: resolveStringField(options.shortDescription, seed, 'shortDescription'),
+            tags: resolveStringArrayField(options.tag, seed, 'tags'),
+            currentVersionId: resolveStringField(options.currentVersionId, seed, 'currentVersionId'),
+        });
+        if (Object.keys(patch).length === 0) {
+            throw new Error('Provide at least one skill field to update.');
+        }
+        const input = { id, patch };
+        await invokeSkillTool(apiState, options, resolvedContext, {
+            command: 'skill.update',
+            toolId: 'agentspace.skill.update-skill',
+            input,
+            successText: 'Skill updated.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillDelete(options = {}) {
+    try {
+        ensureDestructiveWrite(options, 'This command deletes hosted skills.');
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const id = ensureSkillId(options.id);
+        const input = { id };
+        await invokeSkillTool(apiState, options, resolvedContext, {
+            command: 'skill.delete',
+            toolId: 'agentspace.skill.remove-skill',
+            input,
+            successText: 'Skill deleted.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+async function loadSkill(apiState, options, resolvedContext, id) {
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        tenantId: options.tenantId,
+        locale: options.locale,
+        fallbackLocale: options.fallbackLocale,
+        timeoutMs: options.timeoutMs,
+        apiBaseUrl: options.apiBaseUrl,
+        accessToken: options.accessToken,
+        refreshToken: options.refreshToken,
+        toolId: 'agentspace.skill.get-skill',
+        input: { id },
+    });
+    const result = unwrapHostedToolResult(payload);
+    const skill = unwrapResultData(result);
+    return isRecord(skill) ? skill : null;
+}
+async function loadSkillVersionById(apiState, options, resolvedContext, id) {
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        tenantId: options.tenantId,
+        locale: options.locale,
+        fallbackLocale: options.fallbackLocale,
+        timeoutMs: options.timeoutMs,
+        apiBaseUrl: options.apiBaseUrl,
+        accessToken: options.accessToken,
+        refreshToken: options.refreshToken,
+        toolId: 'agentspace.skill-version.get-skill-version',
+        input: { id },
+    });
+    const result = unwrapHostedToolResult(payload);
+    const version = unwrapResultData(result);
+    return isRecord(version) ? version : null;
+}
+async function loadSkillVersions(apiState, options, resolvedContext, skillId, extraFilter = {}) {
+    const filter = compactPayload({
+        skillId,
+        projectId: normalizeNonEmpty(options.projectId) ?? normalizeNonEmpty(resolvedContext.projectId),
+        ...extraFilter,
+    });
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        tenantId: options.tenantId,
+        locale: options.locale,
+        fallbackLocale: options.fallbackLocale,
+        timeoutMs: options.timeoutMs,
+        apiBaseUrl: options.apiBaseUrl,
+        accessToken: options.accessToken,
+        refreshToken: options.refreshToken,
+        toolId: 'agentspace.skill-version.list-skill-versions',
+        input: { filter },
+    });
+    return unwrapListItems(unwrapHostedToolResult(payload));
+}
+export async function runSkillInspect(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const id = ensureSkillId(options.id);
+        const skill = await loadSkill(apiState, options, resolvedContext, id);
+        if (!skill)
+            throw new Error(`Skill not found: ${id}`);
+        const versions = await loadSkillVersions(apiState, options, resolvedContext, id);
+        const currentVersionId = normalizeNonEmpty(skill.currentVersionId);
+        const currentVersion = versions.find((entry) => normalizeNonEmpty(entry.id) === currentVersionId) ??
+            (currentVersionId ? await loadSkillVersionById(apiState, options, resolvedContext, currentVersionId) : null);
+        const result = compactPayload({
+            skill,
+            versions,
+            currentVersion,
+            summary: compactPayload({
+                skillId: normalizeNonEmpty(skill.id),
+                currentVersionId,
+                versionCount: versions.length,
+            }),
+        });
+        const outputResult = options.summary ? summarizeSkillInspectResult(result) : result;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'skill.inspect',
+                surface: 'skill inspection pack',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input: { id },
+                result: outputResult,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Skill inspection pack ready.');
+        console.log(JSON.stringify(outputResult, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillCurrent(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const id = ensureSkillId(options.id);
+        const skill = await loadSkill(apiState, options, resolvedContext, id);
+        if (!skill)
+            throw new Error(`Skill not found: ${id}`);
+        const currentVersionId = normalizeNonEmpty(skill.currentVersionId);
+        if (!currentVersionId) {
+            throw new Error(`Skill ${id} does not have a currentVersionId. Publish or select a skill version first.`);
+        }
+        const currentVersion = await loadSkillVersionById(apiState, options, resolvedContext, currentVersionId);
+        if (!currentVersion) {
+            throw new Error(`Current skill version ${currentVersionId} could not be loaded.`);
+        }
+        const result = { skill, currentVersion };
+        const outputResult = options.summary ? summarizeSkillCurrentResult(result) : result;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'skill.current',
+                surface: 'skill current resolution',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input: { id },
+                artifacts: compactPayload({ skillId: normalizeNonEmpty(skill.id), skillVersionId: currentVersionId }),
+                result: outputResult,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Current skill version loaded.');
+        console.log(JSON.stringify(outputResult, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillVersionList(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const input = {
+            filter: compactPayload({
+                skillId: normalizeNonEmpty(options.skillId),
+                projectId: normalizeNonEmpty(options.projectId) ?? normalizeNonEmpty(resolvedContext.projectId),
+                status: normalizeNonEmpty(options.status),
+                refType: normalizeNonEmpty(options.refType),
+                refId: normalizeNonEmpty(options.refId),
+            }),
+            options: compactPayload({
+                limit: options.limit !== undefined ? toInteger(options.limit, '--limit') : undefined,
+            }),
+        };
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.skill-version.list-skill-versions',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        const outputResult = options.summary ? summarizeSkillVersionListResult(result) : result;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'skill.version.list',
+                toolId: 'agentspace.skill-version.list-skill-versions',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                result: outputResult,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Skill version list loaded.');
+        console.log(JSON.stringify(outputResult, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillVersionGet(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const id = ensureSkillId(options.id);
+        const input = { id };
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.skill-version.get-skill-version',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'skill.version.get',
+                toolId: 'agentspace.skill-version.get-skill-version',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                artifacts: collectSkillArtifacts(result),
+                result,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Skill version loaded.');
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillVersionCreate(options = {}) {
+    const conflictHint = {};
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const seed = parseJsonSeed(options.input);
+        const skillId = resolveStringField(options.skillId, seed, 'skillId');
+        if (!skillId)
+            throw new Error('Skill version create requires --skill-id or input.skillId.');
+        const content = resolveTextField(options.content, seed, 'content');
+        if (!content)
+            throw new Error('Skill version create requires --content or input.content.');
+        const projectId = requireProjectId(options, resolvedContext, seed);
+        const version = resolveIntegerField(options.version, seed, 'version', '--version') ??
+            resolveNextVersionNumber(await loadSkillVersions(apiState, { ...options, projectId }, { ...resolvedContext, projectId: normalizeNonEmpty(resolvedContext.projectId) ?? projectId }, skillId));
+        conflictHint.skillId = skillId;
+        conflictHint.version = version;
+        const input = {
+            data: compactPayload({
+                projectId,
+                skillId,
+                version,
+                status: resolveStringField(options.status, seed, 'status') ?? 'draft',
+                content,
+                entryFile: resolveStringField(options.entryFile, seed, 'entryFile'),
+                skillStandard: resolveStringField(options.skillStandard, seed, 'skillStandard'),
+                meta: resolveUnknownField(options.meta, seed, 'meta', '--meta'),
+                refType: resolveStringField(options.refType, seed, 'refType'),
+                refId: resolveStringField(options.refId, seed, 'refId'),
+            }),
+        };
+        await invokeSkillTool(apiState, options, resolvedContext, {
+            command: 'skill.version.create',
+            toolId: 'agentspace.skill-version.create',
+            input,
+            successText: 'Skill version created.',
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logError(formatSkillVersionCreateError(message, conflictHint));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillVersionUpdate(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const seed = parseJsonSeed(options.input);
+        const id = ensureSkillId(resolveStringField(options.id, seed, 'id'));
+        const patch = compactPayload({
+            projectId: normalizeNonEmpty(options.projectId) ??
+                normalizeNonEmpty(seed.projectId),
+            version: resolveIntegerField(options.version, seed, 'version', '--version'),
+            status: resolveStringField(options.status, seed, 'status'),
+            content: resolveTextField(options.content, seed, 'content'),
+            entryFile: resolveStringField(options.entryFile, seed, 'entryFile'),
+            skillStandard: resolveStringField(options.skillStandard, seed, 'skillStandard'),
+            meta: resolveUnknownField(options.meta, seed, 'meta', '--meta'),
+            refType: resolveStringField(options.refType, seed, 'refType'),
+            refId: resolveStringField(options.refId, seed, 'refId'),
+        });
+        if (Object.keys(patch).length === 0) {
+            throw new Error('Provide at least one skill version field to update.');
+        }
+        const input = { id, patch };
+        await invokeSkillTool(apiState, options, resolvedContext, {
+            command: 'skill.version.update',
+            toolId: 'agentspace.skill-version.update-skill-version',
+            input,
+            successText: 'Skill version updated.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillVersionPublish(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const id = ensureSkillId(options.id);
+        const input = { id };
+        await invokeSkillTool(apiState, options, resolvedContext, {
+            command: 'skill.version.publish',
+            toolId: 'agentspace.skill-version.publish-skill-version',
+            input,
+            successText: 'Skill version published.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runSkillVersionDelete(options = {}) {
+    try {
+        ensureDestructiveWrite(options, 'This command deletes hosted skill versions.');
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveSkillContext(options, apiState);
+        const id = ensureSkillId(options.id);
+        const input = { id };
+        await invokeSkillTool(apiState, options, resolvedContext, {
+            command: 'skill.version.delete',
+            toolId: 'agentspace.skill-version.remove-skill-version',
+            input,
+            successText: 'Skill version deleted.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+function applySkillContextOptions(cmd, params = {}) {
+    applyCommonOptions(cmd);
+    cmd.option('--project-id <id>', 'Project id used to resolve repo-bound skill ownership');
+    cmd.option('--project-name <name>', 'Project name used to resolve repo-bound skill ownership');
+    cmd.option('--hosted-project-slug <slug>', 'Resolve a hosted project by slug through the gateway, bypassing repo config lookup');
+    cmd.option('--scope-id <id>', 'Explicit scope id override for skill shell ownership');
+    if (params.withScopeResolution) {
+        cmd.option('--scope-resolution <mode>', 'Scope resolution policy: explicit or cascade');
+    }
+    return cmd;
+}
+function applyWriteGuards(cmd, params = {}) {
+    cmd.option('--preview', 'Return a validated preflight summary without executing the tool');
+    cmd.option('--apply', 'Execute the hosted write operation');
+    if (params.destructive) {
+        cmd.option('--confirm', 'Required with --apply for destructive deletes');
+    }
+    cmd.option('--idempotency-key <key>', 'Optional idempotency key for hosted writes');
+    return cmd;
+}
+function applyJsonSeedOption(cmd) {
+    cmd.option('--input <jsonOrFile>', 'Optional JSON object seed or @file.json');
+    return cmd;
+}
+export function makeSkillCommand() {
+    const cmd = new Command('skill').description('Agentspace skill and skill-version sugar commands over the hosted AOPS gateway');
+    applySkillContextOptions(cmd.command('search')
+        .description('Find current published hosted skills by bounded deterministic metadata ranking')
+        .option('--q <text>', 'Search phrase (maximum 256 UTF-8 bytes)')
+        .option('--query <text>', 'Long-form alias for --q')
+        .option('--limit <n>', 'Maximum candidates, 1 to 5'), { withScopeResolution: true }).action(async (options) => {
+        await runSkillSearch(options);
+    });
+    applySkillContextOptions(cmd.command('ask')
+        .description('Recommend hosted skills using one deterministic metadata search (no LLM or body loading)')
+        .option('--q <text>', 'Operator or agent need (maximum 256 UTF-8 bytes)')
+        .option('--query <text>', 'Long-form alias for --q')
+        .option('--limit <n>', 'Maximum candidates, 1 to 5'), { withScopeResolution: true }).action(async (options) => {
+        await runSkillAsk(options);
+    });
+    applySkillContextOptions(cmd.command('list')
+        .description('List reusable skill shells')
+        .option('--name <text>', 'Skill name filter')
+        .option('--tag <tag>', 'Skill tag filter', collectRepeatedOption, [])
+        .option('--limit <n>', 'Optional item limit'), { withScopeResolution: true }).action(async (options) => {
+        await runSkillList(options);
+    });
+    applySkillContextOptions(cmd.command('get')
+        .description('Get a skill shell by id')
+        .requiredOption('--id <id>', 'Skill id')).action(async (options) => {
+        await runSkillGet(options);
+    });
+    applyWriteGuards(applyJsonSeedOption(applySkillContextOptions(cmd.command('create')
+        .description('Create a scope-owned skill shell')
+        .requiredOption('--name <text>', 'Skill name')
+        .option('--description <text>', 'Skill description')
+        .option('--short-description <text>', 'Short skill description')
+        .option('--tag <tag>', 'Skill tag', collectRepeatedOption, [])))).action(async (options) => {
+        await runSkillCreate(options);
+    });
+    applyWriteGuards(applyJsonSeedOption(applySkillContextOptions(cmd.command('update')
+        .description('Update a skill shell')
+        .requiredOption('--id <id>', 'Skill id')
+        .option('--name <text>', 'Skill name')
+        .option('--description <text>', 'Skill description')
+        .option('--short-description <text>', 'Short skill description')
+        .option('--tag <tag>', 'Skill tag', collectRepeatedOption, [])
+        .option('--current-version-id <id>', 'Explicitly set currentVersionId on the skill shell')))).action(async (options) => {
+        await runSkillUpdate(options);
+    });
+    applyWriteGuards(applySkillContextOptions(cmd.command('delete')
+        .description('Delete a skill shell')
+        .requiredOption('--id <id>', 'Skill id')), { destructive: true }).action(async (options) => {
+        await runSkillDelete(options);
+    });
+    applySkillContextOptions(cmd.command('inspect')
+        .description('Load the skill shell, versions, and current version together')
+        .requiredOption('--id <id>', 'Skill id')
+        .option('--summary', 'Omit skill-version content and print content size summaries')).action(async (options) => {
+        await runSkillInspect(options);
+    });
+    applySkillContextOptions(cmd.command('current')
+        .description('Resolve the current skill version for a skill shell')
+        .requiredOption('--id <id>', 'Skill id')
+        .option('--summary', 'Omit current version content and print content size summary')).action(async (options) => {
+        await runSkillCurrent(options);
+    });
+    const version = cmd.command('version').description('Skill-version authoring and lifecycle commands');
+    applySkillContextOptions(version.command('list')
+        .description('List skill versions')
+        .option('--skill-id <id>', 'Skill id filter')
+        .option('--status <status>', 'Skill version status filter')
+        .option('--ref-type <type>', 'Skill version refType filter')
+        .option('--ref-id <id>', 'Skill version refId filter')
+        .option('--limit <n>', 'Optional item limit')
+        .option('--summary', 'Omit skill-version content and print content size summaries')).action(async (options) => {
+        await runSkillVersionList(options);
+    });
+    applySkillContextOptions(version.command('get')
+        .description('Get a skill version by id')
+        .requiredOption('--id <id>', 'Skill version id')).action(async (options) => {
+        await runSkillVersionGet(options);
+    });
+    applyWriteGuards(applyJsonSeedOption(applySkillContextOptions(version.command('create')
+        .description('Create a new skill version')
+        .requiredOption('--skill-id <id>', 'Skill id')
+        .option('--version <n>', 'Optional explicit version number')
+        .option('--status <status>', 'Skill version status')
+        .option('--content <textOrFile>', 'Skill content or @file.md')
+        .option('--entry-file <path>', 'Optional entry file path')
+        .option('--skill-standard <id>', 'Optional skill standard id')
+        .option('--meta <jsonOrFile>', 'JSON meta object/array/value or @file.json')
+        .option('--ref-type <type>', 'Optional refType linkage')
+        .option('--ref-id <id>', 'Optional refId linkage')))).action(async (options) => {
+        await runSkillVersionCreate(options);
+    });
+    applyWriteGuards(applyJsonSeedOption(applySkillContextOptions(version.command('update')
+        .description('Update an existing skill version')
+        .requiredOption('--id <id>', 'Skill version id')
+        .option('--version <n>', 'Explicit version number')
+        .option('--status <status>', 'Skill version status')
+        .option('--content <textOrFile>', 'Skill content or @file.md')
+        .option('--entry-file <path>', 'Optional entry file path')
+        .option('--skill-standard <id>', 'Optional skill standard id')
+        .option('--meta <jsonOrFile>', 'JSON meta object/array/value or @file.json')
+        .option('--ref-type <type>', 'Optional refType linkage')
+        .option('--ref-id <id>', 'Optional refId linkage')))).action(async (options) => {
+        await runSkillVersionUpdate(options);
+    });
+    applyWriteGuards(applySkillContextOptions(version.command('publish')
+        .description('Publish a skill version and sync the skill current version')
+        .requiredOption('--id <id>', 'Skill version id'))).action(async (options) => {
+        await runSkillVersionPublish(options);
+    });
+    applyWriteGuards(applySkillContextOptions(version.command('delete')
+        .description('Delete a skill version')
+        .requiredOption('--id <id>', 'Skill version id')), { destructive: true }).action(async (options) => {
+        await runSkillVersionDelete(options);
+    });
+    cmd.addHelpText('after', buildOperatorCookbook({
+        examples: [
+            'aops skill search --q "kanban sprint planning" --limit 3',
+            'aops skill ask --q "Which skill should an agent use to plan a sprint?" --limit 3',
+            'aops-cli skill create --name "Projectman Delivery" --apply --json',
+            'aops-cli skill version list --skill-id <skill-id> --summary --json',
+            'aops-cli skill version create --skill-id <skill-id> --content @./SKILL.md --apply --json',
+            'aops-cli skill version publish --id <skill-version-id> --hosted-project-slug aops --apply --json',
+            'aops-cli sync pull --apply --hosted-project-slug aops --json',
+            'aops-cli skill inspect --id <skill-id> --json',
+            'aops-cli skill current --id <skill-id> --summary --json',
+        ],
+        guide: GUIDE_PATHS.agentspace,
+        notes: [
+            'Canonical reusable skill truth lives in aops-server/DB; create/update/publish through these skill commands.',
+            '.aops/hosted/skills/** is a read-only repo mirror refreshed by sync pull/bootstrap, not an authoring source.',
+            'Skill version list/inspect/current are curated read surfaces and do not require --apply.',
+            'skill search/ask inspect only current published package metadata; they do not load skill bodies or maintain a local search index.',
+            'skill ask is a deterministic projection of one skill search result, not an LLM-generated semantic answer.',
+            'Use version list/inspect/current --summary for token-efficient checks; omit --summary only when full skill content is needed.',
+            'Use --hosted-project-slug <slug> from a non-bound repo when the hosted project is not in local repo config.',
+            'When --version is omitted, the CLI resolves the next version number from existing skill versions.',
+            'After publishing a hosted skill, run sync pull for the hosted project and verify the mirror currentVersionId/currentVersionStatus before review.',
+        ],
+    }));
+    return cmd;
+}