@team-harness/memory-algorithms 0.1.0

package/dist/upstream/core/skill/skill-extractor.js

@@ -0,0 +1,432 @@
+/**
+ * SkillExtractor — 接受结构化 ExtractMessage[] 的抽取入口
+ *
+ * 与旧 SkillExtractor 的差异：
+ *   - 入参 messages 必须是 `ExtractMessage[]`，不再接受裸字符串
+ *   - 内部把 messages 串成 transcript（保留 role 标记）
+ *   - 工具调用走 SkillToolsV2（操作 SkillCore）
+ *   - 候选返回 ExtractedSkillCandidate 形态（含 skill_id / version）
+ *
+ * 每次调用都走 LLM，不做任何对话级去重/缓存 —— 缓存机制已移除。
+ */
+import { createSkillTools } from "./skill-tools.js";
+import { metricProducer, trace, obsLogger } from "../../../runtime/telemetry.js";
+const TAG = "[skill-extractor]";
+export class SkillExtractor {
+    core;
+    runner;
+    systemPrompt;
+    maxIterations;
+    headChars;
+    tailChars;
+    maxTokens;
+    prefixSkillsLimit;
+    logger;
+    constructor(opts) {
+        this.core = opts.core;
+        this.runner = opts.runner;
+        this.systemPrompt = opts.systemPrompt ?? "You are a Skill Review Agent. Use tools to look at existing skills, decide what to add/improve, and call skill_create / skill_update / skill_patch / skill_files_write to persist.";
+        this.maxIterations = opts.maxIterations ?? 16;
+        this.headChars = opts.headChars ?? 8000;
+        this.tailChars = opts.tailChars ?? 32000;
+        this.maxTokens = opts.maxTokens;
+        // 构造器默认 0 (关闭前缀注入 → 不会触发额外的 query-gen LLM 调用);
+        // 生产 wiring 会显式传入 resolved.extraction.prefixSkillsLimit (默认 20)。
+        // <0 或非数字回落到 0 (等价于关闭), 而不是静默改到 20 —— 不想让配置错误
+        // 变成"意外多花一次 LLM"。
+        const rawLimit = opts.prefixSkillsLimit;
+        this.prefixSkillsLimit = rawLimit === undefined
+            ? 0
+            : (Number.isFinite(rawLimit) && rawLimit >= 0 ? Math.floor(rawLimit) : 0);
+        this.logger = opts.logger;
+    }
+    async extract(input) {
+        const { messages } = input;
+        if (!Array.isArray(messages) || messages.length === 0) {
+            throw new Error("ExtractV2: messages must be a non-empty array of ExtractMessage");
+        }
+        // [obs] 一次抽取一条汇总事件；LLM 内部 iteration 走 langfuse trace（trace.report
+        // → OTel Span → Langfuse SpanProcessor 过滤上报），这里只做「入口→出口」
+        // 的耗时 / 候选数量汇总，用 task_id 做 anchor 跟 worker 段对齐。obsLogger
+        // 内部 try/catch + FileLogger + 后端降级，logger 挂了也不影响抽取本身。
+        const t0 = Date.now();
+        const transcript = formatTranscript(messages);
+        const truncated = truncateHeadTail(transcript, this.headChars, this.tailChars);
+        // 预检索 skill 列表, 塞在 user prompt 前面, 让 review agent 一进场就能看到
+        // agent 自己已经拥有哪些 skill (避免盲目 skill_create 撞 SKILL_NAME_DUPLICATE)。
+        //
+        // 三种模式, 由 prefixSkillsLimit + 该 agent 拥有的 skill 总数联合决定:
+        //   full     — total ≤ limit: 全部注入; 不花 query-gen LLM。
+        //   relevant — total > limit + query-gen 成功 + BM25 命中 ≥1: 相关性优先。
+        //   recent   — total > limit + relevant 失败 (query-gen 抛 / 空 / 命中 0):
+        //              退回按 updated_at DESC 的 top-N + "还有 X 条未显示" 提示。
+        //   none     — prefixSkillsLimit=0 或 total=0。
+        //
+        // 关键: 一次 core.list({ limit }) 同时拿到 items + total, 之后所有分支复用,
+        // 不再二次查库; total ≤ limit 的场景直接跳过 query-gen, 覆盖率反而更高。
+        let prefixBlock = "";
+        let prefixMode = "none";
+        let prefixQuery;
+        if (this.prefixSkillsLimit > 0) {
+            let recentPage = null;
+            try {
+                recentPage = await this.core.list({
+                    user_id: input.user_id,
+                    team_id: input.team_id,
+                    agent_id: input.agent_id,
+                    pagination: { limit: this.prefixSkillsLimit },
+                });
+            }
+            catch (e) {
+                // list 挂 → 后续分支也没数据可用, 直接进 none 分支。
+                this.logger?.warn(`${TAG} prefix list failed: ${e.message}`);
+            }
+            if (recentPage && recentPage.items.length > 0) {
+                if (recentPage.total <= this.prefixSkillsLimit) {
+                    // Case full: 拿到全部, 直接铺开; query-gen 完全省掉。
+                    prefixBlock = renderFullSkillsBlock(recentPage.items);
+                    prefixMode = "full";
+                }
+                else {
+                    // Case relevant: total 超 limit, 花一次 LLM query-gen + BM25 找最相关的。
+                    try {
+                        const relevant = await this.buildRelevantSkillsBlock(input, truncated);
+                        if (relevant) {
+                            prefixBlock = relevant.block;
+                            prefixMode = "relevant";
+                            prefixQuery = relevant.query;
+                        }
+                    }
+                    catch (e) {
+                        this.logger?.warn(`${TAG} buildRelevantSkillsBlock failed: ${e.message}`);
+                    }
+                    if (!prefixBlock) {
+                        // Case recent: relevant 失败, 用一开始拿到的 top-N 兜底, 附带
+                        // "还有 X 条未显示" 提示让 LLM 知道自己可以 skill_list 手动补拉。
+                        prefixBlock = renderRecentSkillsBlock(recentPage.items, recentPage.total);
+                        prefixMode = "recent";
+                    }
+                }
+            }
+        }
+        let prompt = prefixBlock ? `${prefixBlock}\n\n---\n\n${truncated}` : truncated;
+        // 主 Agent 注入抽取提示（reason 非空时放在 prompt 最前面）
+        if (input.reason && input.reason.trim().length > 0) {
+            const hintBlock = [
+                "## 主 Agent 的抽取提示",
+                "以下是主 Agent 对本次对话的说明，请重点参考其意图进行抽取：",
+                input.reason,
+            ].join("\n");
+            prompt = `${hintBlock}\n\n---\n\n${prompt}`;
+        }
+        const auditSink = [];
+        if (!this.runner) {
+            // No runner injected (test environment / disabled) → 返回空候选
+            this.logger?.info(`${TAG} no runner provided; returning empty candidates`);
+            obsLogger.info("skill.extractor.extract", {
+                task_id: input.task_id,
+                dur_ms: Date.now() - t0,
+                msg_count: messages.length,
+                candidates: 0,
+                skipped: "no_runner",
+            });
+            return { candidates: [] };
+        }
+        const tools = createSkillTools({
+            core: this.core,
+            user_id: input.user_id,
+            team_id: input.team_id,
+            agent_id: input.agent_id,
+            task_id: input.task_id,
+            auditSink,
+            logger: this.logger,
+        });
+        let text;
+        try {
+            text = await this.runner.run({
+                prompt,
+                systemPrompt: this.systemPrompt,
+                tools,
+                enableTools: true,
+                maxIterations: input.options?.max_iterations ?? this.maxIterations,
+                maxTokens: this.maxTokens,
+                taskId: `skill-extract-${input.task_id ?? "unknown"}`,
+                // Langfuse trace 语义：让此次抽取在 Langfuse UI 有稳定 name / 可筛选 tags。
+                // 详见 core/types.ts LLMRunParams 的 traceName/tags/sessionId/userId 注释。
+                traceName: "skill.extract",
+                tags: [
+                    "skill-extract",
+                    `team:${input.team_id}`,
+                    `agent:${input.agent_id}`,
+                ],
+                sessionId: input.session_id,
+                userId: input.user_id,
+                instanceId: input.space_id,
+            });
+        }
+        catch (e) {
+            // 一条 warn 汇总失败，包含 task_id / err_name / dur —— Worker 侧再按分类
+            // (transient / permanent) 决定 requeue 还是 DLQ。这里不吞异常。
+            const dur = Date.now() - t0;
+            obsLogger.warn("skill.extractor.extract", {
+                task_id: input.task_id,
+                dur_ms: dur,
+                msg_count: messages.length,
+                candidates: auditSink.length,
+                err_name: e.name,
+                err_msg: e.message,
+            });
+            try {
+                trace.report("skill.extractor.extract", {
+                    task_id: input.task_id,
+                    team_id: input.team_id,
+                    agent_id: input.agent_id,
+                    session_id: input.session_id,
+                    msg_count: messages.length,
+                    candidates: auditSink.length,
+                    dur_ms: dur,
+                    success: false,
+                    error: e.message,
+                });
+            }
+            catch { /* noop */ }
+            throw e;
+        }
+        try {
+            metricProducer.send({ metric: "skill.extract.candidates", instanceId: input.team_id, value: auditSink.length });
+        }
+        catch { /* noop */ }
+        const dur = Date.now() - t0;
+        obsLogger.info("skill.extractor.extract", {
+            task_id: input.task_id,
+            dur_ms: dur,
+            msg_count: messages.length,
+            candidates: auditSink.length,
+            prompt_chars: prompt.length,
+            prefix_mode: prefixMode,
+            // 只截前 60 字符 (够识别关键词; 长了对 obs 无用)。
+            prefix_query: prefixQuery ? prefixQuery.slice(0, 60) : undefined,
+        });
+        try {
+            trace.report("skill.extractor.extract", {
+                task_id: input.task_id,
+                team_id: input.team_id,
+                agent_id: input.agent_id,
+                session_id: input.session_id,
+                msg_count: messages.length,
+                candidates: auditSink.length,
+                prompt_chars: prompt.length,
+                dur_ms: dur,
+                success: true,
+            });
+        }
+        catch { /* noop */ }
+        return { candidates: auditSink, text };
+    }
+    /**
+     * "可能与本对话相关"的 skill 预检索: 让 runner 用一次轻量 LLM 调用从
+     * transcript 里挤 2-5 个 BM25 关键词, 再走 core.search 拿 top-N (受
+     * prefixSkillsLimit 限制)。成功且非空 → 返回 { block, query }; query 为空
+     * / search 空命中 / runner 缺失都返回 null 让上游走 recent 降级。
+     *
+     * 拆两步(而不是直接把 relevant 检索合进 review agent 的迭代里)的原因:
+     *   1. 让 review agent 一进场就有个具体的候选池, 而不是先摸黑扫一遍再检索;
+     *   2. query-gen 是短输出 (≤100 tokens), 不占 review agent 上下文;
+     *   3. 失败可精确降级; review agent 内跑 skill_list 只会退化到"全 owner",
+     *      本函数则可选 relevant 或 recent。
+     */
+    async buildRelevantSkillsBlock(input, transcript) {
+        if (!this.runner)
+            return null;
+        const query = await this.generateSearchQueryFromTranscript(input, transcript);
+        if (!query)
+            return null;
+        let hits;
+        try {
+            hits = await this.core.search({
+                user_id: input.user_id,
+                team_id: input.team_id,
+                agent_id: input.agent_id,
+                query,
+                top_k: this.prefixSkillsLimit,
+            });
+        }
+        catch (e) {
+            this.logger?.warn(`${TAG} relevant search failed for query='${query}': ${e.message}`);
+            return null;
+        }
+        if (!hits.length)
+            return null;
+        const lines = hits.map((h) => formatSkillLine(h.skill.name, h.skill.description));
+        const block = [
+            `## Skills possibly relevant to this conversation (query='${query}', BM25 prefetched)`,
+            "These were retrieved by pre-running skill_list(query=...) against your own skill pool.",
+            "If any of these already covers the topic, prefer `skill_update` / `skill_patch` over creating a duplicate.",
+            ...lines,
+        ].join("\n");
+        return { block, query };
+    }
+    /**
+     * 让 runner 用一次无工具的短 LLM 调用从 transcript 里抽 2-5 个 BM25 关键词。
+     * 返回值经过 sanitize (换行 / FTS5 保留词打成空格, 空串视为失败)。runner
+     * 抛异常一律往外扔, 上游 (buildRelevantSkillsBlock) 会 catch 并降级。
+     */
+    async generateSearchQueryFromTranscript(input, transcript) {
+        if (!this.runner)
+            return "";
+        const raw = await this.runner.run({
+            systemPrompt: QUERY_GEN_SYSTEM_PROMPT,
+            prompt: [
+                "Below is a past conversation. Extract 2-5 short keywords (Chinese or English) that",
+                "capture what the user was trying to do. These will feed a BM25 search over an",
+                "existing skill library. Output the keywords on a single line, space-separated,",
+                "no punctuation, no labels, no explanation.",
+                "",
+                "<<transcript>>",
+                transcript,
+                "<<end-of-transcript>>",
+            ].join("\n"),
+            enableTools: false,
+            // 让 runner 别真跑 tool loop, 就当一次普通 completion 用。
+            maxIterations: 1,
+            // 关键词很短; 32 token 足够 5 词 ×~6 字符 CJK, 也帮 runner 快速返回。
+            maxTokens: 64,
+            taskId: `skill-extract-query-${input.task_id ?? "unknown"}`,
+            // Langfuse 上可按此 traceName 单独筛这类 query-gen call, 跟主 skill.extract 分开。
+            traceName: "skill.extract.query-gen",
+            tags: [
+                "skill-extract",
+                "skill-extract-query-gen",
+                `team:${input.team_id}`,
+                `agent:${input.agent_id}`,
+            ],
+            sessionId: input.session_id,
+            userId: input.user_id,
+            instanceId: input.space_id,
+        });
+        return sanitizeGeneratedQuery(raw);
+    }
+}
+// ═════════════════════════════════════════════════════════════════════
+//  helpers
+// ═════════════════════════════════════════════════════════════════════
+/**
+ * 把 ExtractMessage[] 序列化成给 Skill Review Agent 看的 transcript。
+ *
+ * 关键设计（对齐 SKILL_REVIEW_PROMPT 的 "Role isolation" 段）：
+ *   - role 前缀用非自然的 `<<past-xxx>>` 双尖括号 tag，而不是 `[user]` / `[assistant]`。
+ *     后者是 chat completion 的原生 role signal，模型会本能把 transcript 尾部的
+ *     `[assistant]` 当成"该我续写下一 turn"的锚点，直接接着写主 agent 的回复。
+ *     `<<past-user>>` 这类非典型 tag 打破这个暗示，让模型明确知道"这些是我在
+ *     review 的历史内容，不是我要扮演的角色"。
+ *   - 末尾追加 `<<end-of-transcript>>` 锚点 + 一句"现在按 system prompt 里的
+ *     output contract 决策"。没有这个锚点时，模型看到 transcript 直接结束在
+ *     一段 assistant 长回复上，很容易走"再续写一段类似风格"的路径。
+ *
+ * 相关背景：docs/2026-07-28 skill extractor role-capture 分析（trace
+ * f546ab8c-c7c5-4598-a310-6b2162372e7c，抽取 LLM 完全忽略 SKILL_REVIEW_PROMPT
+ * 契约，产出 1235 tokens 的主对话续写，零 tool call、零 "Nothing to save."）。
+ */
+function formatTranscript(messages) {
+    const body = messages.map((m) => `<<past-${m.role}>>\n${m.content}`).join("\n\n");
+    return `${body}\n\n<<end-of-transcript>>\nAbove is the past conversation to review. Now decide, and respond only per the output contract in the system prompt.`;
+}
+function truncateHeadTail(s, head, tail) {
+    if (s.length <= head + tail)
+        return s;
+    return `${s.slice(0, head)}\n\n... [truncated ${s.length - head - tail} chars] ...\n\n${s.slice(-tail)}`;
+}
+/**
+ * "从对话里挤 2-5 个 BM25 关键词" 的 system prompt。
+ * 关键点:
+ *   1. 明确说这些关键词后面要塞进 BM25 → 让 LLM 挑高信号词, 别造完整句子;
+ *   2. 中英都行, jieba 会正确切;
+ *   3. 单行输出 + 无标点 + 无标签; 后置 sanitize 也会强制这个 shape。
+ */
+const QUERY_GEN_SYSTEM_PROMPT = [
+    "You are helping build a BM25 keyword query.",
+    "Given a past user↔assistant conversation, output 2-5 short high-signal keywords",
+    "(Chinese or English mixed as they appear in the transcript) that best represent",
+    "what the user was trying to accomplish.",
+    "",
+    "Rules:",
+    "- Output ONLY the keywords, on a single line, separated by single spaces.",
+    "- No punctuation, no quotes, no bullets, no labels, no explanation.",
+    "- Do NOT invent topics not present in the transcript.",
+    "- Prefer nouns / product names / verbs; drop filler words (the, a, 一下, 帮我).",
+    "- If the transcript is empty or has no clear intent, output an empty line.",
+].join("\n");
+/**
+ * 生成的 query 有效化:
+ *   - 只取第一行 (LLM 有时会先说 "Here are the keywords:" 再一行)
+ *   - 去 FTS5 保留词 (AND/OR/NOT/NEAR) 直接删掉 (BM25 层再走 buildFtsQuery 兜底)
+ *   - 去掉常见标点 (标点会让 BM25 tokenizer 抖动)
+ *   - 折叠空白, trim
+ *   - 保守长度: 上限 120 字符 (5 词 × ~24 char)
+ * 输出空串 = 认为 LLM 没抽到; 上游走 recent 降级。
+ */
+export function sanitizeGeneratedQuery(raw) {
+    if (typeof raw !== "string")
+        return "";
+    // A₂ 派 thinking 模型 (minimax-m3 / GLM-4-thinking / qwq-32b / 部分 vLLM
+    // DeepSeek-R1) 会把 reasoning 内嵌为 `<think>…</think>` 塞在 content 里。
+    // 如果不先剥掉，`raw.split(/\r?\n/)` 的首个非空行会是 `<think>` 或 think 内容,
+    // 后续标点清洗会把 `<` `>` 打成空格 → BM25 拿到脏 query 命中 0 → 上游降级到
+    // recent。业务不断，但预检索静默失效。跟 l1-extractor.ts@ccaa5dc3 同一思路：
+    //   - 非贪婪 `*?` + 强制 </think> 闭合：截断的 think tag (max_tokens 卡住)
+    //     不 match → 保留原样 → sanitize 后续把它当噪声处理 → recent 降级
+    //   - `g` flag：多段 think 全剥
+    //   - A₁ 派 (minimax-m2.7 / deepseek-v4-pro / o1 / o3) content 无 <think>,
+    //     replace 是 no-op → byte-for-byte 等价，backward-compatible。
+    raw = raw.replace(/<think>[\s\S]*?<\/think>\s*/g, "");
+    // 只取首个非空行 —— LLM 偶尔会在关键词前后加一行元数据。
+    const firstLine = raw.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+    if (!firstLine)
+        return "";
+    // 剔常见标点 / FTS5 保留词。用空格替换而非删除, 避免 "foo,bar" 变成 "foobar"。
+    const noPunct = firstLine
+        .replace(/[,;:!?"'`()\[\]{}<>|/\\*+=~@#$%^&]/g, " ")
+        .replace(/[，。；：！？、（）【】《》「」『』]/g, " ")
+        .replace(/\b(AND|OR|NOT|NEAR)\b/gi, " ");
+    const collapsed = noPunct.replace(/\s+/g, " ").trim();
+    if (!collapsed)
+        return "";
+    return collapsed.length > 120 ? collapsed.slice(0, 120).trimEnd() : collapsed;
+}
+/**
+ * 拼一行 "- name — 描述截断到 100 char"。空描述回退到 "- name"。
+ * 抽 recent / relevant / full 三个块共用, 避免行格式漂移。
+ */
+function formatSkillLine(name, description) {
+    const desc = (description ?? "").trim().replace(/\s+/g, " ");
+    const short = desc.length > 100 ? `${desc.slice(0, 100)}…` : desc;
+    return short ? `- ${name} — ${short}` : `- ${name}`;
+}
+/**
+ * "全量" 前缀块 —— 该 agent 的 skill 总数 ≤ prefixSkillsLimit, 直接铺开。
+ * 语义上告诉 LLM "这就是你所有的 skill, 无遗漏", 相比 recent 段更强的先验。
+ * 复用时无 truncated 提示 (因为没截断)。
+ */
+function renderFullSkillsBlock(items) {
+    const lines = items.map((s) => formatSkillLine(s.name, s.description));
+    return [
+        `## Skills you (this agent) own (${items.length} total — full list, no truncation)`,
+        "This is your entire skill inventory. Consider `skill_update` / `skill_patch` on an existing skill before creating a new one.",
+        ...lines,
+    ].join("\n");
+}
+/**
+ * "最近更新" 前缀块 —— relevant 分支失败时的兜底。附带 "还有 X 条未显示"
+ * 提示, 让 LLM 知道可以主动 skill_list(query=...) 拉更多。
+ */
+function renderRecentSkillsBlock(items, total) {
+    const lines = items.map((s) => formatSkillLine(s.name, s.description));
+    const omitted = total - items.length;
+    const header = `## Skills you (this agent) own (${items.length} most-recently-updated of ${total} total, prefetched via skill_list)`;
+    const hint = omitted > 0
+        ? `Most recent first. ${omitted} more not shown — call skill_list(query=...) to search the rest. Consider \`skill_update\` / \`skill_patch\` on an existing skill before creating a new one.`
+        : "Most recent first. Consider `skill_update` / `skill_patch` on an existing skill before creating a new one.";
+    return [header, hint, ...lines].join("\n");
+}
+// A02: expose the canonical formatter for coverage accounting in the host-neutral runtime.
+export { formatTranscript };

package/dist/upstream/core/skill/skill-format.d.ts

@@ -0,0 +1,46 @@
+/**
+ * skill-format — SKILL.md ↔ SkillFile (de)serialization + validation.
+ *
+ * Why a dedicated module:
+ *   - Keep frontmatter parsing rules in one place (the LLM Reviewer in M6
+ *     emits SKILL.md text; the Gateway accepts SKILL.md text in
+ *     /v3/skill/create; both flow through here).
+ *   - Validation lives next to parsing so callers do `parse → validate`
+ *     atomically.
+ *
+ * Frontmatter contract (SKILL_ENGINEERING_DESIGN §4.1 / §11.1):
+ *   - YAML between leading `---\n` ... `\n---` fences (closing `---`
+ *     followed by either newline or EOF).
+ *   - REQUIRED: name, description.
+ *   - OPTIONAL: category, created_at, updated_at, source, resources[].
+ *
+ * Limits (locked in M3):
+ *   - name      : 1..64 chars, ^[a-z0-9][a-z0-9-]*$
+ *   - description: 1..1024 chars
+ *   - body      : ≤50_000 chars
+ *   - resources[*].type ∈ {text, executable, binary}
+ */
+import type { SkillFile } from "./types.js";
+/**
+ * Parse a SKILL.md raw string into a SkillFile.
+ *
+ * Accepts CRLF or LF line endings. Throws with a clear message when:
+ *   - the file does not start with a `---\n` (no frontmatter)
+ *   - the closing `---` fence is missing
+ *   - the YAML body cannot be parsed
+ *   - the parsed YAML is missing `name` or `description`
+ *
+ * No length / regex checks here — call `validateSkillFile` next.
+ */
+export declare function parseSkillFile(raw: string): SkillFile;
+/**
+ * Throw if the SkillFile violates any contract limit.
+ * Mutates nothing; pure assertion.
+ */
+export declare function validateSkillFile(file: SkillFile): void;
+/**
+ * Serialize a SkillFile back to canonical SKILL.md text (frontmatter + body).
+ * Round-trip safe: parseSkillFile(formatSkillFile(f)) yields a file with the
+ * same logical fields and body.
+ */
+export declare function formatSkillFile(file: SkillFile): string;

package/dist/upstream/core/skill/skill-format.js

@@ -0,0 +1,191 @@
+/**
+ * skill-format — SKILL.md ↔ SkillFile (de)serialization + validation.
+ *
+ * Why a dedicated module:
+ *   - Keep frontmatter parsing rules in one place (the LLM Reviewer in M6
+ *     emits SKILL.md text; the Gateway accepts SKILL.md text in
+ *     /v3/skill/create; both flow through here).
+ *   - Validation lives next to parsing so callers do `parse → validate`
+ *     atomically.
+ *
+ * Frontmatter contract (SKILL_ENGINEERING_DESIGN §4.1 / §11.1):
+ *   - YAML between leading `---\n` ... `\n---` fences (closing `---`
+ *     followed by either newline or EOF).
+ *   - REQUIRED: name, description.
+ *   - OPTIONAL: category, created_at, updated_at, source, resources[].
+ *
+ * Limits (locked in M3):
+ *   - name      : 1..64 chars, ^[a-z0-9][a-z0-9-]*$
+ *   - description: 1..1024 chars
+ *   - body      : ≤50_000 chars
+ *   - resources[*].type ∈ {text, executable, binary}
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+const NAME_MAX = 64;
+const DESCRIPTION_MAX = 1024;
+const BODY_MAX = 50_000;
+const NAME_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+const RESOURCE_TYPES = new Set(["text", "executable", "binary"]);
+/**
+ * Parse a SKILL.md raw string into a SkillFile.
+ *
+ * Accepts CRLF or LF line endings. Throws with a clear message when:
+ *   - the file does not start with a `---\n` (no frontmatter)
+ *   - the closing `---` fence is missing
+ *   - the YAML body cannot be parsed
+ *   - the parsed YAML is missing `name` or `description`
+ *
+ * No length / regex checks here — call `validateSkillFile` next.
+ */
+export function parseSkillFile(raw) {
+    // Normalize line endings so the fence matcher is simpler.
+    const text = raw.replace(/\r\n?/g, "\n");
+    if (!text.startsWith("---\n") && text !== "---\n") {
+        throw new Error(`[skill][format] missing frontmatter — file must start with '---\\n'`);
+    }
+    // Find the closing fence. Must be on its own line, after the opening fence.
+    // We search starting from index 4 (past the opening "---\n") for "\n---" followed
+    // by either "\n" or EOF.
+    const start = 4;
+    let close = -1;
+    let endOfClose = -1;
+    for (let i = start; i < text.length - 3; i++) {
+        if (text[i] === "\n" && text[i + 1] === "-" && text[i + 2] === "-" && text[i + 3] === "-") {
+            // Must be followed by newline or EOF.
+            const after = text[i + 4];
+            if (after === undefined || after === "\n") {
+                close = i + 1; // index of the closing "---"
+                endOfClose = i + 4 + (after === "\n" ? 1 : 0);
+                break;
+            }
+        }
+    }
+    if (close === -1) {
+        throw new Error(`[skill][format] missing closing '---' fence in frontmatter`);
+    }
+    const yamlText = text.slice(start, close);
+    let fm;
+    try {
+        fm = parseYaml(yamlText) ?? {};
+    }
+    catch (err) {
+        throw new Error(`[skill][format] YAML parse error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Coerce non-string values to string so YAML's type inference (null / true /
+    // 123 / comment-like #…) doesn't cause confusing "missing required field"
+    // errors when the key is clearly present.  An empty value after coercion is
+    // still an error — every SKILL.md MUST carry a non-empty description.
+    //
+    // Distinguish between "key absent" (undefined) and "key present but non-string"
+    // (null / true / 123).  The former is still an error; the latter is coerced.
+    const nameRaw = fm.name;
+    const name = typeof nameRaw === "string"
+        ? nameRaw
+        : nameRaw === undefined || nameRaw === null
+            ? ""
+            : String(nameRaw);
+    if (name.trim() === "") {
+        throw new Error(`[skill][format] frontmatter missing required field 'name'`);
+    }
+    fm.name = name;
+    const descRaw = fm.description;
+    const description = typeof descRaw === "string"
+        ? descRaw
+        : descRaw === undefined || descRaw === null
+            ? ""
+            : String(descRaw);
+    if (description.trim() === "") {
+        throw new Error(`[skill][format] frontmatter missing required field 'description'`);
+    }
+    fm.description = description;
+    // body is everything after the closing fence; strip a single leading newline
+    // so SKILL.md authors can leave a blank line between fence and body.
+    let body = text.slice(endOfClose);
+    if (body.startsWith("\n"))
+        body = body.slice(1);
+    return {
+        frontmatter: {
+            name,
+            description,
+            category: typeof fm.category === "string" ? fm.category : undefined,
+            created_at: typeof fm.created_at === "string" ? fm.created_at : undefined,
+            updated_at: typeof fm.updated_at === "string" ? fm.updated_at : undefined,
+            source: fm.source === "auto" || fm.source === "manual" ? fm.source : undefined,
+            resources: parseResources(fm.resources),
+        },
+        body,
+        raw,
+    };
+}
+/**
+ * Throw if the SkillFile violates any contract limit.
+ * Mutates nothing; pure assertion.
+ */
+export function validateSkillFile(file) {
+    const { name, description, resources } = file.frontmatter;
+    if (!NAME_REGEX.test(name)) {
+        throw new Error(`[skill][format] invalid name '${name}' — must match ^[a-z0-9][a-z0-9-]*$`);
+    }
+    if (name.length > NAME_MAX) {
+        throw new Error(`[skill][format] name length ${name.length} exceeds max ${NAME_MAX}`);
+    }
+    if (description.length > DESCRIPTION_MAX) {
+        throw new Error(`[skill][format] description length ${description.length} exceeds max ${DESCRIPTION_MAX}`);
+    }
+    if (file.body.length > BODY_MAX) {
+        throw new Error(`[skill][format] body length ${file.body.length} exceeds max ${BODY_MAX}`);
+    }
+    if (resources) {
+        for (const r of resources) {
+            if (!RESOURCE_TYPES.has(r.type)) {
+                throw new Error(`[skill][format] resource type '${r.type}' invalid — must be one of text/executable/binary`);
+            }
+        }
+    }
+}
+/**
+ * Serialize a SkillFile back to canonical SKILL.md text (frontmatter + body).
+ * Round-trip safe: parseSkillFile(formatSkillFile(f)) yields a file with the
+ * same logical fields and body.
+ */
+export function formatSkillFile(file) {
+    const fm = {
+        name: file.frontmatter.name,
+        description: file.frontmatter.description,
+    };
+    if (file.frontmatter.category !== undefined)
+        fm.category = file.frontmatter.category;
+    if (file.frontmatter.created_at !== undefined)
+        fm.created_at = file.frontmatter.created_at;
+    if (file.frontmatter.updated_at !== undefined)
+        fm.updated_at = file.frontmatter.updated_at;
+    if (file.frontmatter.source !== undefined)
+        fm.source = file.frontmatter.source;
+    if (file.frontmatter.resources && file.frontmatter.resources.length > 0) {
+        fm.resources = file.frontmatter.resources;
+    }
+    const yamlBlock = stringifyYaml(fm).replace(/\n+$/, "");
+    return `---\n${yamlBlock}\n---\n\n${file.body}`;
+}
+// ============================
+// Internal helpers
+// ============================
+function parseResources(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = [];
+    for (const item of raw) {
+        if (typeof item !== "object" || item == null)
+            continue;
+        const o = item;
+        if (typeof o.path !== "string" || typeof o.type !== "string")
+            continue;
+        // Note: type is preserved verbatim; full enum check happens in validateSkillFile
+        // so callers see a clean error message rather than a silent drop.
+        out.push({
+            path: o.path,
+            type: o.type,
+        });
+    }
+    return out;
+}