@downcity/plugins 1.0.4

package/src/shell/runtime/ShellActionRuntimeSupport.ts

@@ -0,0 +1,386 @@
+/**
+ * Shell action 运行时辅助能力。
+ *
+ * 关键点（中文）
+ * - 统一承载 ShellActionRuntime 的内部共享逻辑：环境组装、持久化、waiter 协调、session 查找。
+ * - 对外暴露给 ShellActionRuntime 的只有纯运行时辅助函数，不直接承担 plugin action 编排。
+ */
+
+import path from "node:path";
+import fs from "fs-extra";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ShellPluginState,
+  ShellSessionRuntimeState,
+} from "@/shell/ShellRuntimeTypes.js";
+import type {
+  ShellQueryRequest,
+  ShellSessionSnapshot,
+  ShellSessionStatus,
+} from "@downcity/agent/internal/executor/tools/shell/types/ShellPlugin.js";
+import { getShellOutputPath, getShellSnapshotPath } from "./Paths.js";
+import { readChatMetaBySessionId } from "@/chat/runtime/ChatMetaStore.js";
+import { resolveChatQueueStore } from "@/chat/runtime/ChatQueueStore.js";
+import { resolveOwnerContextId } from "./ShellRuntimeEnvironment.js";
+export {
+  buildShellEnv,
+  resolveOwnerContextId,
+  resolveShellCwd,
+} from "./ShellRuntimeEnvironment.js";
+export {
+  buildActionResponse,
+  createOutputChunk,
+} from "./ShellActionResponse.js";
+
+const MAX_ACTIVE_SHELLS = 64;
+const SESSION_CLEANUP_DELAY_MS = 10 * 60 * 1000;
+const MAX_IN_MEMORY_OUTPUT_CHARS = 1_000_000;
+const MIN_WAIT_MS = 50;
+const MAX_WAIT_MS = 30_000;
+const OUTPUT_PREVIEW_CHARS = 280;
+
+/**
+ * shell.start 默认内联等待时间。
+ */
+export const DEFAULT_INLINE_WAIT_MS = 1_200;
+
+/**
+ * shell.wait 默认等待超时。
+ */
+export const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+
+/**
+ * shell.exec 默认总超时。
+ */
+export const DEFAULT_EXEC_TIMEOUT_MS = 60_000;
+
+/**
+ * 创建 shell plugin runtime 初始状态。
+ */
+export function createShellPluginState(): ShellPluginState {
+  return {
+    sessions: new Map<string, ShellSessionRuntimeState>(),
+    boundRuntime: null,
+  };
+}
+
+/**
+ * 返回当前毫秒时间戳。
+ */
+export function nowMs(): number {
+  return Date.now();
+}
+
+/**
+ * 归一化 wait/timeout 参数。
+ */
+export function clampWaitMs(value: number | undefined, fallback: number): number {
+  const raw =
+    typeof value === "number" && Number.isFinite(value)
+      ? Math.floor(value)
+      : fallback;
+  return Math.min(MAX_WAIT_MS, Math.max(MIN_WAIT_MS, raw));
+}
+
+function normalizeOutputChunk(raw: string): string {
+  if (!raw) return "";
+  return raw
+    .replace(/\r\n/g, "\n")
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
+}
+
+function deriveExitStatus(exitCode: number | undefined): ShellSessionStatus {
+  if (exitCode === -9 || exitCode === 137) return "killed";
+  if (typeof exitCode === "number" && exitCode === 0) return "completed";
+  return "failed";
+}
+
+/**
+ * 判断 shell 是否已进入终态。
+ */
+export function isTerminalStatus(status: ShellSessionStatus): boolean {
+  return (
+    status === "completed" ||
+    status === "failed" ||
+    status === "killed" ||
+    status === "expired"
+  );
+}
+
+function extractExternalRefsFromText(
+  text: string,
+  current: ShellSessionSnapshot["externalRefs"],
+): ShellSessionSnapshot["externalRefs"] {
+  const next = [...current];
+  const register = (kind: string, value: string, label?: string): void => {
+    const normalized = String(value || "").trim();
+    if (!normalized) return;
+    if (next.some((item) => item.kind === kind && item.value === normalized)) return;
+    next.push({ kind, value: normalized, ...(label ? { label } : {}) });
+  };
+
+  const threadIdRegex = /thread_id[:=]\s*([a-zA-Z0-9_-]{6,})/g;
+  for (const match of text.matchAll(threadIdRegex)) {
+    register("thread_id", String(match[1] || ""), "external thread id");
+  }
+  return next;
+}
+
+/**
+ * 持久化 shell snapshot。
+ */
+export async function persistSnapshot(session: ShellSessionRuntimeState): Promise<void> {
+  await fs.ensureDir(path.dirname(session.snapshotFilePath));
+  await fs.writeJson(session.snapshotFilePath, session.snapshot, { spaces: 2 });
+}
+
+function enqueuePersistedAppend(
+  session: ShellSessionRuntimeState,
+  text: string,
+): Promise<void> {
+  session.writeChain = session.writeChain.then(async () => {
+    await fs.ensureDir(path.dirname(session.outputFilePath));
+    await fs.appendFile(session.outputFilePath, text, "utf-8");
+  });
+  return session.writeChain;
+}
+
+function notifyWaiters(session: ShellSessionRuntimeState): void {
+  for (const waiter of Array.from(session.waiters)) {
+    clearTimeout(waiter.timer);
+    session.waiters.delete(waiter);
+    waiter.resolve();
+  }
+}
+
+async function emitChatCompletionEvent(
+  context: AgentContext,
+  snapshot: ShellSessionSnapshot,
+): Promise<void> {
+  const ownerContextId = String(snapshot.ownerContextId || "").trim();
+  if (!ownerContextId || snapshot.notificationSent !== false) return;
+
+  const meta = await readChatMetaBySessionId({ context, sessionId: ownerContextId });
+  if (!meta) return;
+
+  const lines = [
+    "[内部 shell 状态通知]",
+    `shell_id: ${snapshot.shellId}`,
+    `status: ${snapshot.status}`,
+    `exit_code: ${typeof snapshot.exitCode === "number" ? snapshot.exitCode : "null"}`,
+    `cmd: ${snapshot.cmd}`,
+  ];
+  if (snapshot.lastOutputPreview) {
+    lines.push(`last_output_preview: ${snapshot.lastOutputPreview}`);
+  }
+  if (snapshot.externalRefs.length > 0) {
+    const refs = snapshot.externalRefs.map((item) => `${item.kind}=${item.value}`);
+    lines.push(`external_refs: ${refs.join(", ")}`);
+  }
+  lines.push("请根据当前 shell 的状态，主动向用户简洁汇报结果或最新进展。");
+  const text = lines.join("\n");
+
+  resolveChatQueueStore(context).enqueue({
+    kind: "exec",
+    channel: meta.channel,
+    targetId: meta.chatId,
+    sessionId: ownerContextId,
+    text,
+    ...(meta.targetType ? { targetType: meta.targetType } : {}),
+    ...(typeof meta.threadId === "number" ? { threadId: meta.threadId } : {}),
+    ...(meta.messageId ? { messageId: meta.messageId } : {}),
+    ...(meta.actorId ? { actorId: meta.actorId } : {}),
+    ...(meta.actorName ? { actorName: meta.actorName } : {}),
+    extra: {
+      note: "shell_session_auto_notify",
+      internal: true,
+      shellId: snapshot.shellId,
+      shellStatus: snapshot.status,
+      exitCode:
+        typeof snapshot.exitCode === "number" ? snapshot.exitCode : null,
+    },
+  });
+}
+
+/**
+ * 更新 session snapshot 并唤醒等待者。
+ */
+export async function updateSessionSnapshot(
+  session: ShellSessionRuntimeState,
+  updater: (snapshot: ShellSessionSnapshot) => void | ShellSessionSnapshot,
+): Promise<void> {
+  const result = updater(session.snapshot);
+  if (result) {
+    session.snapshot = result;
+  }
+  session.snapshot.updatedAt = nowMs();
+  session.snapshot.version += 1;
+  await persistSnapshot(session);
+  notifyWaiters(session);
+}
+
+/**
+ * 追加 shell 输出并同步更新快照。
+ */
+export async function appendSessionOutput(
+  session: ShellSessionRuntimeState,
+  raw: string,
+): Promise<void> {
+  const text = normalizeOutputChunk(raw);
+  if (!text) return;
+
+  session.outputText += text;
+  if (session.outputText.length > MAX_IN_MEMORY_OUTPUT_CHARS) {
+    const overflow = session.outputText.length - MAX_IN_MEMORY_OUTPUT_CHARS;
+    session.outputText = session.outputText.slice(overflow);
+    session.snapshot.droppedChars += overflow;
+  }
+
+  session.snapshot.outputChars += text.length;
+  session.snapshot.lastOutputAt = nowMs();
+  session.snapshot.lastOutputPreview = session.outputText
+    .slice(-OUTPUT_PREVIEW_CHARS)
+    .trim();
+  session.snapshot.externalRefs = extractExternalRefsFromText(
+    text,
+    session.snapshot.externalRefs,
+  );
+  await enqueuePersistedAppend(session, text);
+  await updateSessionSnapshot(session, () => undefined);
+}
+
+/**
+ * 为终态 shell 安排延迟清理。
+ */
+export function scheduleCleanup(state: ShellPluginState, shellId: string): void {
+  const session = state.sessions.get(shellId);
+  if (!session) return;
+  if (session.cleanupTimer) clearTimeout(session.cleanupTimer);
+  session.cleanupTimer = setTimeout(() => {
+    const current = state.sessions.get(shellId);
+    if (!current) return;
+    state.sessions.delete(shellId);
+  }, SESSION_CLEANUP_DELAY_MS);
+  if (typeof session.cleanupTimer.unref === "function") {
+    session.cleanupTimer.unref();
+  }
+}
+
+/**
+ * 控制 in-memory shell session 容量。
+ */
+export function ensureCapacity(state: ShellPluginState): void {
+  if (state.sessions.size < MAX_ACTIVE_SHELLS) return;
+  const removable = Array.from(state.sessions.values())
+    .filter((item) => item.snapshot.status !== "running" && item.snapshot.status !== "starting")
+    .sort((a, b) => a.snapshot.updatedAt - b.snapshot.updatedAt);
+  for (const item of removable) {
+    if (state.sessions.size < MAX_ACTIVE_SHELLS) break;
+    state.sessions.delete(item.snapshot.shellId);
+  }
+  if (state.sessions.size >= MAX_ACTIVE_SHELLS) {
+    throw new Error(
+      `Too many active shell sessions (${state.sessions.size}). Please close or wait older sessions first.`,
+    );
+  }
+}
+
+async function loadPersistedSnapshot(
+  context: AgentContext,
+  shellId: string,
+): Promise<ShellSessionSnapshot | null> {
+  const file = getShellSnapshotPath(context.rootPath, shellId);
+  if (!(await fs.pathExists(file))) return null;
+  const raw = await fs.readJson(file).catch(() => null);
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const snapshot = raw as ShellSessionSnapshot;
+  return typeof snapshot.shellId === "string" ? snapshot : null;
+}
+
+async function readPersistedOutput(
+  context: AgentContext,
+  shellId: string,
+): Promise<string> {
+  const file = getShellOutputPath(context.rootPath, shellId);
+  if (!(await fs.pathExists(file))) return "";
+  return await fs.readFile(file, "utf-8");
+}
+
+/**
+ * 按 shellId 或 ownerContext 解析目标 session。
+ */
+export async function resolveSession(
+  state: ShellPluginState,
+  context: AgentContext,
+  query: ShellQueryRequest,
+): Promise<ShellSessionRuntimeState | { snapshot: ShellSessionSnapshot; outputText: string } | null> {
+  const explicitShellId = String(query.shellId || "").trim();
+  if (explicitShellId) {
+    const inMemory = state.sessions.get(explicitShellId);
+    if (inMemory) return inMemory;
+    const snapshot = await loadPersistedSnapshot(context, explicitShellId);
+    if (!snapshot) return null;
+    return {
+      snapshot,
+      outputText: await readPersistedOutput(context, explicitShellId),
+    };
+  }
+
+  const ownerContextId = resolveOwnerContextId(query.ownerContextId);
+  const cmd = String(query.cmd || "").trim().toLowerCase();
+  if (!ownerContextId) return null;
+  const includeCompleted = query.includeCompleted === true;
+  const matched = Array.from(state.sessions.values())
+    .filter((item) => {
+      if (item.snapshot.ownerContextId !== ownerContextId) return false;
+      if (!includeCompleted) {
+        if (
+          item.snapshot.status !== "running" &&
+          item.snapshot.status !== "starting"
+        ) {
+          return false;
+        }
+      }
+      if (!cmd) return true;
+      return item.snapshot.cmd.toLowerCase().includes(cmd);
+    })
+    .sort((a, b) => b.snapshot.updatedAt - a.snapshot.updatedAt);
+  return matched[0] || null;
+}
+
+/**
+ * 判断解析出的 session 是否仍在内存中活动。
+ */
+export function isInMemorySession(
+  value: ShellSessionRuntimeState | { snapshot: ShellSessionSnapshot; outputText: string },
+): value is ShellSessionRuntimeState {
+  return "child" in value;
+}
+
+/**
+ * 处理 shell 退出后的状态收口。
+ */
+export async function finalizeExit(
+  state: ShellPluginState,
+  session: ShellSessionRuntimeState,
+  exitCode: number,
+): Promise<void> {
+  await updateSessionSnapshot(session, (snapshot) => {
+    snapshot.status = deriveExitStatus(exitCode);
+    snapshot.exitCode = exitCode;
+    snapshot.endedAt = nowMs();
+    snapshot.pid = session.child.pid ?? snapshot.pid;
+  });
+  session.resolveCompletion();
+  scheduleCleanup(state, session.snapshot.shellId);
+
+  if (
+    session.snapshot.autoNotifyOnExit &&
+    session.snapshot.notificationSent === false &&
+    state.boundRuntime
+  ) {
+    await emitChatCompletionEvent(state.boundRuntime, session.snapshot);
+    session.snapshot.notificationSent = true;
+    await persistSnapshot(session);
+  }
+}

