@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

package/dist/tools/builtins/skill-load.js

@@ -0,0 +1,446 @@
+import { createHash } from "node:crypto";
+import { parseSkillMd, SKILL_ENTRY_FILE, SKILLS_SANDBOX_ROOT, skillSandboxPath, ToolError, } from "@capybara-hq/plugin-sdk";
+import { sql } from "kysely";
+import { normalizeStoredDefinition } from "../../agents/definition.js";
+import { ApiError } from "../../errors.js";
+import { latestInvocation } from "../../runtime/context/skills.js";
+import { dispatchOfChildRun } from "../../runtime/subagents/child.js";
+import { resolveSkillForkType } from "../../runtime/subagents/roster.js";
+import { invocationOf, resolveSkills } from "../../skills/catalog.js";
+import { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLease, } from "./sandbox/common.js";
+import { SANDBOX_TOOL_NAMES } from "./sandbox/names.js";
+/**
+ * 内置工具 `skill_load`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
+ * SKILL.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
+ * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
+ *
+ * - 存储里读出的每个文件都按清单的 sha256 核对，不符即拒绝（不把被替换的内容给模型或放进沙箱）。
+ * - 复制记录在内核控制的标记文件（每个技能一个，{@link skillMarkerPath}：`/skills/.capybara/<name>.json`，
+ *   命令用户改不了）：`{ id, version, prefix, files, stale }`。新建 / 重建的沙箱、版本或来源前缀变化、同名换了技能时
+ *   重新复制，否则跳过。
+ * - agent 没有任何沙箱工具时不创建沙箱、不复制（模型也跑不了脚本），只给正文并说明。
+ * - 可执行位：提供方写的文件一律不可执行（0644）。不扩展 `sandbox@1` 的 `writeFile`，而是在结果里告诉模型用解释器
+ *   运行（`sh` / `python3` / `node`）：契约与两个提供方不变，技能包里的 shebang 脚本照样能跑，代价只是不能 `./x`。
+ * - 旧版本多出的文件：`sandbox@1` 没有删除原语，命令用户也删不了 `/skills` 下的文件，所以新版本原地覆盖，
+ *   旧版本独有的文件留在原处、记进标记的 `stale`，每次加载都在结果里列出「不属于当前版本、忽略它们」。
+ */
+/**
+ * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
+ */
+export const SKILLS_MARKER_DIR = `${SKILLS_SANDBOX_ROOT}/.capybara`;
+/** 一个技能的标记文件。 */
+export const skillMarkerPath = (name) => `${SKILLS_MARKER_DIR}/${name}.json`;
+const MARKER_MAX_BYTES = 256 * 1024;
+/** 结果里最多列出的文件数（其余只给数量）。 */
+const MAX_LISTED_FILES = 200;
+/** 「不在目录里」的错误里最多列出的技能名。 */
+const MAX_LISTED_NAMES = 50;
+const SPEC = {
+    name: "skill_load",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["name"],
+    description: "Load a skill from the skills list: returns the skill's instructions " +
+        "(its SKILL.md) and the list of its files. Call it before starting a task that matches a " +
+        "skill's description, then follow the returned instructions. If the skill has scripts or other " +
+        "files, they are copied read-only to /skills/<name>/ in this conversation's sandbox; run scripts " +
+        "there with an interpreter (sh, python3, node). Call it again when the skills list changes or " +
+        "the sandbox was recreated. Do not use it for skills that are not in the list.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                minLength: 1,
+                maxLength: 64,
+                description: 'The skill name exactly as listed, e.g. "pdf-report".',
+            },
+        },
+        required: ["name"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+};
+// ---- 模型可见文案（英文） ----
+const NO_SKILLS_TEXT = "No skills are available in this conversation; do the task without a skill, or ask the user to add one to this agent.";
+const STORAGE_UNAVAILABLE_TEXT = "File storage is temporarily unavailable, so the skill's files cannot be read; retry later.";
+const notInCatalog = (name, skills) => {
+    const names = skills.slice(0, MAX_LISTED_NAMES).map((s) => s.name);
+    const more = skills.length > names.length ? ", …" : "";
+    return `Skill "${clip(name, 80)}" is not in the skills catalog for this conversation; call skill_load with one of the listed names: ${names.join(", ")}${more}.`;
+};
+const removedText = (name) => `Skill "${name}" was removed after the skills list was shown and can no longer be loaded; do the task without it, or ask the user to restore it.`;
+/** Phase D spec §4.4: the line before a forked skill's instructions (model-visible, English). */
+const forkAvailableText = (type) => `This skill is written to run in a sub-agent: call agent with subagent_type "${type}" and a prompt containing these instructions and the details of the task, then use its report; do not follow the instructions yourself.`;
+const FORK_UNAVAILABLE_TEXT = "This skill is written to run in a sub-agent, which is not available here; follow the instructions yourself.";
+const integrityText = (name) => `Skill "${name}" failed an integrity check (its stored files do not match the uploaded package); ask an administrator to upload the skill again.`;
+const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+/** 解析一个技能的标记文件；坏的按没有处理（重新复制）。 */
+function parseMarker(data) {
+    try {
+        const r = JSON.parse(new TextDecoder().decode(data));
+        if (r === null || typeof r !== "object" || Array.isArray(r))
+            return undefined;
+        const e = r;
+        if (typeof e.id !== "string" || typeof e.version !== "number")
+            return undefined;
+        return {
+            id: e.id,
+            version: e.version,
+            ...(typeof e.prefix === "string" && { prefix: e.prefix }),
+            files: strings(e.files),
+            stale: strings(e.stale),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 存储错误 → 给模型的说明（存储不可用可重试）；其余原样抛出。 */
+function storageError(e) {
+    if (e instanceof ApiError && e.code === "storage.unavailable") {
+        return new ToolError(STORAGE_UNAVAILABLE_TEXT);
+    }
+    return e;
+}
+/** A stored skill file is missing or does not match its manifest entry (size, sha256). */
+export class SkillIntegrityError extends Error {
+}
+/**
+ * Reads one skill file and checks it against its manifest entry (size and sha256). A missing or
+ * mismatching object throws {@link SkillIntegrityError}; a storage error is rethrown as is
+ * (`storage.unavailable` from the store). Shared with a person's skill invocation (phase D).
+ */
+export async function readSkillFile(store, key, file, signal) {
+    const got = await store.get(key, signal && { signal });
+    if (!got)
+        throw new SkillIntegrityError(`${key} is missing`);
+    const hash = createHash("sha256");
+    const chunks = [];
+    let n = 0;
+    const reader = got.body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            n += value.byteLength;
+            if (n > file.size)
+                throw new SkillIntegrityError(`${key} is larger than its manifest says`);
+            hash.update(value);
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+    if (n !== file.size || hash.digest("hex") !== file.sha256) {
+        throw new SkillIntegrityError(`${key} does not match its manifest`);
+    }
+    return new Uint8Array(Buffer.concat(chunks));
+}
+/** {@link readSkillFile} for the model: integrity and storage failures become tool errors. */
+async function readVerified(store, key, file, skill, signal) {
+    try {
+        return await readSkillFile(store, key, file, signal);
+    }
+    catch (e) {
+        if (e instanceof SkillIntegrityError)
+            throw new ToolError(integrityText(skill));
+        throw storageError(e);
+    }
+}
+/**
+ * 把技能整个复制到 `/skills/<name>/`（标记命中则跳过）。每个文件按清单核对后写入，全部写完才更新标记：
+ * 中途失败下次整体重来。返回旧版本留下的文件。
+ */
+async function copySkill(s, v) {
+    const { name, id, version } = v.entry;
+    const markerPath = skillMarkerPath(name);
+    let cur;
+    if (!s.reset) {
+        const m = await s.p.readFile(s.h, markerPath, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
+        if (m && !m.truncated)
+            cur = parseMarker(m.data);
+    }
+    if (cur && cur.id === id && cur.version === version && cur.prefix === v.prefix) {
+        return { stale: cur.stale };
+    }
+    for (const f of v.manifest.files) {
+        const data = f.path === SKILL_ENTRY_FILE
+            ? v.entryBytes
+            : await readVerified(v.store, `${v.prefix}${f.path}`, f, name, s.signal);
+        await s.p.writeFile(s.h, skillSandboxPath(name, f.path), data, s.signal);
+    }
+    const files = v.manifest.files.map((f) => f.path);
+    const now = new Set(files);
+    const stale = cur ? [...new Set([...cur.stale, ...cur.files])].filter((p) => !now.has(p)) : [];
+    stale.sort();
+    const entry = { id, version, prefix: v.prefix, files, stale };
+    await s.p.writeFile(s.h, markerPath, new TextEncoder().encode(JSON.stringify(entry)), s.signal);
+    return { stale };
+}
+/** 本步可用的工具里是否有沙箱工具（没有时模型用不了复制进去的文件）。 */
+const hasSandboxTools = (ctx) => (ctx.tools ?? []).some((t) => t.source.kind === "builtin" &&
+    SANDBOX_TOOL_NAMES.includes(t.source.name));
+/** 文件清单（最多 {@link MAX_LISTED_FILES} 行）。 */
+function fileList(files) {
+    const shown = files.slice(0, MAX_LISTED_FILES).map((f) => `- ${f.path} (${f.size} bytes)`);
+    if (files.length > shown.length)
+        shown.push(`- … and ${files.length - shown.length} more files`);
+    return shown.join("\n");
+}
+/**
+ * 目录条目对应的内容，按条目的 `source`（对象前缀，T15）精确解析：先找该技能前缀相同的已生成版本（技能未删除；
+ * 批准时草稿前缀原样成为版本前缀，版本号变了也能找到），再找本对话发起、仍待批准、前缀相同的技能改动（试用草稿：
+ * 没有 `skill_versions` 行，新技能连 `skills` 行都没有）。绝不按版本号解析——被拒绝的草稿与之后别人批准的同号版本
+ * 内容不同。都没有 → undefined（已移除）。
+ */
+export async function findSkillVersion(db, ctx, entry) {
+    const row = await db
+        .selectFrom("skills")
+        .innerJoin("skill_versions", "skill_versions.skill_id", "skills.id")
+        .select(["skills.deleted_at", "skill_versions.manifest", "skill_versions.object_prefix"])
+        .where("skills.id", "=", entry.id)
+        .where("skills.org_id", "=", ctx.orgId)
+        .where("skill_versions.object_prefix", "=", entry.source)
+        .executeTakeFirst();
+    if (row)
+        return row.deleted_at === null ? row : undefined;
+    const draft = await db
+        .selectFrom("skill_change_requests")
+        .select(["proposed_version", "object_prefix"])
+        .where("org_id", "=", ctx.orgId)
+        .where("requested_in_conversation", "=", ctx.conversationId)
+        .where("status", "=", "pending")
+        .where("object_prefix", "=", entry.source)
+        .where(sql `proposed_version ->> 'skillId'`, "=", entry.id)
+        .executeTakeFirst();
+    if (!draft)
+        return undefined;
+    return { manifest: draft.proposed_version.manifest, object_prefix: draft.object_prefix };
+}
+/** A Claude Code style qualified name `<plugin>:<skill>` (phase B, spec §9.3). */
+const QUALIFIED_NAME_RE = /^([a-z0-9][a-z0-9-]{0,63}):(.+)$/;
+/**
+ * The catalog entry for `name`: the skill with exactly that name; else, for `<plugin>:<skill>`,
+ * the skill named `<skill>` whose `plugin` (recorded in the snapshot) is `<plugin>`.
+ */
+function findEntry(skills, name) {
+    const exact = skills.find((s) => s.name === name);
+    if (exact)
+        return exact;
+    const m = QUALIFIED_NAME_RE.exec(name);
+    if (!m)
+        return undefined;
+    return skills.find((s) => s.name === m[2] && s.plugin !== undefined && s.plugin === m[1]);
+}
+/** The definition of the agent version this run uses; undefined without a run. */
+async function runAgent(db, ctx) {
+    if (ctx.runId === undefined)
+        return undefined;
+    const row = await db
+        .selectFrom("runs")
+        .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+        .innerJoin("agent_versions", (j) => j
+        .onRef("agent_versions.agent_id", "=", "conversations.agent_id")
+        .onRef("agent_versions.version", "=", "runs.agent_version"))
+        .select(["conversations.agent_id", "agent_versions.definition"])
+        .where("runs.id", "=", ctx.runId)
+        .where("conversations.org_id", "=", ctx.orgId)
+        .executeTakeFirst();
+    return row
+        ? { agentId: row.agent_id, definition: normalizeStoredDefinition(row.definition) }
+        : undefined;
+}
+/**
+ * Where an invoked skill's effectiveness is checked: the conversation, agent and agent version of
+ * the person's invocation. In a sub-agent's run (a fork's child: its task message carries the
+ * record the kernel wrote at dispatch) that is the PARENT: its conversation, its agent and the
+ * parent run's agent version, so an org-agent child or a trial draft of the parent conversation
+ * resolves as the parent did (final review I1). Undefined without a run.
+ */
+async function invocationScope(db, ctx) {
+    if (ctx.runId === undefined)
+        return undefined;
+    const dispatch = await dispatchOfChildRun(db, ctx.runId);
+    if (!dispatch) {
+        const agent = await runAgent(db, ctx);
+        return agent && { ...agent, conversationId: ctx.conversationId };
+    }
+    const row = await db
+        .selectFrom("runs")
+        .innerJoin("conversations", "conversations.id", "runs.conversation_id")
+        .innerJoin("agent_versions", (j) => j
+        .onRef("agent_versions.agent_id", "=", "conversations.agent_id")
+        .onRef("agent_versions.version", "=", "runs.agent_version"))
+        .select(["conversations.agent_id", "agent_versions.definition"])
+        .where("runs.id", "=", dispatch.parentRunId)
+        .where("conversations.id", "=", dispatch.parentConversationId)
+        .where("conversations.org_id", "=", ctx.orgId)
+        .executeTakeFirst();
+    return row
+        ? {
+            agentId: row.agent_id,
+            definition: normalizeStoredDefinition(row.definition),
+            conversationId: dispatch.parentConversationId,
+        }
+        : undefined;
+}
+/**
+ * Phase D spec §4.4: a name that is not in the snapshot may be a skill a person invoked in this
+ * conversation (a manual-only one never is in the catalog). Resolved from the latest
+ * `user_message.skill` with that name, then checked against the effective skills of the
+ * invocation's scope now ({@link invocationScope}: the parent's for a fork's sub-agent): the same
+ * id and name must still be one (deleted, deselected or replaced by another skill of the same
+ * name → `removed`). `conversationId` is the scope's (a trial draft is found there). Undefined
+ * when nobody invoked it here (A4: the caller says "not in the catalog").
+ */
+async function invokedEntry(db, ctx, name) {
+    // only the `skill` field: a message's content holds the rendered skill (up to 200k characters)
+    const rows = await db
+        .selectFrom("conversation_events")
+        .select(["seq", sql `payload -> 'skill'`.as("skill")])
+        .where("conversation_id", "=", ctx.conversationId)
+        .where("type", "=", "user_message")
+        .where(sql `payload -> 'skill' IS NOT NULL`)
+        .orderBy("seq")
+        .execute();
+    const invoked = latestInvocation(rows.map((r) => ({ type: "user_message", seq: Number(r.seq), payload: { skill: r.skill } })), name);
+    if (!invoked)
+        return undefined;
+    const scope = await invocationScope(db, ctx);
+    if (!scope)
+        return "removed";
+    const effective = await resolveSkills(db, {
+        orgId: ctx.orgId,
+        agentId: scope.agentId,
+        agent: scope.definition,
+        conversationId: scope.conversationId,
+    });
+    if (!effective.some((r) => r.skill.id === invoked.id && r.skill.name === invoked.name)) {
+        return "removed";
+    }
+    return {
+        entry: {
+            id: invoked.id,
+            name: invoked.name,
+            description: "",
+            version: invoked.version,
+            source: invoked.source,
+            ...(invoked.plugin !== undefined && { plugin: invoked.plugin }),
+        },
+        conversationId: scope.conversationId,
+    };
+}
+/**
+ * The line before a forked skill's instructions (spec §4.4): run it through `agent` when this step
+ * offers the tool and the skill's type is in the agent's roster, else follow it yourself.
+ */
+async function forkLine(db, ctx, fork, plugin) {
+    const hasAgent = (ctx.tools ?? []).some((t) => t.source.kind === "builtin" && t.source.name === "agent");
+    if (!hasAgent)
+        return FORK_UNAVAILABLE_TEXT;
+    const agent = await runAgent(db, ctx);
+    if (!agent)
+        return FORK_UNAVAILABLE_TEXT;
+    const type = await resolveSkillForkType(db, ctx.orgId, agent.definition, fork.agent, plugin);
+    return type.inRoster ? forkAvailableText(type.agentType) : FORK_UNAVAILABLE_TEXT;
+}
+/** 内置工具 `skill_load`（见文件头）。 */
+export function skillLoadTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        // 可能要创建 / 恢复沙箱并复制文件：与沙箱工具同一时限
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        async run(input, ctx) {
+            const asked = input.name;
+            const snap = await deps.eventLog.latestOfType(ctx.conversationId, "skills_catalog");
+            const skills = snap?.payload.skills ?? [];
+            let entry = findEntry(skills, asked);
+            // a trial draft is looked up in the conversation where the skill resolved
+            let draftConversation = ctx.conversationId;
+            if (!entry) {
+                // phase D: a skill a person invoked here (manual-only skills are never in the catalog)
+                const invoked = await invokedEntry(deps.db, ctx, asked);
+                if (invoked === "removed")
+                    throw new ToolError(removedText(asked));
+                if (invoked) {
+                    entry = invoked.entry;
+                    draftConversation = invoked.conversationId;
+                }
+            }
+            if (!entry && skills.length === 0)
+                throw new ToolError(NO_SKILLS_TEXT);
+            if (!entry)
+                throw new ToolError(notInCatalog(asked, skills));
+            const name = entry.name;
+            const row = await findSkillVersion(deps.db, { orgId: ctx.orgId, conversationId: draftConversation }, entry);
+            if (!row)
+                throw new ToolError(removedText(name));
+            const manifest = row.manifest;
+            const store = deps.storage.kernel(ctx.orgId);
+            const prefix = row.object_prefix;
+            const md = manifest.files.find((f) => f.path === SKILL_ENTRY_FILE);
+            if (!md)
+                throw new ToolError(integrityText(name));
+            const mdBytes = await readVerified(store, `${prefix}${md.path}`, md, name, ctx.signal);
+            const v = { entry, manifest, prefix, store, entryBytes: mdBytes };
+            let parsed;
+            try {
+                parsed = parseSkillMd(new TextDecoder("utf-8", { fatal: true }).decode(mdBytes), {
+                    invocationKeys: false,
+                });
+            }
+            catch {
+                throw new ToolError(integrityText(name));
+            }
+            if ("errors" in parsed)
+                throw new ToolError(integrityText(name));
+            const dir = `${SKILLS_SANDBOX_ROOT}/${name}/`;
+            const others = manifest.files.filter((f) => f.path !== SKILL_ENTRY_FILE);
+            let notices = [];
+            let filesText;
+            if (others.length === 0) {
+                filesText = "This skill has no files besides its instructions.";
+            }
+            else if (!deps.sandbox.available) {
+                filesText =
+                    `Skill files (for reference):\n${fileList(manifest.files)}\n` +
+                        "This deployment has no sandbox, so the skill's scripts and other files are not available; " +
+                        "follow the instructions without running them.";
+            }
+            else if (!hasSandboxTools(ctx)) {
+                // 模型跑不了脚本：不为它创建沙箱、不复制
+                filesText =
+                    `Skill files (for reference):\n${fileList(manifest.files)}\n` +
+                        "This agent has no sandbox tools, so the skill's scripts and other files cannot be run; " +
+                        "follow the instructions in the body without them.";
+            }
+            else {
+                // the skill's marker is read, compared and written: one holder at a time per skill
+                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, ctx, skillMarkerPath(v.entry.name), s.signal, (signal) => copySkill({ ...s, signal }, v)));
+                notices = r.notices;
+                const stale = r.value.stale.length > 0
+                    ? `\nFiles left over from an earlier version (not part of this version; ignore them): ${r.value.stale.join(", ")}`
+                    : "";
+                filesText =
+                    `Skill files (copied to ${dir} in the sandbox, read-only):\n${fileList(manifest.files)}\n` +
+                        `Run scripts with an interpreter, e.g. \`sh ${dir}<script>.sh\`, \`python3 ${dir}<script>.py\` ` +
+                        "or `node`; the files are not executable, so `./script` does not work. Write outputs under " +
+                        `/workspace, not ${SKILLS_SANDBOX_ROOT}.${stale}`;
+            }
+            const fork = invocationOf(manifest).fork;
+            const text = [
+                ...(fork ? [await forkLine(deps.db, ctx, fork, entry.plugin)] : []),
+                `Loaded skill "${name}" (version ${entry.version}).`,
+                filesText,
+                `<skill name="${name}" version="${entry.version}">\n${parsed.body.trim()}\n</skill>`,
+            ].join("\n\n");
+            return {
+                content: [{ type: "text", text: withNotices(notices, text) }],
+                display: display(`加载技能 ${name}（版本 ${entry.version}）`, `Loaded skill ${name} (version ${entry.version})`),
+            };
+        },
+    };
+}

