@memtensor/memos-local-openclaw-plugin 0.1.3 → 0.1.5

package/src/recall/engine.ts

@@ -10,6 +10,7 @@ export interface RecallOptions {
   query?: string;
   maxResults?: number;
   minScore?: number;
+  role?: string;
 }
 
 const MAX_RECENT_QUERIES = 20;
@@ -31,6 +32,7 @@ export class RecallEngine {
     );
     const minScore = opts.minScore ?? recallCfg.minScoreDefault!;
     const query = opts.query ?? "";
+    const roleFilter = opts.role;
 
     const repeatNote = this.checkRepeat(query, maxResults, minScore);
     const candidatePool = maxResults * 5;
@@ -82,24 +84,31 @@ export class RecallEngine {
     });
     const decayed = applyRecencyDecay(withTs, recallCfg.recencyHalfLifeDays);
 
-    // Step 5: Normalize scores to [0,1]
-    const maxScore = Math.max(...decayed.map((d) => d.score), 1e-10);
-    const normalized = decayed.map((d) => ({
+    // Step 5: Apply relative threshold on raw scores, then normalize to [0,1]
+    const sorted = [...decayed].sort((a, b) => b.score - a.score);
+    const topScore = sorted.length > 0 ? sorted[0].score : 0;
+
+    const absoluteFloor = topScore * minScore * 0.3;
+    // When role filter is active, keep a larger pool before slicing so we don't
+    // discard target-role candidates that rank below non-target ones.
+    const preSliceLimit = roleFilter ? maxResults * 5 : maxResults;
+    const filtered = sorted
+      .filter((d) => d.score >= absoluteFloor)
+      .slice(0, preSliceLimit);
+
+    const displayMax = filtered.length > 0 ? filtered[0].score : 1;
+    const normalized = filtered.map((d) => ({
       ...d,
-      score: d.score / maxScore,
+      score: d.score / displayMax,
     }));
 
-    // Step 6: Filter by minScore and limit
-    const filtered = normalized
-      .filter((d) => d.score >= minScore)
-      .sort((a, b) => b.score - a.score)
-      .slice(0, maxResults);
-
-    // Step 7: Build hits
+    // Step 6: Build hits (with optional role filter), applying maxResults cap at the end
     const hits: SearchHit[] = [];
-    for (const candidate of filtered) {
+    for (const candidate of normalized) {
+      if (hits.length >= maxResults) break;
       const chunk = this.store.getChunk(candidate.id);
       if (!chunk) continue;
+      if (roleFilter && chunk.role !== roleFilter) continue;
 
       hits.push({
         summary: chunk.summary,
@@ -111,6 +120,8 @@ export class RecallEngine {
           seq: chunk.seq,
         },
         score: Math.round(candidate.score * 1000) / 1000,
+        taskId: chunk.taskId,
+        skillId: chunk.skillId,
         source: {
           ts: chunk.createdAt,
           role: chunk.role,

package/src/recall/mmr.ts

@@ -53,7 +53,9 @@ export function mmrRerank(
     }
 
     const chosen = remaining.splice(bestIdx, 1)[0];
-    selected.push({ id: chosen.id, score: bestMmr });
+    // Preserve original RRF score for downstream filtering;
+    // MMR only determines selection order, not the score value.
+    selected.push({ id: chosen.id, score: chosen.score });
   }
 
   return selected;

package/src/skill/bundled-memory-guide.ts

@@ -0,0 +1,91 @@
+/**
+ * Bundled MemOS memory-guide skill content.
+ * Written to workspace/skills/memos-memory-guide on plugin register so OpenClaw loads it.
+ */
+export const MEMORY_GUIDE_SKILL_MD = `---
+name: memos-memory-guide
+description: Use the MemOS local memory system to search and use the user's past conversations. Use this skill whenever the user refers to past chats, their own preferences or history, or when you need to answer from prior context. When auto-recall returns nothing (long or unclear user query), generate your own short search query and call memory_search. Use task_summary when you need full task context, skill_get for experience guides, and memory_timeline to expand around a memory hit.
+---
+
+# MemOS Local Memory — Agent Guide
+
+This skill describes how to use the MemOS memory tools so you can reliably search and use the user's long-term conversation history.
+
+## How memory is provided each turn
+
+- **Automatic recall (hook):** At the start of each turn, the system runs a memory search using the user's current message and injects relevant past memories into your context. You do not need to call any tool for that.
+- **When that is not enough:** If the user's message is very long, vague, or the automatic search returns **no memories**, you should **generate your own short, focused query** and call \`memory_search\` yourself. For example:
+  - User sent a long paragraph → extract 1–2 key topics or a short question and search with that.
+  - Auto-recall said "no memories" or you see no memory block → call \`memory_search\` with a query you derive (e.g. the user's name, a topic they often mention, or a rephrased question).
+- **When you need more detail:** Search results only give excerpts and IDs. Use the tools below to fetch full task context, skill content, or surrounding messages.
+
+## Tools — what they do and when to call
+
+### memory_search
+
+- **What it does:** Searches the user's stored conversation memory by a natural-language query. Returns a list of relevant excerpts with \`chunkId\` and optionally \`task_id\`.
+- **When to call:**
+  - The automatic recall did not run or returned nothing (e.g. no \`<memory_context>\` block, or a note that no memories were found).
+  - The user's query is long or unclear — **generate a short query yourself** (keywords, rephrased question, or a clear sub-question) and call \`memory_search(query="...")\`.
+  - You need to search with a different angle (e.g. filter by \`role='user'\` to find what the user said, or use a more specific query).
+- **Parameters:** \`query\` (required), optional \`minScore\`, \`role\` (e.g. \`"user"\`).
+- **Output:** List of items with role, excerpt, \`chunkId\`, and sometimes \`task_id\`. Use those IDs with the tools below when you need more context.
+
+### task_summary
+
+- **What it does:** Returns the full task summary for a given \`task_id\`: title, status, and the complete narrative summary of that conversation task (steps, decisions, URLs, commands, etc.).
+- **When to call:** A \`memory_search\` hit included a \`task_id\` and you need the full story of that task (e.g. what was done, what the user decided, what failed or succeeded).
+- **Parameters:** \`taskId\` (from a search hit).
+- **Effect:** You get one coherent summary of the whole task instead of isolated excerpts.
+
+### skill_get
+
+- **What it does:** Returns the content of a learned skill (experience guide) by \`skillId\` or by \`taskId\`. If you pass \`taskId\`, the system finds the skill linked to that task.
+- **When to call:** A search hit has a \`task_id\` and the task is the kind that has a "how to do this again" guide (e.g. a workflow the user has run before). Use this to follow the same approach or reuse steps.
+- **Parameters:** \`skillId\` (direct) or \`taskId\` (lookup).
+- **Effect:** You receive the full SKILL.md-style guide. You can then call \`skill_install(skillId)\` if the user or you want that skill loaded for future turns.
+
+### skill_install
+
+- **What it does:** Installs a skill (by \`skillId\`) into the workspace so it is loaded in future sessions.
+- **When to call:** After \`skill_get\` when the skill is useful for ongoing use (e.g. the user's recurring workflow). Optional; only when you want the skill to be permanently available.
+- **Parameters:** \`skillId\`.
+
+### memory_timeline
+
+- **What it does:** Expands context around a single memory chunk: returns the surrounding conversation messages (±N turns) so you see what was said before and after that excerpt.
+- **When to call:** A \`memory_search\` hit is relevant but you need the surrounding dialogue (e.g. who said what next, or the exact follow-up question).
+- **Parameters:** \`chunkId\` (from a search hit), optional \`window\` (default 2).
+- **Effect:** You get a short, linear slice of the conversation around that chunk.
+
+### memory_viewer
+
+- **What it does:** Returns the URL of the MemOS Memory Viewer (web UI) where the user can browse, search, and manage their memories.
+- **When to call:** The user asks how to view their memories, open the memory dashboard, or manage stored data.
+- **Parameters:** None.
+- **Effect:** You can tell the user to open that URL in a browser.
+
+## Quick decision flow
+
+1. **No memories in context or auto-recall reported nothing**
+   → Call \`memory_search\` with a **self-generated short query** (e.g. key topic or rephrased question).
+
+2. **Search returned hits with \`task_id\` and you need full context**
+   → Call \`task_summary(taskId)\`.
+
+3. **Task has an experience guide you want to follow**
+   → Call \`skill_get(taskId=...)\` (or \`skill_get(skillId=...)\` if you have the id). Optionally \`skill_install(skillId)\` for future use.
+
+4. **You need the exact surrounding conversation of a hit**
+   → Call \`memory_timeline(chunkId=...)\`.
+
+5. **User asks where to see or manage their memories**
+   → Call \`memory_viewer()\` and share the URL.
+
+## Writing good search queries
+
+- Prefer **short, focused** queries (a few words or one clear question).
+- Use **concrete terms**: names, topics, tools, or decisions (e.g. "preferred editor", "deploy script", "API key setup").
+- If the user's message is long, **derive one or two sub-queries** rather than pasting the whole message.
+- Use \`role='user'\` when you specifically want to find what the user said (e.g. preferences, past questions).
+`;

package/src/skill/evaluator.ts

@@ -0,0 +1,220 @@
+import type { Chunk, Task, Skill, PluginContext, SummarizerConfig } from "../types";
+import { DEFAULTS } from "../types";
+
+export interface CreateEvalResult {
+  shouldGenerate: boolean;
+  reason: string;
+  suggestedName: string;
+  suggestedTags: string[];
+  confidence: number;
+}
+
+export interface UpgradeEvalResult {
+  shouldUpgrade: boolean;
+  upgradeType: "refine" | "extend" | "fix";
+  dimensions: string[];
+  reason: string;
+  mergeStrategy: string;
+  confidence: number;
+}
+
+const CREATE_EVAL_PROMPT = `You are an experience evaluation expert. Based on the completed task record below, decide whether this task contains reusable experience worth distilling into a "skill".
+
+A skill is a reusable guide that helps an AI agent handle similar tasks better in the future.
+
+Worth distilling (any ONE qualifies):
+- Contains concrete steps, commands, code, or configuration
+- Solves a recurring problem with a specific approach/workflow
+- Went through trial-and-error (wrong approach then corrected)
+- Involves non-obvious usage of specific tools, APIs, or frameworks
+- Contains debugging/troubleshooting with diagnostic reasoning
+- Demonstrates a multi-step workflow using external tools (browser, search, file system, etc.)
+- Reveals user preferences or style requirements that should be remembered
+- Shows how to combine multiple tools/services to accomplish a goal
+- Contains a process that required specific parameter tuning or configuration
+
+NOT worth distilling:
+- Pure factual Q&A with no process ("what is TCP", "what's the capital of France")
+- Single-turn simple answers with no workflow
+- Conversation too fragmented or incoherent to extract a clear process
+
+Task title: {TITLE}
+Task summary:
+{SUMMARY}
+
+Reply in JSON only, no extra text:
+{
+  "shouldGenerate": boolean,
+  "reason": "brief explanation",
+  "suggestedName": "kebab-case-name",
+  "suggestedTags": ["tag1", "tag2"],
+  "confidence": 0.0-1.0
+}`;
+
+const UPGRADE_EVAL_PROMPT = `You are a skill upgrade evaluation expert.
+
+Existing skill (v{VERSION}):
+Name: {SKILL_NAME}
+Content:
+{SKILL_CONTENT}
+
+Newly completed task:
+Title: {TITLE}
+Summary:
+{SUMMARY}
+
+Does the new task bring substantive improvements to the existing skill?
+
+Worth upgrading (any one qualifies):
+1. Faster — shorter path discovered
+2. More elegant — cleaner, follows best practices better
+3. More convenient — fewer dependencies or complexity
+4. Fewer tokens — less exploration/trial-and-error needed
+5. More accurate — corrects wrong parameters/steps in old skill
+6. More robust — adds edge cases, error handling
+7. New scenario — covers a variant the old skill didn't
+8. Fixes outdated info — old skill has stale information
+
+NOT worth upgrading:
+- New task is identical to existing skill
+- New task's approach is worse than existing skill
+- Differences are trivial
+
+Reply in JSON only, no extra text:
+{
+  "shouldUpgrade": boolean,
+  "upgradeType": "refine" | "extend" | "fix",
+  "dimensions": ["faster", "more_elegant", "more_convenient", "fewer_tokens", "more_accurate", "more_robust", "new_scenario", "fix_outdated"],
+  "reason": "what new value the task brings",
+  "mergeStrategy": "which specific parts need updating",
+  "confidence": 0.0-1.0
+}`;
+
+export class SkillEvaluator {
+  constructor(private ctx: PluginContext) {}
+
+  passesRuleFilter(chunks: Chunk[], task: Task): { pass: boolean; skipReason: string } {
+    const minChunks = this.ctx.config.skillEvolution?.minChunksForEval ?? DEFAULTS.skillMinChunksForEval;
+    if (chunks.length < minChunks) {
+      return { pass: false, skipReason: `chunks不足 (${chunks.length} < ${minChunks})` };
+    }
+
+    if (task.status === "skipped") {
+      return { pass: false, skipReason: "task状态为skipped" };
+    }
+
+    if (task.summary.length < 100) {
+      return { pass: false, skipReason: `summary过短 (${task.summary.length} < 100)` };
+    }
+
+    const userChunks = chunks.filter(c => c.role === "user");
+    if (userChunks.length === 0) {
+      return { pass: false, skipReason: "无用户消息" };
+    }
+
+    const assistantChunks = chunks.filter(c => c.role === "assistant");
+    if (assistantChunks.length === 0) {
+      return { pass: false, skipReason: "无助手回复" };
+    }
+
+    return { pass: true, skipReason: "" };
+  }
+
+  async evaluateCreate(task: Task): Promise<CreateEvalResult> {
+    const cfg = this.getProviderConfig();
+    if (!cfg) {
+      return { shouldGenerate: false, reason: "no LLM configured", suggestedName: "", suggestedTags: [], confidence: 0 };
+    }
+
+    const prompt = CREATE_EVAL_PROMPT
+      .replace("{TITLE}", task.title)
+      .replace("{SUMMARY}", task.summary.slice(0, 3000));
+
+    try {
+      const raw = await this.callLLM(cfg, prompt);
+      return this.parseJSON<CreateEvalResult>(raw, {
+        shouldGenerate: false, reason: "parse failed", suggestedName: "", suggestedTags: [], confidence: 0,
+      });
+    } catch (err) {
+      this.ctx.log.warn(`SkillEvaluator.evaluateCreate failed: ${err}`);
+      return { shouldGenerate: false, reason: `error: ${err}`, suggestedName: "", suggestedTags: [], confidence: 0 };
+    }
+  }
+
+  async evaluateUpgrade(task: Task, skill: Skill, skillContent: string): Promise<UpgradeEvalResult> {
+    const cfg = this.getProviderConfig();
+    if (!cfg) {
+      return { shouldUpgrade: false, upgradeType: "refine", dimensions: [], reason: "no LLM configured", mergeStrategy: "", confidence: 0 };
+    }
+
+    const prompt = UPGRADE_EVAL_PROMPT
+      .replace("{VERSION}", String(skill.version))
+      .replace("{SKILL_NAME}", skill.name)
+      .replace("{SKILL_CONTENT}", skillContent.slice(0, 4000))
+      .replace("{TITLE}", task.title)
+      .replace("{SUMMARY}", task.summary.slice(0, 3000));
+
+    try {
+      const raw = await this.callLLM(cfg, prompt);
+      return this.parseJSON<UpgradeEvalResult>(raw, {
+        shouldUpgrade: false, upgradeType: "refine", dimensions: [], reason: "parse failed", mergeStrategy: "", confidence: 0,
+      });
+    } catch (err) {
+      this.ctx.log.warn(`SkillEvaluator.evaluateUpgrade failed: ${err}`);
+      return { shouldUpgrade: false, upgradeType: "refine", dimensions: [], reason: `error: ${err}`, mergeStrategy: "", confidence: 0 };
+    }
+  }
+
+  private getProviderConfig(): SummarizerConfig | undefined {
+    return this.ctx.config.skillEvolution?.summarizer ?? this.ctx.config.summarizer;
+  }
+
+  private async callLLM(cfg: SummarizerConfig, userContent: string): Promise<string> {
+    const endpoint = this.normalizeEndpoint(cfg.endpoint ?? "https://api.openai.com/v1/chat/completions");
+    const model = cfg.model ?? "gpt-4o-mini";
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${cfg.apiKey}`,
+      ...cfg.headers,
+    };
+
+    const resp = await fetch(endpoint, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model,
+        temperature: cfg.temperature ?? 0.1,
+        max_tokens: 1024,
+        messages: [
+          { role: "user", content: userContent },
+        ],
+      }),
+      signal: AbortSignal.timeout(cfg.timeoutMs ?? 30_000),
+    });
+
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new Error(`LLM call failed (${resp.status}): ${body}`);
+    }
+
+    const json = (await resp.json()) as { choices: Array<{ message: { content: string } }> };
+    return json.choices[0]?.message?.content?.trim() ?? "";
+  }
+
+  private parseJSON<T>(raw: string, fallback: T): T {
+    const jsonMatch = raw.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return fallback;
+    try {
+      return JSON.parse(jsonMatch[0]) as T;
+    } catch {
+      return fallback;
+    }
+  }
+
+  private normalizeEndpoint(url: string): string {
+    const stripped = url.replace(/\/+$/, "");
+    if (stripped.endsWith("/chat/completions")) return stripped;
+    if (stripped.endsWith("/completions")) return stripped;
+    return `${stripped}/chat/completions`;
+  }
+}

package/src/skill/evolver.ts

@@ -0,0 +1,169 @@
+import * as fs from "fs";
+import * as path from "path";
+import type { SqliteStore } from "../storage/sqlite";
+import type { RecallEngine } from "../recall/engine";
+import type { Task, Skill, Chunk, PluginContext } from "../types";
+import { DEFAULTS } from "../types";
+import { SkillEvaluator } from "./evaluator";
+import { SkillGenerator } from "./generator";
+import { SkillUpgrader } from "./upgrader";
+import { SkillInstaller } from "./installer";
+
+export class SkillEvolver {
+  private evaluator: SkillEvaluator;
+  private generator: SkillGenerator;
+  private upgrader: SkillUpgrader;
+  private installer: SkillInstaller;
+  private processing = false;
+
+  constructor(
+    private store: SqliteStore,
+    private engine: RecallEngine,
+    private ctx: PluginContext,
+  ) {
+    this.evaluator = new SkillEvaluator(ctx);
+    this.generator = new SkillGenerator(store, engine, ctx);
+    this.upgrader = new SkillUpgrader(store, ctx);
+    this.installer = new SkillInstaller(store, ctx);
+  }
+
+  async onTaskCompleted(task: Task): Promise<void> {
+    const enabled = this.ctx.config.skillEvolution?.enabled ?? DEFAULTS.skillEvolutionEnabled;
+    const autoEval = this.ctx.config.skillEvolution?.autoEvaluate ?? DEFAULTS.skillAutoEvaluate;
+    if (!enabled || !autoEval) return;
+
+    if (this.processing) {
+      this.ctx.log.debug("SkillEvolver: already processing, skipping");
+      return;
+    }
+    this.processing = true;
+    try {
+      await this.process(task);
+    } catch (err) {
+      this.ctx.log.error(`SkillEvolver error: ${err}`);
+    } finally {
+      this.processing = false;
+    }
+  }
+
+  private async process(task: Task): Promise<void> {
+    const chunks = this.store.getChunksByTask(task.id);
+
+    const { pass, skipReason } = this.evaluator.passesRuleFilter(chunks, task);
+    if (!pass) {
+      this.ctx.log.debug(`SkillEvolver: task ${task.id} skipped by rule filter: ${skipReason} (chunks=${chunks.length})`);
+      this.store.setTaskSkillMeta(task.id, { skillStatus: "skipped", skillReason: skipReason });
+      return;
+    }
+
+    const relatedSkill = await this.findRelatedSkill(task);
+
+    if (relatedSkill) {
+      await this.handleExistingSkill(task, chunks, relatedSkill);
+    } else {
+      await this.handleNewSkill(task, chunks);
+    }
+  }
+
+  private async findRelatedSkill(task: Task): Promise<Skill | null> {
+    try {
+      const result = await this.engine.search({
+        query: task.summary.slice(0, 500),
+        maxResults: 10,
+        minScore: 0.5,
+      });
+
+      for (const hit of result.hits) {
+        if (hit.skillId) {
+          const skill = this.store.getSkill(hit.skillId);
+          if (skill && (skill.status === "active" || skill.status === "draft")) {
+            this.ctx.log.debug(`SkillEvolver: found related skill "${skill.name}" via memory search`);
+            return skill;
+          }
+        }
+      }
+    } catch (err) {
+      this.ctx.log.warn(`SkillEvolver: memory search for related skill failed: ${err}`);
+    }
+    return null;
+  }
+
+  private async handleExistingSkill(task: Task, chunks: Chunk[], skill: Skill): Promise<void> {
+    const skillContent = this.readSkillContent(skill);
+    if (!skillContent) {
+      this.ctx.log.warn(`SkillEvolver: cannot read skill "${skill.name}" content, treating as new`);
+      await this.handleNewSkill(task, chunks);
+      return;
+    }
+
+    const minConfidence = this.ctx.config.skillEvolution?.minConfidence ?? DEFAULTS.skillMinConfidence;
+    const evalResult = await this.evaluator.evaluateUpgrade(task, skill, skillContent);
+
+    if (evalResult.shouldUpgrade && evalResult.confidence >= minConfidence) {
+      this.ctx.log.info(`SkillEvolver: upgrading skill "${skill.name}" — ${evalResult.reason}`);
+      const { upgraded } = await this.upgrader.upgrade(task, skill, evalResult);
+
+      this.markChunksWithSkill(chunks, skill.id);
+
+      if (upgraded) {
+        this.store.linkTaskSkill(task.id, skill.id, "evolved_from", skill.version + 1);
+        this.installer.syncIfInstalled(skill.name);
+      } else {
+        this.store.linkTaskSkill(task.id, skill.id, "applied_to", skill.version);
+      }
+    } else if (evalResult.confidence < 0.3) {
+      // Low confidence means the matched skill is likely unrelated — try creating a new one
+      this.ctx.log.info(
+        `SkillEvolver: skill "${skill.name}" has low relevance (confidence=${evalResult.confidence}), ` +
+        `falling back to new skill evaluation for task "${task.title}"`,
+      );
+      await this.handleNewSkill(task, chunks);
+    } else {
+      this.ctx.log.debug(`SkillEvolver: skill "${skill.name}" not worth upgrading (confidence=${evalResult.confidence})`);
+      this.markChunksWithSkill(chunks, skill.id);
+      this.store.linkTaskSkill(task.id, skill.id, "applied_to", skill.version);
+    }
+  }
+
+  private async handleNewSkill(task: Task, chunks: Chunk[]): Promise<void> {
+    const minConfidence = this.ctx.config.skillEvolution?.minConfidence ?? DEFAULTS.skillMinConfidence;
+    const evalResult = await this.evaluator.evaluateCreate(task);
+
+    if (evalResult.shouldGenerate && evalResult.confidence >= minConfidence) {
+      this.ctx.log.info(`SkillEvolver: generating new skill "${evalResult.suggestedName}" — ${evalResult.reason}`);
+      this.store.setTaskSkillMeta(task.id, { skillStatus: "generating", skillReason: evalResult.reason });
+
+      const skill = await this.generator.generate(task, chunks, evalResult);
+      this.markChunksWithSkill(chunks, skill.id);
+      this.store.linkTaskSkill(task.id, skill.id, "generated_from", 1);
+      this.store.setTaskSkillMeta(task.id, { skillStatus: "generated", skillReason: evalResult.reason });
+
+      const autoInstall = this.ctx.config.skillEvolution?.autoInstall ?? DEFAULTS.skillAutoInstall;
+      if (autoInstall && skill.status === "active") {
+        this.installer.install(skill.id);
+      }
+    } else {
+      const reason = evalResult.reason || `confidence不足 (${evalResult.confidence} < ${minConfidence})`;
+      this.ctx.log.debug(`SkillEvolver: task "${task.title}" not worth generating skill — ${reason}`);
+      this.store.setTaskSkillMeta(task.id, { skillStatus: "not_generated", skillReason: reason });
+    }
+  }
+
+  private markChunksWithSkill(chunks: Chunk[], skillId: string): void {
+    for (const chunk of chunks) {
+      this.store.setChunkSkillId(chunk.id, skillId);
+    }
+    this.ctx.log.debug(`SkillEvolver: marked ${chunks.length} chunks with skill_id=${skillId}`);
+  }
+
+  private readSkillContent(skill: Skill): string | null {
+    const filePath = path.join(skill.dirPath, "SKILL.md");
+    try {
+      if (fs.existsSync(filePath)) {
+        return fs.readFileSync(filePath, "utf-8");
+      }
+    } catch { /* fall through */ }
+    const sv = this.store.getLatestSkillVersion(skill.id);
+    return sv?.content ?? null;
+  }
+}