package/src/shell/runtime/ShellProcessEvents.ts

@@ -0,0 +1,65 @@
+/**
+ * Shell 子进程事件绑定辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理 stdout/stderr 追加、process error 与 close 事件。
+ * - close 到达时先等待输出写入链 drain，再统一进入终态收口，避免尾部输出丢读。
+ */
+
+import type { ShellPluginState, ShellSessionRuntimeState } from "@/shell/ShellRuntimeTypes.js";
+import {
+  appendSessionOutput,
+  finalizeExit,
+} from "./ShellActionRuntimeSupport.js";
+
+async function finalizeExitAfterOutputDrain(
+  state: ShellPluginState,
+  session: ShellSessionRuntimeState,
+  exitCode: number,
+): Promise<void> {
+  // 关键点（中文）
+  // - `close` 事件到达时，stdout / stderr 的异步 append 链可能刚刚开始收尾。
+  // - 这里先让出一个事件循环 tick，再等待当前 writeChain，可显著降低“终态已到但尾部输出尚未可读”的竞态。
+  await new Promise<void>((resolve) => {
+    const timer = setImmediate(resolve);
+    if (typeof timer.unref === "function") timer.unref();
+  });
+  await session.writeChain.catch(() => undefined);
+  await finalizeExit(state, session, exitCode);
+}
+
+/**
+ * 绑定 shell 子进程事件。
+ */
+export function attachShellProcessEventHandlers(params: {
+  /**
+   * 当前 shell plugin runtime 状态。
+   */
+  state: ShellPluginState;
+  /**
+   * 当前 shell runtime session。
+   */
+  session: ShellSessionRuntimeState;
+}): void {
+  const { state, session } = params;
+  const { child } = session;
+  child.stdout.on("data", (chunk: string | Buffer) => {
+    void appendSessionOutput(session, String(chunk ?? "")).catch(() => undefined);
+  });
+  child.stderr.on("data", (chunk: string | Buffer) => {
+    void appendSessionOutput(session, String(chunk ?? "")).catch(() => undefined);
+  });
+  child.on("error", (error: Error) => {
+    void appendSessionOutput(session, `\n[process error] ${String(error)}\n`).catch(
+      () => undefined,
+    );
+    void finalizeExitAfterOutputDrain(state, session, -1).catch(() => undefined);
+  });
+  child.on("close", (code: number | null) => {
+    void finalizeExitAfterOutputDrain(
+      state,
+      session,
+      typeof code === "number" ? code : -1,
+    ).catch(() => undefined);
+  });
+}

