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

package/dist/sandbox.js

@@ -0,0 +1,96 @@
+/**
+ * Sandbox contract `sandbox@1`: a single-select, brokered extension point (extensions may not
+ * `requires` it; the kernel's `SandboxService` consumes it). The provider implements only the
+ * primitives below; the kernel builds `glob` / `grep` / `edit` from `exec` plus `readFile` /
+ * `writeFile`.
+ */
+/** Sandbox extension point ref. */
+export const SANDBOX_EXTENSION_POINT = "sandbox@1";
+/** 沙箱内允许模型访问的根目录。 */
+export const SANDBOX_ROOTS = ["/workspace", "/skills", "/tmp"];
+const MAX_PATH_LENGTH = 4096;
+/**
+ * 实例在提供方那边确定已经不在了（容器被删、E2B 沙箱过期）。`exec` / `readFile` / `writeFile` / `stat`
+ * 发现实例不在时必须抛它（而不是普通 Error），内核据此重建沙箱并重试一次；只是暂时连不上时抛普通错误。
+ */
+export class SandboxGoneError extends Error {
+    sandboxGone = true;
+    constructor(message, opts) {
+        super(message, opts && "cause" in opts ? { cause: opts.cause } : undefined);
+        this.name = "SandboxGoneError";
+    }
+}
+/** 鸭子类型判断（不用 instanceof），兼容插件自带另一份 plugin-sdk 副本的情况。 */
+export function isSandboxGoneError(e) {
+    return (e instanceof Error &&
+        e.name === "SandboxGoneError" &&
+        e.sandboxGone === true);
+}
+/**
+ * A holder tag (`exec` argument `tag`, {@link SandboxProvider.killTagged}): the kernel passes its
+ * lease tokens (UUIDs). Providers check tags against it before putting them in a command line or a
+ * kill pattern.
+ */
+export const SANDBOX_TAG_RE = /^[a-z0-9-]{1,64}$/;
+// biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拦控制字符
+const CONTROL = /[\u0000-\u001f\u007f]/;
+/** 校验沙箱内路径：返回错误列表，空数组表示合法。 */
+export function validateSandboxPath(p) {
+    if (typeof p !== "string" || p.length === 0)
+        return ["path must be a non-empty string"];
+    if (p.length > MAX_PATH_LENGTH)
+        return [`path must be at most ${MAX_PATH_LENGTH} characters`];
+    if (CONTROL.test(p))
+        return ["path must not contain control characters"];
+    if (p.includes("\\"))
+        return ["path must not contain backslashes"];
+    if (!p.startsWith("/"))
+        return ["path must be absolute"];
+    if (p.includes("//"))
+        return ["path must not contain empty segments"];
+    const errors = [];
+    for (const seg of p.split("/")) {
+        let decoded = seg;
+        try {
+            decoded = decodeURIComponent(seg);
+        }
+        catch {
+            // 非法百分号编码按字面处理
+        }
+        if (seg === ".." || decoded === ".." || decoded.includes("/") || decoded.includes("\\")) {
+            errors.push("path must not contain '..' segments");
+            break;
+        }
+    }
+    if (!SANDBOX_ROOTS.some((r) => p === r || p.startsWith(`${r}/`))) {
+        errors.push(`path must be under ${SANDBOX_ROOTS.join(", ")}`);
+    }
+    return errors;
+}
+const LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+/** 校验出站白名单主机名：小写、无协议与端口、可选前导 `*.`、IDN 只认 punycode。 */
+export function validateAllowHost(h) {
+    if (typeof h !== "string" || h.length === 0)
+        return ["host must be a non-empty string"];
+    if (h.length > 253)
+        return ["host must be at most 253 characters"];
+    const name = h.startsWith("*.") ? h.slice(2) : h;
+    if (name.length === 0)
+        return ["wildcard must be followed by a domain"];
+    const labels = name.split(".");
+    if (labels.every((l) => LABEL.test(l))) {
+        const tld = labels[labels.length - 1];
+        if (labels.length < 2)
+            return ["host must have at least two labels (no single-label names)"];
+        // 末段必须以字母开头：挡住 IPv4 的十进制 / 八进制 / 十六进制写法
+        if (!/^[a-z]/.test(tld))
+            return ["host must not be an IP address literal"];
+        if (["local", "internal", "localhost"].includes(tld)) {
+            return ["host must not be in an internal-only domain (.local, .internal, .localhost)"];
+        }
+        return [];
+    }
+    return [
+        "host must be a lowercase hostname without scheme, port or path (optional leading '*.'; IDN as punycode)",
+    ];
+}

