@selesai/code 0.13.13 → 0.13.14

package/dist/extensions/pi-hermes-memory/src/store/skill-store.ts

@@ -0,0 +1,950 @@
+/**
+ * SkillStore — procedural memory stored as Pi-native skills.
+ *
+ * Global skills live in ~/.selesai/agent/pi-hermes-memory/skills/<slug>/SKILL.md.
+ * Project skills live in ~/.selesai/agent/<projectsMemoryDir>/<project>/skills/<slug>/SKILL.md.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { scanContent } from "./content-scanner.js";
+import {
+  buildSkillId,
+  exists,
+  formatFrontmatter,
+  jaccardSimilarity,
+  parseFrontmatter,
+  parseSkillId,
+  slugify,
+  today,
+  tokenizeForSimilarity,
+} from "./skill-utils.js";
+import type { SkillDocument, SkillIndex, SkillResult, SkillScope } from "../types.js";
+import { AGENT_ROOT } from "../paths.js";
+
+interface SkillStoreOptions {
+  /** Where this extension writes global skills. Never Pi's own root. */
+  globalSkillsDir?: string;
+  /** Pi's global skills root, consulted read-only to refuse shadowed writes. */
+  piGlobalSkillsDir?: string;
+  projectSkillsDir?: string | null;
+  projectName?: string | null;
+  legacySkillsDir?: string;
+  migrationSentinelPath?: string;
+}
+
+interface SkillLocation {
+  skillId: string;
+  scope: SkillScope;
+  slug: string;
+  fileName: string;
+  path: string;
+  projectName?: string;
+}
+
+export interface LegacySkillMigrationResult {
+  migrated: number;
+  skipped: number;
+  warnings: string[];
+}
+
+const LIST_SECTIONS = new Set(["procedure", "pitfalls", "verification"]);
+
+function normalizeSectionName(section: string): string {
+  return section.replace(/^#+\s*/, "").trim();
+}
+
+function isExactSectionHeader(line: string, section: string): boolean {
+  const heading = line.trim().match(/^##\s+(.+?)\s*$/);
+  if (!heading) return false;
+  return heading[1].trim().toLowerCase() === section.trim().toLowerCase();
+}
+
+function looksLikeJsonArray(content: string): boolean {
+  const trimmed = content.trim();
+  return trimmed.startsWith("[") && trimmed.endsWith("]");
+}
+
+function looksLikeJsonObject(content: string): boolean {
+  const trimmed = content.trim();
+  return trimmed.startsWith("{") && trimmed.endsWith("}");
+}
+
+function formatPatchList(section: string, items: string[]): string {
+  const cleaned = items.map((item) => item.trim()).filter(Boolean);
+  if (cleaned.length === 0) return "";
+  const key = section.trim().toLowerCase();
+  if (key === "pitfalls") {
+    return cleaned.map((item) => `- ${item.replace(/^[-*]\s+/, "")}`).join("\n");
+  }
+  // Procedure / Verification default to ordered steps.
+  return cleaned
+    .map((item, index) => `${index + 1}. ${item.replace(/^\d+\.\s+/, "").replace(/^[-*]\s+/, "")}`)
+    .join("\n");
+}
+
+/**
+ * Normalize/validate free-form patch content so LLM format drift cannot wipe
+ * or splice skill sections. Coerces JSON string arrays into Markdown lists for
+ * list-shaped sections and rejects empty / object / header-injecting payloads.
+ */
+export function normalizeSkillPatchContent(
+  section: string,
+  rawContent: string,
+): { content: string } | { error: string } {
+  const sectionName = normalizeSectionName(section);
+  if (!sectionName) {
+    return { error: "section is required for patch." };
+  }
+
+  let content = typeof rawContent === "string" ? rawContent.trim() : "";
+  if (!content) {
+    return {
+      error: "New content is required for patch. Prefer structured fields (procedure_steps, pitfalls, verification_steps, when_to_use) over free-form content.",
+    };
+  }
+
+  if (looksLikeJsonObject(content)) {
+    return {
+      error: "Patch content looks like a JSON object. Provide Markdown section body or a string array via structured fields.",
+    };
+  }
+
+  if (looksLikeJsonArray(content)) {
+    try {
+      const parsed: unknown = JSON.parse(content);
+      if (!Array.isArray(parsed)) {
+        return { error: "Patch content looks like JSON but is not a string array." };
+      }
+      const items = parsed
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+      if (items.length === 0) {
+        return { error: "Patch content JSON array must contain non-empty strings." };
+      }
+      const key = sectionName.toLowerCase();
+      if (key === "when to use") {
+        content = items.join("\n\n");
+      } else if (LIST_SECTIONS.has(key)) {
+        content = formatPatchList(sectionName, items);
+      } else {
+        content = items.map((item) => `- ${item}`).join("\n");
+      }
+    } catch {
+      return {
+        error: "Patch content looks like a JSON array but could not be parsed. Use Markdown or structured string[] fields.",
+      };
+    }
+  }
+
+  // Reject payloads that would inject extra ## sections mid-body.
+  if (/^#{1,6}\s+\S/m.test(content)) {
+    return {
+      error: "Patch content must not include Markdown section headers (## ...). Patch only the body of the target section.",
+    };
+  }
+
+  if (!content.trim()) {
+    return { error: "New content is required for patch." };
+  }
+
+  return { content: content.trim() };
+}
+
+
+export class SkillStore {
+  private globalSkillsDir: string;
+  private piGlobalSkillsDir: string;
+  private projectSkillsDir: string | null;
+  private projectName: string | null;
+  private legacySkillsDir: string;
+  private migrationSentinelPath: string;
+
+  constructor(options: SkillStoreOptions = {}) {
+    const agentRoot = AGENT_ROOT;
+    this.globalSkillsDir = options.globalSkillsDir ?? path.join(agentRoot, "pi-hermes-memory", "skills");
+    this.piGlobalSkillsDir = options.piGlobalSkillsDir ?? path.join(agentRoot, "skills");
+    this.projectSkillsDir = options.projectSkillsDir ?? null;
+    this.projectName = options.projectName ?? null;
+    this.legacySkillsDir = options.legacySkillsDir ?? path.join(agentRoot, "memory", "skills");
+    this.migrationSentinelPath = options.migrationSentinelPath
+      ?? path.join(agentRoot, "pi-hermes-memory", ".skills-migrated-to-extension-storage");
+  }
+
+  getGlobalSkillsDir(): string {
+    return this.globalSkillsDir;
+  }
+
+  /**
+   * Pi's own global skills root. Read-only from here: we never create, patch,
+   * or delete inside it. It is consulted solely to refuse writes that Pi would
+   * silently shadow (see `findShadowingPiGlobalSkill`).
+   */
+  getPiGlobalSkillsDir(): string {
+    return this.piGlobalSkillsDir;
+  }
+
+  getProjectSkillsDir(): string | null {
+    return this.projectSkillsDir;
+  }
+
+  getProjectName(): string | null {
+    return this.projectName;
+  }
+
+  setProjectContext(projectName: string | null, projectSkillsDir: string | null): void {
+    this.projectName = projectName;
+    this.projectSkillsDir = projectSkillsDir;
+  }
+
+  async ensureDiscoveredRoots(): Promise<void> {
+    await fs.mkdir(this.globalSkillsDir, { recursive: true });
+    if (this.projectSkillsDir) {
+      await fs.mkdir(this.projectSkillsDir, { recursive: true });
+    }
+  }
+
+  async migrateLegacySkills(): Promise<LegacySkillMigrationResult> {
+    const result: LegacySkillMigrationResult = { migrated: 0, skipped: 0, warnings: [] };
+
+    // Always normalize flat markdown files under the global skills root,
+    // even when a previous migration sentinel already exists.
+    await this.migrateFlatMarkdownInGlobalSkillsDir(result);
+
+    if (await exists(this.migrationSentinelPath)) return result;
+
+    await fs.mkdir(path.dirname(this.migrationSentinelPath), { recursive: true });
+
+    // Only this migration's own warnings may hold back its sentinel — a
+    // permanently shadowed skill reported above must not make it retry forever.
+    const warningsBefore = result.warnings.length;
+    try {
+      await this.migrateLegacyMarkdownSkills(result);
+    } finally {
+      if (result.warnings.length === warningsBefore) {
+        await fs.writeFile(this.migrationSentinelPath, `${new Date().toISOString()}\n`, "utf-8");
+      }
+    }
+
+    return result;
+  }
+
+  private async migrateLegacyMarkdownSkills(result: LegacySkillMigrationResult): Promise<void> {
+    if (!await exists(this.legacySkillsDir)) return;
+
+    const files = (await fs.readdir(this.legacySkillsDir))
+      .filter((file) => file.endsWith(".md"))
+      .sort();
+
+    for (const file of files) {
+      const legacyPath = path.join(this.legacySkillsDir, file);
+      try {
+        const raw = await fs.readFile(legacyPath, "utf-8");
+        const parsed = parseFrontmatter(raw);
+        const fallbackSlug = slugify(path.basename(file, ".md"));
+        const slug = slugify(parsed.meta.name || fallbackSlug);
+        if (!slug) {
+          result.skipped++;
+          continue;
+        }
+
+        const targetPath = path.join(this.globalSkillsDir, slug, "SKILL.md");
+        if (await exists(targetPath)) {
+          result.skipped++;
+          continue;
+        }
+
+        const skillDoc = {
+          name: slug,
+          displayName: parsed.meta.display_name?.trim() || parsed.meta.name?.trim() || undefined,
+          description: parsed.meta.description?.trim() || `Migrated legacy skill: ${slug}`,
+          version: Number.parseInt(parsed.meta.version || "1", 10) || 1,
+          created: parsed.meta.created || today(),
+          updated: parsed.meta.updated || today(),
+          body: parsed.body || `# ${slug}\n`,
+        };
+
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await this.atomicWrite(targetPath, formatFrontmatter(skillDoc));
+        result.migrated++;
+      } catch (error) {
+        result.warnings.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  private async migrateFlatMarkdownInGlobalSkillsDir(result: LegacySkillMigrationResult): Promise<void> {
+    if (!await exists(this.globalSkillsDir)) return;
+
+    const files = (await fs.readdir(this.globalSkillsDir))
+      .filter((file) => file.endsWith(".md") && file !== "SKILL.md")
+      .sort();
+
+    for (const file of files) {
+      const legacyPath = path.join(this.globalSkillsDir, file);
+      try {
+        const raw = await fs.readFile(legacyPath, "utf-8");
+        const parsed = parseFrontmatter(raw);
+        const fallbackSlug = slugify(path.basename(file, ".md"));
+        const slug = slugify(parsed.meta.name || fallbackSlug);
+        if (!slug) {
+          result.skipped++;
+          continue;
+        }
+
+        const targetPath = path.join(this.globalSkillsDir, slug, "SKILL.md");
+        if (await exists(targetPath)) {
+          await fs.rm(legacyPath, { force: true });
+          result.skipped++;
+          continue;
+        }
+
+        const skillDoc = {
+          name: slug,
+          displayName: parsed.meta.display_name?.trim() || parsed.meta.name?.trim() || undefined,
+          description: parsed.meta.description?.trim() || `Migrated legacy skill: ${slug}`,
+          version: Number.parseInt(parsed.meta.version || "1", 10) || 1,
+          created: parsed.meta.created || today(),
+          updated: parsed.meta.updated || today(),
+          body: parsed.body || `# ${slug}\n`,
+        };
+
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await this.atomicWrite(targetPath, formatFrontmatter(skillDoc));
+        await fs.rm(legacyPath, { force: true });
+        result.migrated++;
+      } catch (error) {
+        result.warnings.push(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+  }
+
+  /**
+   * Is `slug` already claimed by a skill in Pi's own global root?
+   *
+   * Pi keys skills by name, first-loaded wins, and `~/.selesai/agent/skills/` is
+   * auto-discovered at higher precedence than anything an extension contributes
+   * via `resources_discover`. A global skill we write under a name that also
+   * exists there is never the copy Pi loads, so the write succeeds on disk and
+   * changes nothing about the agent's behaviour — silent write-loss (#125).
+   *
+   * Callers refuse the write and name both paths instead, which makes the
+   * shadowed state impossible to create rather than merely reported after the
+   * fact. Returns the shadowing path, or null when the name is free.
+   */
+  private async findShadowingPiGlobalSkill(slug: string): Promise<string | null> {
+    if (path.resolve(this.piGlobalSkillsDir) === path.resolve(this.globalSkillsDir)) return null;
+    const candidate = path.join(this.piGlobalSkillsDir, slug, "SKILL.md");
+    return await exists(candidate) ? candidate : null;
+  }
+
+  async loadIndex(scope?: SkillScope): Promise<SkillIndex[]> {
+    const locations = await this.collectLocations(scope);
+    const skills: SkillIndex[] = [];
+
+    for (const location of locations) {
+      const doc = await this.readLocation(location);
+      if (doc) skills.push(this.toIndex(doc));
+    }
+
+    return skills.sort((a, b) => {
+      if (a.updated !== b.updated) return b.updated.localeCompare(a.updated);
+      if (a.created !== b.created) return b.created.localeCompare(a.created);
+      if (a.scope !== b.scope) return a.scope.localeCompare(b.scope);
+      return (a.displayName || a.name).localeCompare(b.displayName || b.name);
+    });
+  }
+
+  async loadSkill(skillId: string): Promise<SkillDocument | null> {
+    const location = await this.findLocationById(skillId);
+    if (!location) return null;
+    return this.readLocation(location);
+  }
+
+  async create(name: string, description: string, body: string, scope?: SkillScope): Promise<SkillResult> {
+    name = name.trim();
+    description = description.trim();
+    body = body.trim();
+
+    if (!name) return { success: false, error: "Skill name is required." };
+    if (!description) return { success: false, error: "Skill description is required." };
+    if (!body) return { success: false, error: "Skill body is required." };
+
+    const scanError = scanContent(`${name} ${description} ${body}`);
+    if (scanError) return { success: false, error: scanError };
+
+    const slug = slugify(name);
+    if (!slug) return { success: false, error: "Skill name produces empty slug." };
+
+    const resolvedScope = this.resolveScope(scope, name, description, body);
+    const root = this.getScopeRoot(resolvedScope);
+    if (!root) {
+      return { success: false, error: "Project skills require an active project." };
+    }
+
+    const skillId = buildSkillId(resolvedScope, slug, this.projectName);
+    const existing = await this.findLocationById(skillId);
+    if (existing) {
+      return {
+        success: false,
+        error: `Skill '${slug}' already exists (${skillId}). Use 'patch' or 'update' to update it.`,
+        conflictType: "duplicate",
+        similarSkillIds: [skillId],
+        suggestedAction: "patch",
+      };
+    }
+
+    if (resolvedScope === "global") {
+      const similarSkillIds = await this.findSimilarGlobalSkillIds(slug, description);
+      if (similarSkillIds.length > 0) {
+        const targetId = similarSkillIds[0];
+        return {
+          success: false,
+          error: `A similar global skill already exists (${targetId}). Enhance the existing skill with new learnings/failures using 'patch' or 'update' instead of creating a duplicate.`,
+          conflictType: "similar",
+          similarSkillIds,
+          suggestedAction: "patch",
+        };
+      }
+
+      const collidingNameSkillIds = await this.findNameCollisionGlobalSkillIds(slug, description);
+      if (collidingNameSkillIds.length > 0) {
+        const targetId = collidingNameSkillIds[0];
+        return {
+          success: false,
+          error: `A near-name global skill already exists (${targetId}) but with different intent. Use a clearer differentiated name for the new skill, or patch/update the existing skill if the intent is actually the same.`,
+          conflictType: "name-collision",
+          similarSkillIds: collidingNameSkillIds,
+          suggestedAction: "rename",
+        };
+      }
+
+      const shadowedBy = await this.findShadowingPiGlobalSkill(slug);
+      if (shadowedBy) {
+        return {
+          success: false,
+          error: `Pi already loads a global skill named '${slug}' from ${shadowedBy}. `
+            + `Pi keys skills by name and loads its own root first, so a skill written to `
+            + `${path.join(this.globalSkillsDir, slug, "SKILL.md")} would never be the copy in effect. `
+            + `Choose a different name, or edit ${shadowedBy} directly.`,
+          conflictType: "name-collision",
+          suggestedAction: "rename",
+        };
+      }
+    }
+
+    const filePath = path.join(root, slug, "SKILL.md");
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+    const displayName = name;
+    const storedName = slug;
+    const stamp = today();
+    await this.atomicWrite(filePath, formatFrontmatter({
+      name: storedName,
+      displayName,
+      description,
+      version: 1,
+      created: stamp,
+      updated: stamp,
+      body,
+    }));
+
+    return {
+      success: true,
+      message: `Skill '${displayName}' created as a ${resolvedScope} skill.`,
+      fileName: path.basename(filePath),
+      skillId,
+      scope: resolvedScope,
+      path: filePath,
+    };
+  }
+
+  async patch(skillId: string, section: string, newContent: string): Promise<SkillResult> {
+    const sectionName = normalizeSectionName(section);
+    if (!sectionName) return { success: false, error: "section is required for patch." };
+
+    const normalized = normalizeSkillPatchContent(sectionName, newContent);
+    if ("error" in normalized) return { success: false, error: normalized.error };
+    const content = normalized.content;
+
+    const scanError = scanContent(content);
+    if (scanError) return { success: false, error: scanError };
+
+    const doc = await this.loadSkill(skillId);
+    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
+
+    const sectionHeader = `## ${sectionName}`;
+    const lines = doc.body.split("\n");
+    let found = false;
+    const result: string[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+      if (isExactSectionHeader(lines[i], sectionName)) {
+        result.push(sectionHeader);
+        // Preserve multi-line body as discrete lines so later headers stay exact.
+        for (const bodyLine of content.split("\n")) {
+          result.push(bodyLine);
+        }
+        found = true;
+        i++;
+        while (i < lines.length && !lines[i].trim().startsWith("## ")) i++;
+        if (i < lines.length) result.push(lines[i]);
+      } else {
+        result.push(lines[i]);
+      }
+    }
+
+    if (!found) {
+      if (result.length > 0 && result[result.length - 1] !== "") result.push("");
+      result.push(sectionHeader);
+      for (const bodyLine of content.split("\n")) {
+        result.push(bodyLine);
+      }
+    }
+
+    await this.atomicWrite(doc.path, formatFrontmatter({
+      name: doc.name,
+      displayName: doc.displayName,
+      description: doc.description,
+      version: doc.version + 1,
+      created: doc.created,
+      updated: today(),
+      body: result.join("\n").trim(),
+    }));
+
+    return {
+      success: true,
+      message: `Skill '${doc.displayName || doc.name}' section '${sectionName}' updated.`,
+      fileName: doc.fileName,
+      skillId: doc.skillId,
+      scope: doc.scope,
+      path: doc.path,
+    };
+  }
+
+  async edit(skillId: string, description: string, body: string): Promise<SkillResult> {
+    description = description.trim();
+    body = body.trim();
+
+    if (!description && !body) {
+      return { success: false, error: "At least one of description or body is required." };
+    }
+
+    const doc = await this.loadSkill(skillId);
+    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
+
+    const newDescription = description || doc.description;
+    const newBody = body || doc.body;
+    const scanError = scanContent(`${newDescription} ${newBody}`);
+    if (scanError) return { success: false, error: scanError };
+
+    await this.atomicWrite(doc.path, formatFrontmatter({
+      name: doc.name,
+      displayName: doc.displayName,
+      description: newDescription,
+      version: doc.version + 1,
+      created: doc.created,
+      updated: today(),
+      body: newBody,
+    }));
+
+    return {
+      success: true,
+      message: `Skill '${doc.displayName || doc.name}' updated.`,
+      fileName: doc.fileName,
+      skillId: doc.skillId,
+      scope: doc.scope,
+      path: doc.path,
+    };
+  }
+
+  async move(skillId: string, targetScope: SkillScope): Promise<SkillResult> {
+    const doc = await this.loadSkill(skillId);
+    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
+
+    const parsed = parseSkillId(skillId);
+    if (!parsed) return { success: false, error: `Skill '${skillId}' is invalid.` };
+
+    if (doc.scope === targetScope) {
+      return {
+        success: true,
+        message: `Skill '${doc.displayName || doc.name}' is already ${targetScope}.`,
+        fileName: doc.fileName,
+        skillId: doc.skillId,
+        scope: doc.scope,
+        path: doc.path,
+      };
+    }
+
+    const targetRoot = this.getScopeRoot(targetScope);
+    if (!targetRoot) {
+      return { success: false, error: "Project skills require an active project." };
+    }
+
+    const targetSkillId = buildSkillId(targetScope, parsed.slug, this.projectName);
+    const targetPath = path.join(targetRoot, parsed.slug, "SKILL.md");
+    if (await exists(targetPath)) {
+      return {
+        success: false,
+        error: `Cannot move '${doc.displayName || doc.name}' to ${targetScope}: ${targetSkillId} already exists.`,
+        conflictType: "scope-conflict",
+        similarSkillIds: [targetSkillId],
+        suggestedAction: "rename",
+      };
+    }
+
+    if (targetScope === "global") {
+      const similarSkillIds = await this.findSimilarGlobalSkillIds(parsed.slug, doc.description);
+      if (similarSkillIds.length > 0) {
+        const targetId = similarSkillIds[0];
+        return {
+          success: false,
+          error: `Cannot move '${doc.displayName || doc.name}' to global: a similar global skill already exists (${targetId}).`,
+          conflictType: "similar",
+          similarSkillIds,
+          suggestedAction: "patch",
+        };
+      }
+
+      const collidingNameSkillIds = await this.findNameCollisionGlobalSkillIds(parsed.slug, doc.description);
+      if (collidingNameSkillIds.length > 0) {
+        const targetId = collidingNameSkillIds[0];
+        return {
+          success: false,
+          error: `Cannot move '${doc.displayName || doc.name}' to global: a near-name global skill already exists (${targetId}) with different intent.`,
+          conflictType: "name-collision",
+          similarSkillIds: collidingNameSkillIds,
+          suggestedAction: "rename",
+        };
+      }
+    }
+
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+
+    // Same-filesystem move: use rename first for atomicity and to avoid duplicate windows.
+    try {
+      await fs.rename(doc.path, targetPath);
+
+      if (path.basename(doc.path) === "SKILL.md") {
+        await this.removeEmptyParents(path.dirname(doc.path), this.getScopeRoot(doc.scope));
+      }
+
+      return {
+        success: true,
+        message: `Skill '${doc.displayName || doc.name}' moved to ${targetScope}.`,
+        fileName: path.basename(targetPath),
+        skillId: targetSkillId,
+        scope: targetScope,
+        path: targetPath,
+      };
+    } catch (renameError) {
+      const code = (renameError as NodeJS.ErrnoException)?.code;
+      if (code !== "EXDEV") {
+        return {
+          success: false,
+          error: `Move to ${targetScope} failed before copy for skill '${skillId}'. Source path: ${doc.path}. Destination path: ${targetPath}. Error: ${renameError instanceof Error ? renameError.message : String(renameError)}`,
+        };
+      }
+      // Cross-device fallback below.
+    }
+
+    // Cross-device fallback: copy then remove source.
+    await this.atomicWrite(targetPath, formatFrontmatter({
+      name: parsed.slug,
+      displayName: doc.displayName,
+      description: doc.description,
+      version: doc.version,
+      created: doc.created,
+      updated: doc.updated,
+      body: doc.body,
+    }));
+
+    try {
+      await fs.unlink(doc.path);
+      if (path.basename(doc.path) === "SKILL.md") {
+        await this.removeEmptyParents(path.dirname(doc.path), this.getScopeRoot(doc.scope));
+      }
+    } catch (error) {
+      // Best-effort rollback: remove the destination copy if source removal fails,
+      // so we do not silently leave duplicate skills across scopes.
+      let rollbackFailed = false;
+      try {
+        await fs.unlink(targetPath);
+        if (path.basename(targetPath) === "SKILL.md") {
+          await this.removeEmptyParents(path.dirname(targetPath), this.getScopeRoot(targetScope));
+        }
+      } catch {
+        rollbackFailed = true;
+      }
+
+      return {
+        success: false,
+        error: rollbackFailed
+          ? `Move to ${targetScope} failed while removing source skill '${skillId}', and rollback also failed. Source path: ${doc.path}. Destination path: ${targetPath}. Error: ${error instanceof Error ? error.message : String(error)}`
+          : `Move to ${targetScope} failed while removing source skill '${skillId}'. Rolled back destination copy. Source path: ${doc.path}. Destination path: ${targetPath}. Error: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+
+    return {
+      success: true,
+      message: `Skill '${doc.displayName || doc.name}' moved to ${targetScope}.`,
+      fileName: path.basename(targetPath),
+      skillId: targetSkillId,
+      scope: targetScope,
+      path: targetPath,
+    };
+  }
+
+  async delete(skillId: string): Promise<SkillResult> {
+    const doc = await this.loadSkill(skillId);
+    if (!doc) return { success: false, error: `Skill '${skillId}' not found.` };
+
+    await fs.unlink(doc.path);
+    if (path.basename(doc.path) === "SKILL.md") {
+      await this.removeEmptyParents(path.dirname(doc.path), this.getScopeRoot(doc.scope));
+    }
+
+    return {
+      success: true,
+      message: `Skill '${doc.displayName || doc.name}' deleted.`,
+      fileName: doc.fileName,
+      skillId: doc.skillId,
+      scope: doc.scope,
+      path: doc.path,
+    };
+  }
+
+  private resolveScope(scope: SkillScope | undefined, name: string, description: string, body: string): SkillScope {
+    if (scope) return scope;
+    if (!this.projectSkillsDir || !this.projectName) return "global";
+
+    const haystack = `${name}\n${description}\n${body}`.toLowerCase();
+    const projectLower = this.projectName.toLowerCase();
+
+    const strongSignals = [
+      haystack.includes(projectLower),
+      /\bthis repo\b|\bthis repository\b|\bthis project\b|\bour codebase\b|\bour app\b/.test(haystack),
+      /\bpackage\.json\b|\bpnpm-lock\.yaml\b|\byarn\.lock\b|\btsconfig\.json\b|\bdocker-compose(\.ya?ml)?\b|\b\.env(\.[a-z0-9._-]+)?\b/.test(haystack),
+      /(^|\s)(src|app|apps|packages|services|scripts|tests|docs|infra|migrations|db|api|web|frontend|backend)\/[a-z0-9._/-]+/m.test(haystack),
+      /\b(npm|pnpm|yarn|bun)\s+(run|test|build|dev|lint|deploy)\b/.test(haystack),
+    ].filter(Boolean).length;
+
+    const weakerSignals = [
+      /\bdeploy\b|\brelease\b|\bmigrate\b|\bmonorepo\b|\bworkspace\b|\bstaging\b|\bproduction\b/.test(haystack),
+      /\bteam convention\b|\bcodebase convention\b|\brepo convention\b/.test(haystack),
+    ].filter(Boolean).length;
+
+    return strongSignals >= 2 || (strongSignals >= 1 && weakerSignals >= 1) ? "project" : "global";
+  }
+
+  private getScopeRoot(scope: SkillScope): string | null {
+    return scope === "global" ? this.globalSkillsDir : this.projectSkillsDir;
+  }
+
+  private async findSimilarGlobalSkillIds(candidateSlug: string, candidateDescription: string): Promise<string[]> {
+    const NAME_SIMILARITY_THRESHOLD = 0.7;
+    const DESCRIPTION_SIMILARITY_THRESHOLD = 0.75;
+
+    const scored = await this.scoreGlobalSimilarity(candidateSlug, candidateDescription);
+
+    return scored
+      .filter((entry) => entry.nameSimilarity > NAME_SIMILARITY_THRESHOLD
+        && entry.descriptionSimilarity > DESCRIPTION_SIMILARITY_THRESHOLD)
+      .map((entry) => entry.skillId);
+  }
+
+  private async findNameCollisionGlobalSkillIds(candidateSlug: string, candidateDescription: string): Promise<string[]> {
+    const NAME_SIMILARITY_THRESHOLD = 0.7;
+    const DESCRIPTION_SIMILARITY_THRESHOLD = 0.75;
+
+    const scored = await this.scoreGlobalSimilarity(candidateSlug, candidateDescription);
+
+    return scored
+      .filter((entry) => entry.nameSimilarity > NAME_SIMILARITY_THRESHOLD
+        && entry.descriptionSimilarity <= DESCRIPTION_SIMILARITY_THRESHOLD)
+      .map((entry) => entry.skillId);
+  }
+
+  private async scoreGlobalSimilarity(
+    candidateSlug: string,
+    candidateDescription: string,
+  ): Promise<Array<{ skillId: string; nameSimilarity: number; descriptionSimilarity: number }>> {
+    const globals = await this.loadIndex("global");
+    const candidateNameTokens = tokenizeForSimilarity(candidateSlug.replace(/-/g, " "));
+    const candidateDescriptionTokens = tokenizeForSimilarity(candidateDescription);
+
+    return globals
+      .map((skill) => {
+        const nameTokens = tokenizeForSimilarity((skill.displayName || skill.name).replace(/-/g, " "));
+        const descriptionTokens = tokenizeForSimilarity(skill.description || "");
+        const nameSimilarity = jaccardSimilarity(candidateNameTokens, nameTokens);
+        const descriptionSimilarity = jaccardSimilarity(candidateDescriptionTokens, descriptionTokens);
+
+        return {
+          skillId: skill.skillId,
+          nameSimilarity,
+          descriptionSimilarity,
+        };
+      })
+      .sort((a, b) => {
+        const byName = b.nameSimilarity - a.nameSimilarity;
+        if (Math.abs(byName) > 0.0001) return byName;
+        return b.descriptionSimilarity - a.descriptionSimilarity;
+      });
+  }
+
+  private async collectLocations(scope?: SkillScope): Promise<SkillLocation[]> {
+    const locations: SkillLocation[] = [];
+    const seen = new Set<string>();
+
+    if (!scope || scope === "global") {
+      const globalLocations = await this.scanScope(this.globalSkillsDir, "global", true, this.projectName ?? undefined);
+      for (const location of globalLocations) {
+        if (seen.has(location.skillId)) continue;
+        seen.add(location.skillId);
+        locations.push(location);
+      }
+    }
+
+    if ((!scope || scope === "project") && this.projectSkillsDir && this.projectName) {
+      const projectLocations = await this.scanScope(this.projectSkillsDir, "project", false, this.projectName);
+      for (const location of projectLocations) {
+        if (seen.has(location.skillId)) continue;
+        seen.add(location.skillId);
+        locations.push(location);
+      }
+    }
+
+    return locations;
+  }
+
+  private async scanScope(
+    root: string,
+    scope: SkillScope,
+    allowRootMarkdown: boolean,
+    projectName?: string,
+  ): Promise<SkillLocation[]> {
+    if (!await exists(root)) return [];
+    const results: SkillLocation[] = [];
+
+    const walk = async (dir: string, isRoot: boolean): Promise<void> => {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      const dirs = entries.filter((entry) => entry.isDirectory()).sort((a, b) => a.name.localeCompare(b.name));
+      const files = entries.filter((entry) => entry.isFile()).sort((a, b) => a.name.localeCompare(b.name));
+
+      for (const entry of dirs) {
+        if (entry.name.startsWith(".")) continue;
+        const childDir = path.join(dir, entry.name);
+        const skillFile = path.join(childDir, "SKILL.md");
+        if (await exists(skillFile)) {
+          results.push({
+            skillId: buildSkillId(scope, entry.name, projectName),
+            scope,
+            slug: entry.name,
+            fileName: "SKILL.md",
+            path: skillFile,
+            projectName,
+          });
+        }
+        await walk(childDir, false);
+      }
+
+      if (!isRoot || !allowRootMarkdown) return;
+
+      for (const entry of files) {
+        if (!entry.name.endsWith(".md") || entry.name === "SKILL.md") continue;
+        const slug = slugify(path.basename(entry.name, ".md"));
+        if (!slug) continue;
+        results.push({
+          skillId: buildSkillId(scope, slug, projectName),
+          scope,
+          slug,
+          fileName: entry.name,
+          path: path.join(dir, entry.name),
+          projectName,
+        });
+      }
+    };
+
+    await walk(root, true);
+    return results;
+  }
+
+  private async findLocationById(skillId: string): Promise<SkillLocation | null> {
+    const parsed = parseSkillId(skillId);
+    if (!parsed) return null;
+
+    const locations = await this.collectLocations(parsed.scope);
+    return locations.find((location) => location.skillId === skillId) ?? null;
+  }
+
+  private async readLocation(location: SkillLocation): Promise<SkillDocument | null> {
+    try {
+      const raw = await fs.readFile(location.path, "utf-8");
+      const { meta, body } = parseFrontmatter(raw);
+      const skillName = meta.name?.trim() || location.slug;
+      const displayName = meta.display_name?.trim() || undefined;
+      return {
+        skillId: location.skillId,
+        scope: location.scope,
+        fileName: location.fileName,
+        path: location.path,
+        projectName: location.projectName,
+        name: skillName,
+        displayName,
+        description: meta.description?.trim() || "",
+        version: Number.parseInt(meta.version || "1", 10) || 1,
+        created: meta.created || today(),
+        updated: meta.updated || today(),
+        body,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  private toIndex(doc: SkillDocument): SkillIndex {
+    return {
+      skillId: doc.skillId,
+      scope: doc.scope,
+      fileName: doc.fileName,
+      path: doc.path,
+      projectName: doc.projectName,
+      name: doc.name,
+      displayName: doc.displayName,
+      description: doc.description,
+      created: doc.created,
+      updated: doc.updated,
+    };
+  }
+
+  private async atomicWrite(filePath: string, content: string): Promise<void> {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+
+    const tempFile = path.join(
+      dir,
+      `.${path.basename(filePath)}.tmp-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+    );
+
+    await fs.writeFile(tempFile, content, "utf-8");
+    await fs.rename(tempFile, filePath);
+  }
+
+  private async removeEmptyParents(startDir: string, stopDir: string | null): Promise<void> {
+    if (!stopDir) return;
+
+    let current = startDir;
+    while (current.startsWith(stopDir) && current !== stopDir) {
+      try {
+        const entries = await fs.readdir(current);
+        if (entries.length > 0) return;
+        await fs.rmdir(current);
+        current = path.dirname(current);
+      } catch {
+        return;
+      }
+    }
+  }
+}