package/src/shell/runtime/ShellRuntimeEnvironment.ts

@@ -0,0 +1,67 @@
+/**
+ * Shell action 运行环境解析辅助。
+ *
+ * 关键点（中文）
+ * - 集中处理 shell 子进程 cwd、env 与 owner context 的解析。
+ * - 这里只做输入归一化，不持有 shell session 状态。
+ */
+
+import path from "node:path";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import { stripInvocationAuthEnv } from "@downcity/agent/internal/runtime/server/http/auth/AuthEnv.js";
+import { getSessionRunScope } from "@downcity/agent/internal/executor/SessionRunScope.js";
+
+/**
+ * 构造 shell 子进程环境变量。
+ */
+export function buildShellEnv(context: AgentContext): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+
+  // 关键点（中文）
+  // - AgentContext.env 现在就是宿主已经整理好的最终 env 视图。
+  // - shell 只消费这一份显式上下文，避免再次引入 platform/global env 隐式来源。
+  for (const [key, value] of Object.entries(context.env || {})) {
+    const normalizedKey = String(key || "").trim();
+    const normalizedValue = String(value || "").trim();
+    if (!normalizedKey || !normalizedValue) continue;
+    env[normalizedKey] = normalizedValue;
+  }
+
+  const request = getSessionRunScope();
+  const sessionId = String(request?.sessionId || "").trim();
+  const agentPath = String(context.rootPath || "").trim();
+  const configuredAgentName = String(context.config?.name || "").trim();
+  const agentName = configuredAgentName || (agentPath ? path.basename(agentPath) : "");
+
+  // 关键点（中文）
+  // - agent 自己在 shell 里执行 `city <service> ...` 时，也需要显式知道“当前 agent 是谁”。
+  // - 否则 service CLI 会退回到当前终端 cwd / registry 猜测，在多 agent 或外部工作目录下
+  //   很容易把请求发到错误项目，最终误报 “Agent server 没启动”。
+  if (agentPath) env.DC_AGENT_PATH = agentPath;
+  if (agentName) env.DC_AGENT_NAME = agentName;
+  if (sessionId) env.DC_SESSION_ID = sessionId;
+  if (process.env.DC_SERVER_HOST) env.DC_CTX_SERVER_HOST = process.env.DC_SERVER_HOST;
+  if (process.env.DC_SERVER_PORT) env.DC_CTX_SERVER_PORT = process.env.DC_SERVER_PORT;
+  stripInvocationAuthEnv(env);
+
+  return env;
+}
+
+/**
+ * 解析 shell 执行目录。
+ */
+export function resolveShellCwd(context: AgentContext, cwd?: string): string {
+  const raw = String(cwd || "").trim();
+  if (!raw) return context.rootPath;
+  return path.isAbsolute(raw) ? raw : path.resolve(context.rootPath, raw);
+}
+
+/**
+ * 推断 shell 所属的 owner context。
+ */
+export function resolveOwnerContextId(explicit?: string): string | undefined {
+  const fromInput = String(explicit || "").trim();
+  if (fromInput) return fromInput;
+  const fromRequest = String(getSessionRunScope()?.sessionId || "").trim();
+  return fromRequest || undefined;
+}