package/dist/secret.d.ts

@@ -0,0 +1,5 @@
+import type { z } from "zod";
+/** 标记一个 schema 为敏感字段（Zod 4 meta `{ secret: true }`）。 */
+export declare function secret<T extends z.ZodTypeAny>(schema: T): T;
+/** 读取 schema 的 meta，判断是否敏感；内核 `meta({secret:true})` 同样可识别。 */
+export declare function isSecret(schema: z.ZodTypeAny): boolean;

package/dist/secret.js

@@ -0,0 +1,8 @@
+/** 标记一个 schema 为敏感字段（Zod 4 meta `{ secret: true }`）。 */
+export function secret(schema) {
+    return schema.meta({ secret: true });
+}
+/** 读取 schema 的 meta，判断是否敏感；内核 `meta({secret:true})` 同样可识别。 */
+export function isSecret(schema) {
+    return schema.meta()?.secret === true;
+}

package/dist/semver-range.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Internal helper (not exported from index.ts): whether a semver range has an upper bound, i.e.
+ * every comparator set (each `||` branch) has at least one `<` / `<=` or an exact version. Ranges
+ * such as `*`, `x` or `>=1.0.0` would treat a future major SDK as compatible.
+ */
+export declare function hasUpperBound(range: string): boolean;

package/dist/semver-range.js

@@ -0,0 +1,12 @@
+import semver from "semver";
+/**
+ * Internal helper (not exported from index.ts): whether a semver range has an upper bound, i.e.
+ * every comparator set (each `||` branch) has at least one `<` / `<=` or an exact version. Ranges
+ * such as `*`, `x` or `>=1.0.0` would treat a future major SDK as compatible.
+ */
+export function hasUpperBound(range) {
+    const r = new semver.Range(range);
+    return r.set.every((comparators) => comparators.some((c) => c.operator === "<" ||
+        c.operator === "<=" ||
+        ((c.operator === "" || c.operator === "=") && c.value !== "")));
+}

package/dist/skill-invocation.d.ts

@@ -0,0 +1,83 @@
+/** How a skill can be invoked, read from its SKILL.md frontmatter by {@link skillInvocation}. */
+export interface SkillInvocation {
+    /** false: `disable-model-invocation: true` (manual-only, left out of the model's catalog). */
+    model: boolean;
+    /** false: `user-invocable: false` (hidden from the `/` menu). */
+    user: boolean;
+    /** `context: fork`: runs as a sub-agent when a person invokes it; `agent` as written. */
+    fork?: {
+        agent?: string;
+    };
+    /** `argument-hint`, shown after the skill's name in the `/` menu. */
+    argumentHint?: string;
+    /** `arguments`: the names usable as `$name` in the body, in positional order. */
+    arguments?: string[];
+}
+/**
+ * The invocation metadata of a SKILL.md frontmatter. Values of the wrong type are ignored here
+ * (`parseSkillMd` reports them as errors), so this never throws.
+ */
+export declare function skillInvocation(frontmatter: Readonly<Record<string, unknown>>): SkillInvocation;
+/**
+ * Splits an argument string like a shell: whitespace separates values, double and single quotes
+ * group (`"hello world"` is one value), a backslash outside single quotes escapes the next
+ * character (inside double quotes only `"` and `\`). An unclosed quote runs to the end.
+ */
+export declare function parseSkillArguments(args: string): string[];
+/**
+ * A skill body with its arguments substituted (see the file header), without the wrapper.
+ * `skillName` is the resolved skill's bare name: `${CLAUDE_SKILL_DIR}` becomes
+ * `/skills/<skillName>` (a qualified `<plugin>:<name>` throws a `TypeError`). `args` is trimmed;
+ * more than {@link SKILL_INVOCATION_LIMITS.argumentsMaxChars} characters throw a `RangeError`, and
+ * so does a result longer than {@link SKILL_INVOCATION_LIMITS.renderedMaxChars} (checked while
+ * substituting, before the long string is built).
+ */
+export declare function renderSkillBody(body: string, invocation: SkillInvocation, args: string, skillName: string): string;
+/** Input of {@link renderSkillInvocation}. */
+export interface RenderSkillInvocationInput {
+    /**
+     * The name the person typed after `/` (`fix-issue`, or `<plugin>:<name>`): used in the lead, the
+     * `name="…"` attribute and the `skill_load` argument (where the qualified form resolves).
+     */
+    name: string;
+    /**
+     * The resolved skill's bare name (never `<plugin>:<name>`): its sandbox directory
+     * `/skills/<skillName>/`, used for `${CLAUDE_SKILL_DIR}` and the files line.
+     */
+    skillName: string;
+    version: number;
+    /** The SKILL.md body (after the frontmatter). */
+    body: string;
+    invocation: SkillInvocation;
+    /** The text after `/name`. */
+    args: string;
+    /** Decided by the caller from the agent's tools and the version's manifest. */
+    lines: {
+        /** The version has files besides SKILL.md: `load` when the agent has `skill_load`. */
+        files?: "load" | "unavailable";
+        /** The body has shell injections and the agent has `sandbox_bash`. */
+        shellHint?: boolean;
+    };
+    /** false: leave out the lead sentence (a forked skill's task for the sub-agent). Default true. */
+    lead?: boolean;
+}
+/**
+ * Both `skill_invocation` wrapper tags made inert (`<\/skill_invocation`, `<\skill_invocation`, any
+ * case), for text outside the wrapper that quotes a person's input: the inline lead here, and the
+ * kernel's fork lead.
+ */
+export declare const escapeSkillInvocationTags: (s: string) => string;
+/**
+ * The model-visible text of an inline skill invocation: the lead sentence, the rendered body inside
+ * `<skill_invocation name="…" version="…">`, then the optional files and shell lines. A closing
+ * tag inside the body is written `<\/skill_invocation` so the wrapper cannot be closed early; in the
+ * lead (which quotes the arguments as typed) both tags are made inert (`<\/skill_invocation`,
+ * `<\skill_invocation`), and the `name` attribute escapes `&`, `"` and `<`. Throws like
+ * {@link renderSkillBody}.
+ */
+export declare function renderSkillInvocation(i: RenderSkillInvocationInput): string;
+/**
+ * Whether a skill body has Claude Code shell injections: `` !`command` `` at the start of a line or
+ * after whitespace, or a fenced block opened with ` ```! `.
+ */
+export declare function hasShellInjection(body: string): boolean;