package/dist/tools/builtins/skill-write.d.ts

@@ -0,0 +1,59 @@
+import type { SkillManifest } from "../../db/kernel-schema.js";
+import type { SkillChangesService } from "../../skills/changes.service.js";
+import type { BuiltinTool } from "../registry.js";
+/**
+ * 内置工具 `skill_write`（M5 T15，R4）：agent 新建或更新它自己的技能（`scope = agent`）。
+ * - 输入 `{ name, description, files: [{ path, content }] }`，只收文本文件，整个技能 ≤ {@link SKILL_WRITE_MAX_BYTES}；
+ * - the kernel generates SKILL.md ({@link buildSkillWrite}): its frontmatter is `name` / `description`
+ *   plus the invocation keys (`disable-model-invocation`, `context`, ... phase D) of the frontmatter
+ *   of the `SKILL.md` entry in `files`, whose other keys are dropped; its body is that entry's body
+ *   (empty without the entry);
+ * - 每次调用写一个完整的新版本（上一版有、这次没给的文件不再属于新版本）；
+ * - 私有 agent 直接生成新版本并立即生效；共享 agent 由触发对话的人先确认这次调用（R3 固定 ask，见 tools/policy.ts），
+ *   再生成变更申请等负责人批准，期间只有本对话试用新版本（见 skills/changes.service.ts）；
+ * - 成功后立即在日志追加技能目录快照（`skills_catalog`，Ruling M17），同一运行的下一步就能 `skill_load`。
+ */
+/** 一个技能（含合成的 SKILL.md）的总大小上限（UTF-8 字节）。 */
+export declare const SKILL_WRITE_MAX_BYTES: number;
+/** 一次最多的文件数（含 SKILL.md）。 */
+export declare const SKILL_WRITE_MAX_FILES = 200;
+/** `skill_write` 的输入（已按 inputSchema 校验）。 */
+export interface SkillWriteInput {
+    name: string;
+    description: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+}
+/** 一个待写入的文件。 */
+export interface BuiltSkillFile {
+    path: string;
+    data: Uint8Array;
+    size: number;
+    sha256: string;
+}
+/** {@link buildSkillWrite} 成功的结果。 */
+export interface BuiltSkill {
+    name: string;
+    description: string;
+    files: BuiltSkillFile[];
+    manifest: SkillManifest;
+}
+/**
+ * 由工具输入合成技能文件（纯函数）：
+ * - SKILL.md = `---\n<yaml name/description>---\n\n<正文>\n`，正文为 `files` 里 `SKILL.md` 的内容去掉 frontmatter、
+ *   去掉首尾空行；合成结果再用 `parseSkillMd` 校验（名字规则、描述长度、不含 XML 标签）；
+ * - 其余文件按 `validateSkillPackage` 校验路径（不能越出 `/skills/<name>/`、不能重复、大小写冲突等）；
+ * - 只收文本：内容含 NUL 视为二进制，拒绝；全部文件（含 SKILL.md）的 UTF-8 字节数之和 ≤ {@link SKILL_WRITE_MAX_BYTES}。
+ * 返回合成结果或全部问题（英文，直接给模型）。
+ */
+export declare function buildSkillWrite(input: SkillWriteInput): BuiltSkill | {
+    errors: string[];
+};
+/** 依赖：技能变更服务。 */
+export interface SkillWriteDeps {
+    changes: Pick<SkillChangesService, "write">;
+}
+/** 内置工具 `skill_write`（见文件头）。 */
+export declare function skillWriteTool(deps: SkillWriteDeps): BuiltinTool;