package/src/skill/Action.ts

@@ -0,0 +1,159 @@
+/**
+ * skill plugin action helper。
+ *
+ * 关键点（中文）
+ * - 与 runtime tool 解耦：CLI / plugin action / server 都可统一复用。
+ * - `lookup` 采用无状态实现：直接返回 `SKILL.md` 内容，不做 pin 持久化。
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import { discoverClaudeSkillsSync } from "@/skill/runtime/Discovery.js";
+import { loadDowncityConfig } from "@downcity/agent/internal/config/Config.js";
+import type { ClaudeSkill } from "@/skill/types/ClaudeSkill.js";
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+import type {
+  SkillListResponse,
+  SkillLookupRequest,
+  SkillLookupResponse,
+  SkillSummary,
+} from "@/skill/types/SkillCommand.js";
+
+function normalizeAllowedTools(input: JsonValue | undefined): string[] {
+  if (!Array.isArray(input)) return [];
+  const values: string[] = [];
+  for (const item of input) {
+    const value = typeof item === "string" ? item.trim() : "";
+    if (!value) continue;
+    values.push(value);
+  }
+  return Array.from(new Set(values));
+}
+
+function toSkillSummary(skill: ClaudeSkill): SkillSummary {
+  return {
+    id: skill.id,
+    name: skill.name,
+    description: skill.description || "",
+    source: skill.source,
+    skillMdPath: skill.skillMdPath,
+    allowedTools: normalizeAllowedTools(skill.allowedTools),
+  };
+}
+
+function findSkillExact(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
+  const q = String(name || "").trim().toLowerCase();
+  if (!q) return null;
+
+  return (
+    skills.find((item) => item.id.toLowerCase() === q) ||
+    skills.find((item) => item.name.toLowerCase() === q) ||
+    null
+  );
+}
+
+function findSkill(skills: ClaudeSkill[], name: string): ClaudeSkill | null {
+  const q = String(name || "").trim().toLowerCase();
+  if (!q) return null;
+
+  return (
+    skills.find((item) => item.id.toLowerCase() === q) ||
+    skills.find((item) => item.name.toLowerCase() === q) ||
+    skills.find((item) => item.name.toLowerCase().includes(q)) ||
+    null
+  );
+}
+
+function getSkills(projectRoot: string): ClaudeSkill[] {
+  const root = path.resolve(projectRoot);
+  const config = loadDowncityConfig(root);
+  return discoverClaudeSkillsSync(root, config);
+}
+
+/**
+ * 在“已学会（本地可发现）”技能里做精确匹配。
+ */
+export function findLearnedSkillExact(
+  projectRoot: string,
+  query: string,
+): SkillSummary | null {
+  const skills = getSkills(projectRoot);
+  const target = findSkillExact(skills, query);
+  return target ? toSkillSummary(target) : null;
+}
+
+/**
+ * 在“已学会（本地可发现）”技能里做模糊搜索。
+ */
+export function searchLearnedSkills(
+  projectRoot: string,
+  query: string,
+  limit: number = 10,
+): SkillSummary[] {
+  const q = String(query || "").trim().toLowerCase();
+  if (!q) return [];
+
+  const skills = getSkills(projectRoot);
+  const matched = skills.filter((item) => {
+    const id = item.id.toLowerCase();
+    const name = item.name.toLowerCase();
+    const description = String(item.description || "").toLowerCase();
+    return id.includes(q) || name.includes(q) || description.includes(q);
+  });
+
+  return matched.slice(0, Math.max(1, limit)).map(toSkillSummary);
+}
+
+/**
+ * 列出当前项目下可发现的全部 skill。
+ */
+export function listSkills(projectRoot: string): SkillListResponse {
+  const skills = getSkills(projectRoot).map(toSkillSummary);
+  return {
+    success: true,
+    skills,
+  };
+}
+
+/**
+ * 读取指定 skill 的正文内容。
+ */
+export async function lookupSkill(params: {
+  /**
+   * 项目根目录。
+   */
+  projectRoot: string;
+  /**
+   * skill lookup 请求。
+   */
+  request: SkillLookupRequest;
+}): Promise<SkillLookupResponse> {
+  const root = path.resolve(params.projectRoot);
+  const skills = getSkills(root);
+  const target = findSkill(skills, params.request.name);
+  if (!target) {
+    return {
+      success: false,
+      error: `Skill not found: ${params.request.name}`,
+    };
+  }
+
+  let content = "";
+  try {
+    content = String(await fs.readFile(target.skillMdPath, "utf-8")).trim();
+  } catch {
+    content = "";
+  }
+  if (!content) {
+    return {
+      success: false,
+      error: `Skill content is empty: ${target.id}`,
+    };
+  }
+
+  return {
+    success: true,
+    skill: toSkillSummary(target),
+    content,
+  };
+}