package/dist/skill-invocation.js

@@ -0,0 +1,201 @@
+// biome-ignore-all lint/suspicious/noTemplateCurlyInString: Claude Code variables such as ${CLAUDE_SKILL_DIR} are plain text here
+/**
+ * Manual skill invocation (package ecosystem phase D): a skill's invocation metadata read from its
+ * SKILL.md frontmatter, and the pure rendering of `/name args` into the text the model sees.
+ *
+ * The argument rules follow Claude Code (re-checked 2026-10-27): `$ARGUMENTS` is the whole argument
+ * string, `$ARGUMENTS[N]` / `$N` are 0-based positional values (a missing one stays as written),
+ * `$name` takes its value from frontmatter `arguments` (a missing one becomes empty), `\$` is a
+ * literal `$`, `${CLAUDE_SKILL_DIR}` is `/skills/<name>` and every other `${…}` stays as written.
+ * When the body has no argument placeholder and the arguments are not empty, they are appended as
+ * `ARGUMENTS: <args>`. Substituted text is never scanned again. Nothing is executed: shell
+ * injections (`` !`cmd` ``) stay text, and the model is told how to run them.
+ */
+import { isSkillName, SKILL_INVOCATION_LIMITS, SKILLS_SANDBOX_ROOT } from "./skill.js";
+import { argumentHintText, SKILL_ARGUMENT_NAME_RE } from "./skill-keys.js";
+/**
+ * The invocation metadata of a SKILL.md frontmatter. Values of the wrong type are ignored here
+ * (`parseSkillMd` reports them as errors), so this never throws.
+ */
+export function skillInvocation(frontmatter) {
+    const out = {
+        model: frontmatter["disable-model-invocation"] !== true,
+        user: frontmatter["user-invocable"] !== false,
+    };
+    if (frontmatter.context === "fork") {
+        const agent = frontmatter.agent;
+        out.fork = typeof agent === "string" && agent !== "" ? { agent } : {};
+    }
+    const hint = argumentHintText(frontmatter["argument-hint"]);
+    if (hint !== undefined && hint !== "")
+        out.argumentHint = hint;
+    const names = frontmatter.arguments;
+    if (Array.isArray(names) &&
+        names.length > 0 &&
+        names.every((n) => typeof n === "string" && SKILL_ARGUMENT_NAME_RE.test(n))) {
+        out.arguments = [...names];
+    }
+    return out;
+}
+/**
+ * Splits an argument string like a shell: whitespace separates values, double and single quotes
+ * group (`"hello world"` is one value), a backslash outside single quotes escapes the next
+ * character (inside double quotes only `"` and `\`). An unclosed quote runs to the end.
+ */
+export function parseSkillArguments(args) {
+    const out = [];
+    let cur = "";
+    let has = false;
+    let quote = null;
+    const s = [...args];
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (quote === "'") {
+            if (c === "'")
+                quote = null;
+            else
+                cur += c;
+            continue;
+        }
+        if (quote === '"') {
+            if (c === '"')
+                quote = null;
+            else if (c === "\\" && (s[i + 1] === '"' || s[i + 1] === "\\"))
+                cur += s[++i];
+            else
+                cur += c;
+            continue;
+        }
+        if (c === "'" || c === '"') {
+            quote = c;
+            has = true;
+        }
+        else if (c === "\\" && i + 1 < s.length) {
+            cur += s[++i];
+            has = true;
+        }
+        else if (/\s/.test(c)) {
+            if (has)
+                out.push(cur);
+            cur = "";
+            has = false;
+        }
+        else {
+            cur += c;
+            has = true;
+        }
+    }
+    if (has)
+        out.push(cur);
+    return out;
+}
+const PLACEHOLDER_RE = /\\\$|\$ARGUMENTS\[(\d+)\]|\$ARGUMENTS|\$(\d+)|\$([A-Za-z_][A-Za-z0-9_]*)|\$\{CLAUDE_SKILL_DIR\}/g;
+const trimmedArgs = (args) => {
+    const t = args.trim();
+    if ([...t].length > SKILL_INVOCATION_LIMITS.argumentsMaxChars) {
+        throw new RangeError(`skill arguments must be at most ${SKILL_INVOCATION_LIMITS.argumentsMaxChars} characters`);
+    }
+    return t;
+};
+const checkSkillName = (skillName) => {
+    if (!isSkillName(skillName)) {
+        throw new TypeError(`skillName must be a bare skill name (its directory under ${SKILLS_SANDBOX_ROOT}), got "${skillName}"`);
+    }
+};
+const tooLong = () => new RangeError(`the rendered skill must be at most ${SKILL_INVOCATION_LIMITS.renderedMaxChars} characters`);
+/**
+ * A skill body with its arguments substituted (see the file header), without the wrapper.
+ * `skillName` is the resolved skill's bare name: `${CLAUDE_SKILL_DIR}` becomes
+ * `/skills/<skillName>` (a qualified `<plugin>:<name>` throws a `TypeError`). `args` is trimmed;
+ * more than {@link SKILL_INVOCATION_LIMITS.argumentsMaxChars} characters throw a `RangeError`, and
+ * so does a result longer than {@link SKILL_INVOCATION_LIMITS.renderedMaxChars} (checked while
+ * substituting, before the long string is built).
+ */
+export function renderSkillBody(body, invocation, args, skillName) {
+    checkSkillName(skillName);
+    const all = trimmedArgs(args);
+    const values = parseSkillArguments(all);
+    const named = invocation.arguments ?? [];
+    const max = SKILL_INVOCATION_LIMITS.renderedMaxChars;
+    let placeholder = false;
+    // Output length so far = body consumed up to the match end, minus the matched text, plus what
+    // replaced it.
+    let delta = 0;
+    const replace = (m, idx, pos, word) => {
+        if (m === "\\$")
+            return "$";
+        if (m === "${CLAUDE_SKILL_DIR}")
+            return `${SKILLS_SANDBOX_ROOT}/${skillName}`;
+        if (m === "$ARGUMENTS") {
+            placeholder = true;
+            return all;
+        }
+        const n = idx ?? pos;
+        if (n !== undefined) {
+            placeholder = true;
+            return values[Number(n)] ?? m;
+        }
+        const at = word === undefined ? -1 : named.indexOf(word);
+        if (at < 0)
+            return m;
+        placeholder = true;
+        return values[at] ?? "";
+    };
+    const out = body.replace(PLACEHOLDER_RE, (m, idx, pos, word, offset) => {
+        const r = replace(m, idx, pos, word);
+        delta += r.length - m.length;
+        if (offset + m.length + delta > max)
+            throw tooLong();
+        return r;
+    });
+    const result = !placeholder && all !== "" ? `${out}\n\nARGUMENTS: ${all}` : out;
+    if (result.length > max)
+        throw tooLong();
+    return result;
+}
+const CLOSE_TAG_RE = /<\/(skill_invocation)/gi;
+const OPEN_TAG_RE = /<(skill_invocation)/gi;
+/**
+ * Both `skill_invocation` wrapper tags made inert (`<\/skill_invocation`, `<\skill_invocation`, any
+ * case), for text outside the wrapper that quotes a person's input: the inline lead here, and the
+ * kernel's fork lead.
+ */
+export const escapeSkillInvocationTags = (s) => s.replace(CLOSE_TAG_RE, "<\\/$1").replace(OPEN_TAG_RE, "<\\$1");
+const escapeTags = escapeSkillInvocationTags;
+const escapeAttr = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+/**
+ * The model-visible text of an inline skill invocation: the lead sentence, the rendered body inside
+ * `<skill_invocation name="…" version="…">`, then the optional files and shell lines. A closing
+ * tag inside the body is written `<\/skill_invocation` so the wrapper cannot be closed early; in the
+ * lead (which quotes the arguments as typed) both tags are made inert (`<\/skill_invocation`,
+ * `<\skill_invocation`), and the `name` attribute escapes `&`, `"` and `<`. Throws like
+ * {@link renderSkillBody}.
+ */
+export function renderSkillInvocation(i) {
+    const args = trimmedArgs(i.args);
+    const body = renderSkillBody(i.body, i.invocation, args, i.skillName).replace(CLOSE_TAG_RE, "<\\/$1");
+    const parts = [];
+    if (i.lead !== false) {
+        parts.push(escapeTags(`The user invoked the skill "${i.name}" with /${i.name}${args === "" ? "" : ` ${args}`}. Follow its instructions for this request.`));
+    }
+    parts.push(`<skill_invocation name="${escapeAttr(i.name)}" version="${i.version}">\n${body}\n</skill_invocation>`);
+    if (i.lines.files === "load") {
+        parts.push(`Its files are not in the sandbox yet: call skill_load with "${i.name}" to copy them to ${SKILLS_SANDBOX_ROOT}/${i.skillName}/ before running its scripts.`);
+    }
+    else if (i.lines.files === "unavailable") {
+        parts.push("Its other files are not available in this conversation.");
+    }
+    if (i.lines.shellHint) {
+        parts.push("Lines written as !`command` were meant to run before you read this; run those commands with sandbox_bash if you need their output.");
+    }
+    return parts.join("\n\n");
+}
+const INLINE_SHELL_RE = /(?:^|[ \t])!`[^`\n]+`/m;
+const FENCE_SHELL_RE = /^[ \t]*```!/m;
+/**
+ * Whether a skill body has Claude Code shell injections: `` !`command` `` at the start of a line or
+ * after whitespace, or a fenced block opened with ` ```! `.
+ */
+export function hasShellInjection(body) {
+    return INLINE_SHELL_RE.test(body) || FENCE_SHELL_RE.test(body);
+}

package/dist/skill-keys.d.ts

@@ -0,0 +1,9 @@
+/** Helpers shared by `skill.ts` and `skill-invocation.ts`. Not exported from the package. */
+/** A name in a SKILL.md's `arguments` (referenced as `$name` in the body). */
+export declare const SKILL_ARGUMENT_NAME_RE: RegExp;
+/**
+ * `argument-hint` as text. Claude Code's docs write it unquoted (`argument-hint: [issue-number]`),
+ * which YAML reads as a list: a list of strings and numbers is written back as `[a, b]`.
+ * Undefined for any other value.
+ */
+export declare function argumentHintText(v: unknown): string | undefined;

package/dist/skill-keys.js

@@ -0,0 +1,16 @@
+/** Helpers shared by `skill.ts` and `skill-invocation.ts`. Not exported from the package. */
+/** A name in a SKILL.md's `arguments` (referenced as `$name` in the body). */
+export const SKILL_ARGUMENT_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+/**
+ * `argument-hint` as text. Claude Code's docs write it unquoted (`argument-hint: [issue-number]`),
+ * which YAML reads as a list: a list of strings and numbers is written back as `[a, b]`.
+ * Undefined for any other value.
+ */
+export function argumentHintText(v) {
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v) && v.every((x) => typeof x === "string" || typeof x === "number")) {
+        return `[${v.join(", ")}]`;
+    }
+    return undefined;
+}

package/dist/skill.d.ts

@@ -0,0 +1,77 @@
+/** 技能包的上限。 */
+export declare const SKILL_LIMITS: {
+    readonly nameMaxChars: 64;
+    readonly descriptionMaxChars: 1024;
+    readonly compatibilityMaxChars: 500;
+    /** 单个文件解压后的上限（字节）。 */
+    readonly fileBytes: number;
+    /** 全部文件解压后的总量上限（字节）。 */
+    readonly totalBytes: number;
+    /** 文件数上限。 */
+    readonly maxFiles: 1000;
+    /** 包内相对路径的长度上限（字符）。 */
+    readonly pathMaxChars: 512;
+    /** frontmatter（两条 `---` 之间）的长度上限（字符），超过不做 YAML 解析。 */
+    readonly frontmatterMaxChars: number;
+};
+/** Limits of the invocation keys of a SKILL.md (see `SkillInvocation`). */
+export declare const SKILL_INVOCATION_LIMITS: {
+    /** `argument-hint`, in characters. */
+    readonly argumentHintMaxChars: 200;
+    /** Names in `arguments`. */
+    readonly argumentNames: 20;
+    /** The argument string of one invocation, in characters (after trimming). */
+    readonly argumentsMaxChars: 10000;
+    /**
+     * The rendered body of one invocation (substitutions and the `ARGUMENTS:` line), in UTF-16 code
+     * units: placeholders copy the arguments again for every occurrence, so this bounds the output.
+     */
+    readonly renderedMaxChars: 200000;
+};
+/** 技能入口文件（包根目录，大小写敏感）。 */
+export declare const SKILL_ENTRY_FILE = "SKILL.md";
+/** 沙箱里放技能的根目录：每个技能在 `/skills/<name>/` 下（只读复制）。 */
+export declare const SKILLS_SANDBOX_ROOT = "/skills";
+/** 是否为合法的技能名（见文件头的规范说明）。 */
+export declare function isSkillName(s: unknown): s is string;
+/** 技能文件在沙箱里的路径：`/skills/<name>/<path>`。 */
+export declare function skillSandboxPath(name: string, path: string): string;
+/** {@link parseSkillMd} 成功时的结果。 */
+export interface ParsedSkillMd {
+    name: string;
+    /** 去掉首尾空白。 */
+    description: string;
+    /** frontmatter 之后的 Markdown 正文。 */
+    body: string;
+    /**
+     * The parsed YAML frontmatter mapping: every key, values unchanged (e.g. Claude Code's
+     * `disable-model-invocation`, `context`, `allowed-tools`), for readers that translate them.
+     */
+    frontmatter: Readonly<Record<string, unknown>>;
+}
+/** Options of {@link parseSkillMd}. */
+export interface ParseSkillMdOptions {
+    /**
+     * false: do not check the types of the invocation keys (`disable-model-invocation`, `context`,
+     * ...). For readers of a SKILL.md stored before those checks existed, which must keep loading;
+     * `skillInvocation` ignores values of the wrong type. Default true.
+     */
+    invocationKeys?: boolean;
+}
+/**
+ * 解析 SKILL.md：开头是 `---` 行包住的 YAML frontmatter，之后是正文。容忍 BOM 与 CRLF（正文里的 CRLF 换成 LF）。
+ * 返回 name / description / 正文，或全部问题（英文，可直接给模型或管理员看）。
+ */
+export declare function parseSkillMd(text: string, options?: ParseSkillMdOptions): ParsedSkillMd | {
+    errors: string[];
+};
+/**
+ * 校验技能包的文件清单（路径相对于包根目录，只含文件、不含目录项）：
+ * 根目录必须有 `SKILL.md`；单文件 ≤ {@link SKILL_LIMITS.fileBytes}；总量 ≤ {@link SKILL_LIMITS.totalBytes}；
+ * 文件数 ≤ {@link SKILL_LIMITS.maxFiles}；路径不能越界（绝对路径、`..`、反斜杠、盘符、控制字符），不能重复
+ * （只差大小写也算重复：大小写不敏感的文件系统上会互相覆盖），文件不能与目录同名。返回问题列表，空数组表示合法。
+ */
+export declare function validateSkillPackage(files: {
+    path: string;
+    size: number;
+}[]): string[];