@winspan/claude-forge 8.51.1 → 8.53.2

package/src/skills/upgrade-engine.ts

@@ -0,0 +1,541 @@
+/**
+ * upgrade-engine.ts
+ *
+ * Orchestrates the AI-assisted official skill upgrade pipeline.
+ * Does NOT contain AI prompt strings — those live in upgrade-prompt.ts.
+ */
+
+import { execSync, exec } from 'node:child_process';
+import { promises as fs, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import matter from 'gray-matter';
+import type { OfficialSkill } from './official-skills.js';
+import { buildEvaluationPrompt } from './upgrade-prompt.js';
+import type { ClaudeProvider } from '../core/ai/provider.js';
+import { logger } from '../core/utils/logger.js';
+
+const execAsync = promisify(exec);
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+export interface CandidateSkill {
+  id: string;
+  source: string;        // 'agent-skills' | 'superpowers'
+  filePath: string;
+  name: string;
+  description: string;
+  keywords: string[];
+  content: string;
+}
+
+export interface MatchResult {
+  officialId: string;
+  score: number;         // 0-100
+}
+
+export type UpgradeAction = 'upgrade' | 'merge' | 'skip';
+
+export interface UpgradeDecision {
+  action: UpgradeAction;
+  confidence: number;    // 0-100
+  reasoning: string;
+  merged_content: string | null;
+}
+
+export interface ReportEntry {
+  officialId: string;
+  candidateId: string;
+  candidateSource: string;
+  action: UpgradeAction | 'error' | 'needs_review';
+  confidence: number;
+  reasoning: string;
+  candidateFilePath: string;
+  merged_content: string | null;
+}
+
+// ── Default candidate sources ───────────────────────────────────────────────
+
+export const DEFAULT_SOURCES: Array<{ name: string; url: string }> = [
+  { name: 'agent-skills', url: 'https://github.com/addyosmani/agent-skills.git' },
+  { name: 'superpowers',  url: 'https://github.com/obra/superpowers.git' },
+];
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Parse a .md file into a CandidateSkill.
+ * If frontmatter is missing, falls back to filename-based id.
+ */
+function parseCandidateFile(filePath: string, sourceName: string): CandidateSkill | null {
+  try {
+    const raw = readFileSync(filePath, 'utf-8');
+    const parsed = matter(raw);
+    const { data } = parsed;
+
+    const fileName = path.basename(filePath, '.md');
+    const id = typeof data.name === 'string' ? data.name : fileName;
+    const name = typeof data.name === 'string' ? data.name : fileName;
+    const description = typeof data.description === 'string' ? data.description : '';
+
+    const rawKeywords: unknown = data.keywords ?? data.tags;
+    const keywords: string[] = Array.isArray(rawKeywords)
+      ? rawKeywords.filter((k): k is string => typeof k === 'string')
+      : [];
+
+    return {
+      id,
+      source: sourceName,
+      filePath,
+      name,
+      description,
+      keywords,
+      content: raw,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Recursively scan a directory for .md files.
+ * Supports both directory/SKILL.md format (agent-skills) and flat *.md format.
+ */
+async function scanMdFiles(dir: string): Promise<string[]> {
+  const results: string[] = [];
+
+  async function walk(current: string): Promise<void> {
+    let entries: import('node:fs').Dirent[];
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        // Check for SKILL.md inside this directory (agent-skills format)
+        const skillMd = path.join(fullPath, 'SKILL.md');
+        try {
+          await fs.access(skillMd);
+          results.push(skillMd);
+        } catch {
+          // Recurse into sub-directories that don't have SKILL.md directly
+          await walk(fullPath);
+        }
+      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md') {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  await walk(dir);
+  return results;
+}
+
+// ── Exported pipeline functions ─────────────────────────────────────────────
+
+/**
+ * Clone or pull each source into `candidatesDir/<source.name>/`, then scan
+ * all .md files and parse them into CandidateSkill objects.
+ * Individual source failures are caught and logged; they do not abort the run.
+ */
+export async function pullCandidates(
+  sources: Array<{ name: string; url: string }>,
+  candidatesDir: string,
+): Promise<CandidateSkill[]> {
+  await fs.mkdir(candidatesDir, { recursive: true });
+
+  const candidates: CandidateSkill[] = [];
+
+  for (const source of sources) {
+    const targetDir = path.join(candidatesDir, source.name);
+
+    let exists = false;
+    try {
+      await fs.access(targetDir);
+      exists = true;
+    } catch { /* not exists */ }
+
+    // Try pull/clone, but don't abort scan if pull fails on existing dir
+    try {
+      if (exists) {
+        logger.info(`[upgrade] Pulling ${source.name}...`);
+        await execAsync(`git -C "${targetDir}" pull --ff-only`, { timeout: 60_000 });
+      } else {
+        logger.info(`[upgrade] Cloning ${source.name}...`);
+        await execAsync(`git clone --depth=1 "${source.url}" "${targetDir}"`, { timeout: 120_000 });
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (exists) {
+        logger.warn(`[upgrade] ${source.name} pull failed (using existing checkout): ${msg}`);
+      } else {
+        logger.warn(`[upgrade] ${source.name} clone failed, skipping: ${msg}`);
+        continue;
+      }
+    }
+
+    // Always scan if dir exists (even when pull fails — old checkout is better than nothing)
+    try {
+      const mdFiles = await scanMdFiles(targetDir);
+      for (const filePath of mdFiles) {
+        const candidate = parseCandidateFile(filePath, source.name);
+        if (candidate) {
+          candidates.push(candidate);
+        }
+      }
+      logger.info(`[upgrade] ${source.name}: ${mdFiles.length} .md files found`);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.warn(`[upgrade] Skipping source ${source.name}: ${msg}`);
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * Match a candidate skill to the best official skill using keyword + name token
+ * overlap. Returns null if the best score is below the 30-point threshold.
+ */
+export function matchToOfficial(
+  candidate: CandidateSkill,
+  officialSkills: OfficialSkill[],
+): MatchResult | null {
+  /** Tokenise a string into lowercase words / tokens. */
+  function tokenise(text: string): Set<string> {
+    return new Set(
+      text
+        .toLowerCase()
+        .replace(/[^a-z0-9一-鿿\s-]/g, ' ')
+        .split(/[\s-]+/)
+        .filter((t) => t.length > 1),
+    );
+  }
+
+  /** Jaccard-like overlap score (0–100). */
+  function overlapScore(aSet: Set<string>, bSet: Set<string>): number {
+    if (aSet.size === 0 && bSet.size === 0) return 0;
+    let intersection = 0;
+    for (const t of aSet) {
+      if (bSet.has(t)) intersection++;
+    }
+    const union = new Set([...aSet, ...bSet]).size;
+    return union === 0 ? 0 : Math.round((intersection / union) * 100);
+  }
+
+  const candidateKeywordTokens = tokenise(candidate.keywords.join(' '));
+  const candidateNameTokens = tokenise(candidate.name + ' ' + candidate.description);
+
+  let best: MatchResult | null = null;
+
+  for (const official of officialSkills) {
+    const officialKeywordTokens = tokenise(official.keywords.join(' '));
+    const officialNameTokens = tokenise(official.name + ' ' + official.description);
+
+    // keyword overlap (weight 60) + name/description token overlap (weight 40)
+    const keywordScore = overlapScore(candidateKeywordTokens, officialKeywordTokens);
+    const nameScore = overlapScore(candidateNameTokens, officialNameTokens);
+    let combined = Math.round(keywordScore * 0.6 + nameScore * 0.4);
+
+    // Substring boost: candidate id/name contains official keyword (or vice versa)
+    // helps with English↔中文 token mismatch (e.g. "debugging" ↔ "debug"/"调试")
+    const candidateText = (candidate.id + ' ' + candidate.name + ' ' + candidate.description).toLowerCase();
+    const officialText = (official.name + ' ' + official.description).toLowerCase();
+    for (const kw of official.keywords) {
+      const kwLower = kw.toLowerCase();
+      if (kwLower.length >= 3 && candidateText.includes(kwLower)) {
+        combined = Math.max(combined, 50);
+        break;
+      }
+    }
+    for (const kw of candidate.keywords) {
+      const kwLower = kw.toLowerCase();
+      if (kwLower.length >= 3 && officialText.includes(kwLower)) {
+        combined = Math.max(combined, 50);
+        break;
+      }
+    }
+
+    if (combined >= 15) {
+      if (!best || combined > best.score) {
+        best = { officialId: official.name, score: combined };
+      }
+    }
+  }
+
+  return best;
+}
+
+/**
+ * Ask the AI provider to evaluate whether a candidate should upgrade / merge /
+ * skip the matched official skill. Returns a parsed UpgradeDecision.
+ *
+ * On JSON parse failure → returns { action: 'skip', confidence: 0, reasoning:
+ * 'AI response could not be parsed', merged_content: null } with needs_review=true
+ * embedded in the reasoning (caller promotes to needs_review).
+ */
+export async function evaluateWithAI(
+  candidate: CandidateSkill,
+  official: OfficialSkill,
+  aiProvider: ClaudeProvider,
+): Promise<UpgradeDecision & { needs_review?: boolean }> {
+  const { system, user } = buildEvaluationPrompt(candidate, official);
+
+  let raw: string;
+  try {
+    raw = await aiProvider.complete(user, {
+      system,
+      maxTokens: 1200,
+      timeoutMs: 45_000,
+      maxRetries: 2,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      action: 'skip',
+      confidence: 0,
+      reasoning: `AI 调用失败: ${msg}`,
+      merged_content: null,
+      needs_review: true,
+    };
+  }
+
+  // Strip markdown code fences if model wrapped the JSON
+  const stripped = raw
+    .replace(/^```(?:json)?\s*/im, '')
+    .replace(/\s*```$/im, '')
+    .trim();
+
+  try {
+    const parsed = JSON.parse(stripped) as Record<string, unknown>;
+
+    const validActions = new Set<string>(['upgrade', 'merge', 'skip']);
+    const action = typeof parsed.action === 'string' && validActions.has(parsed.action)
+      ? (parsed.action as UpgradeAction)
+      : 'skip';
+
+    const confidence =
+      typeof parsed.confidence === 'number'
+        ? Math.max(0, Math.min(100, parsed.confidence))
+        : 0;
+
+    const reasoning =
+      typeof parsed.reasoning === 'string' ? parsed.reasoning : '';
+
+    const merged_content =
+      typeof parsed.merged_content === 'string' ? parsed.merged_content : null;
+
+    return { action, confidence, reasoning, merged_content };
+  } catch {
+    return {
+      action: 'skip',
+      confidence: 0,
+      reasoning: `AI 返回内容无法解析为 JSON，需人工审核。原始响应片段: ${stripped.slice(0, 200)}`,
+      merged_content: null,
+      needs_review: true,
+    };
+  }
+}
+
+/**
+ * Write the upgrade report as a markdown file with embedded HTML comment
+ * machine markers for `applyDecisions` to parse.
+ */
+export async function generateReport(
+  entries: ReportEntry[],
+  outputPath: string,
+  stats: { total: number; matched: number; unmatched: number },
+): Promise<void> {
+  const now = new Date();
+  const timestamp = now.toISOString().replace('T', ' ').slice(0, 16);
+
+  const actionCounts = { upgrade: 0, merge: 0, skip: 0, error: 0, needs_review: 0 };
+  for (const e of entries) {
+    if (e.action in actionCounts) {
+      actionCounts[e.action as keyof typeof actionCounts]++;
+    }
+  }
+
+  const lines: string[] = [
+    '# Skill Upgrade Report',
+    '',
+    `Generated: ${timestamp}`,
+    '',
+    '## Summary',
+    '',
+    '| Metric | Count |',
+    '|--------|-------|',
+    `| Candidates scanned | ${stats.total} |`,
+    `| Matched to official | ${stats.matched} |`,
+    `| Action: upgrade | ${actionCounts.upgrade} |`,
+    `| Action: merge | ${actionCounts.merge} |`,
+    `| Action: skip | ${actionCounts.skip} |`,
+    `| Needs review | ${actionCounts.needs_review} |`,
+    `| Error | ${actionCounts.error} |`,
+    `| Unmatched | ${stats.unmatched} |`,
+    '',
+    '## Per-Skill Decisions',
+    '',
+  ];
+
+  for (const entry of entries) {
+    lines.push(`### ${entry.officialId}`);
+    lines.push(`- **Action**: ${entry.action}`);
+    lines.push(`- **Confidence**: ${entry.confidence}%`);
+    lines.push(`- **Candidate**: \`${entry.candidateSource}/${entry.candidateId}\``);
+    lines.push(`- **Candidate path**: \`${entry.candidateFilePath}\``);
+    lines.push(`- **Reasoning**: ${entry.reasoning}`);
+
+    // Machine-readable marker for applyDecisions
+    lines.push('');
+    lines.push(`<!-- upgrade-entry: ${entry.officialId} | ${entry.candidateFilePath} | ${entry.action} -->`);
+
+    if (entry.action === 'merge' && entry.merged_content) {
+      lines.push('');
+      lines.push('<!-- merged-content-begin -->');
+      lines.push(entry.merged_content);
+      lines.push('<!-- merged-content-end -->');
+    }
+
+    lines.push('');
+  }
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, lines.join('\n'), 'utf-8');
+  logger.info(`[upgrade] Report written to ${outputPath}`);
+}
+
+/**
+ * Apply the decisions recorded in a report file to the official skills directory.
+ *
+ * Safety checks:
+ * 1. `git status --porcelain <officialDir>` must be clean
+ * 2. Full backup created in `backupBaseDir/<YYYYMMDD-HHMM>/` (conflict → -2/-3)
+ *
+ * Returns { applied, skipped, backupPath }.
+ */
+export async function applyDecisions(
+  reportPath: string,
+  officialDir: string,
+  backupBaseDir: string,
+): Promise<{ applied: number; skipped: number; backupPath: string }> {
+  // 1. Check git working tree is clean
+  try {
+    const { stdout } = await execAsync(`git status --porcelain "${officialDir}"`);
+    if (stdout.trim().length > 0) {
+      throw new Error(
+        `Working tree is dirty in ${officialDir}. Commit or stash changes before applying.\n${stdout}`,
+      );
+    }
+  } catch (err) {
+    // If git is not available or it's not a repo, rethrow only for dirty-tree errors
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes('Working tree is dirty')) throw err;
+    logger.warn(`[upgrade] git status check failed (not a git repo?): ${msg}`);
+  }
+
+  // 2. Create timestamped backup directory
+  const ts = new Date()
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace('T', '-')
+    .slice(0, 13); // YYYYMMDD-HHM -> need YYYYMMDD-HHMM format
+  const tsFormatted = (() => {
+    const d = new Date();
+    const YYYY = d.getFullYear();
+    const MM = String(d.getMonth() + 1).padStart(2, '0');
+    const DD = String(d.getDate()).padStart(2, '0');
+    const HH = String(d.getHours()).padStart(2, '0');
+    const mm = String(d.getMinutes()).padStart(2, '0');
+    return `${YYYY}${MM}${DD}-${HH}${mm}`;
+  })();
+
+  let backupPath = path.join(backupBaseDir, tsFormatted);
+  // Handle conflict: try -2, -3, ...
+  let suffix = 2;
+  while (true) {
+    try {
+      await fs.access(backupPath);
+      // Directory exists — try next suffix
+      backupPath = path.join(backupBaseDir, `${tsFormatted}-${suffix}`);
+      suffix++;
+    } catch {
+      break; // doesn't exist, we can use it
+    }
+  }
+  await fs.mkdir(backupPath, { recursive: true });
+
+  // Copy all .md files from officialDir into backup
+  const officialFiles = (await fs.readdir(officialDir)).filter((f) => f.endsWith('.md'));
+  for (const file of officialFiles) {
+    await fs.copyFile(path.join(officialDir, file), path.join(backupPath, file));
+  }
+  logger.info(`[upgrade] Backed up ${officialFiles.length} files to ${backupPath}`);
+
+  // 3. Parse report
+  const reportContent = await fs.readFile(reportPath, 'utf-8');
+
+  // Parse <!-- upgrade-entry: id | path | action --> markers
+  const entryPattern = /<!-- upgrade-entry: (.+?) \| (.+?) \| (.+?) -->/g;
+  let match: RegExpExecArray | null;
+
+  const entries: Array<{ officialId: string; candidatePath: string; action: string }> = [];
+  while ((match = entryPattern.exec(reportContent)) !== null) {
+    entries.push({
+      officialId: match[1].trim(),
+      candidatePath: match[2].trim(),
+      action: match[3].trim(),
+    });
+  }
+
+  // Parse merged content blocks
+  const mergedContentMap = new Map<string, string>();
+  // Associate merged-content blocks with the preceding entry
+  const mergedPattern =
+    /<!-- upgrade-entry: (.+?) \| (.+?) \| merge -->[\s\S]*?<!-- merged-content-begin -->\n([\s\S]*?)\n<!-- merged-content-end -->/g;
+  while ((match = mergedPattern.exec(reportContent)) !== null) {
+    mergedContentMap.set(match[1].trim(), match[3]);
+  }
+
+  let applied = 0;
+  let skipped = 0;
+
+  for (const entry of entries) {
+    if (entry.action === 'skip' || entry.action === 'error' || entry.action === 'needs_review') {
+      skipped++;
+      continue;
+    }
+
+    const targetFile = path.join(officialDir, `${entry.officialId}.md`);
+
+    try {
+      if (entry.action === 'upgrade') {
+        // Copy candidate file content
+        const candidateContent = await fs.readFile(entry.candidatePath, 'utf-8');
+        await fs.writeFile(targetFile, candidateContent, 'utf-8');
+        applied++;
+        logger.info(`[upgrade] Applied upgrade: ${entry.officialId}`);
+      } else if (entry.action === 'merge') {
+        const mergedContent = mergedContentMap.get(entry.officialId);
+        if (mergedContent) {
+          await fs.writeFile(targetFile, mergedContent, 'utf-8');
+          applied++;
+          logger.info(`[upgrade] Applied merge: ${entry.officialId}`);
+        } else {
+          logger.warn(`[upgrade] Merge entry ${entry.officialId} has no merged content; skipping`);
+          skipped++;
+        }
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.error(`[upgrade] Failed to apply ${entry.officialId}: ${msg}`);
+      skipped++;
+    }
+  }
+
+  logger.info(`[upgrade] Apply complete: ${applied} applied, ${skipped} skipped`);
+  return { applied, skipped, backupPath };
+}

package/src/skills/upgrade-prompt.ts

@@ -0,0 +1,84 @@
+/**
+ * upgrade-prompt.ts
+ *
+ * Builds the system + user prompts for AI-assisted skill evaluation.
+ * Pure functions — no I/O, no side effects.
+ */
+
+import type { CandidateSkill } from './upgrade-engine.js';
+import type { OfficialSkill } from './official-skills.js';
+
+const MAX_CONTENT_CHARS = 2000;
+
+/**
+ * Truncate content to at most `maxChars` characters, appending an ellipsis
+ * marker so the model knows the text was cut.
+ */
+function truncate(text: string, maxChars = MAX_CONTENT_CHARS): string {
+  if (text.length <= maxChars) return text;
+  return text.slice(0, maxChars) + '\n\n...[content truncated]';
+}
+
+/**
+ * Build system + user prompts for evaluating whether a candidate skill should
+ * upgrade, merge with, or skip an official skill.
+ *
+ * The system prompt defines the decision criteria and output JSON contract.
+ * The user prompt contains the two skill bodies (capped at 2000 chars each).
+ */
+export function buildEvaluationPrompt(
+  candidate: CandidateSkill,
+  official: OfficialSkill,
+): { system: string; user: string } {
+  const system = `你是 Claude Code skill 内容评估专家。
+
+你的任务是比较"候选 skill"和"官方 skill"，决定如何处理。
+
+## 评估维度
+- **主题重叠度**：两个 skill 覆盖的领域是否高度相关
+- **内容质量**：深度、广度、实例丰富程度、可操作性
+- **互补性**：候选是否包含官方 skill 未涵盖的独特章节
+
+## 决策标准
+- **skip**：主题不重叠，或官方 skill 已完整覆盖候选内容，合并无额外价值
+- **upgrade**：候选覆盖官方 skill 的全部核心要点，且整体质量明显更高（深度/广度提升 ≥30%），用候选直接替换官方版本
+- **merge**：主题相同但各有独特章节，合并后整体价值更高，需要生成合并后完整内容
+
+## 输出格式
+必须返回严格的 JSON，不含任何其他文本、代码块标记或注释：
+{"action":"upgrade|merge|skip","confidence":0-100,"reasoning":"简短中文说明（<200字）","merged_content":null或合并后完整md字符串}
+
+## merged_content 规则
+- action = merge  → 提供合并后的完整 .md 文件内容（含 frontmatter）
+- action = upgrade → null（直接使用候选原文）
+- action = skip   → null`;
+
+  const user = `## 官方 Skill（目标）
+
+**ID**: ${official.name}
+**描述**: ${official.description}
+**关键词**: ${official.keywords.join(', ') || '（无）'}
+
+\`\`\`markdown
+${truncate(official.content)}
+\`\`\`
+
+---
+
+## 候选 Skill（来源: ${candidate.source}）
+
+**ID**: ${candidate.id}
+**名称**: ${candidate.name}
+**描述**: ${candidate.description}
+**关键词**: ${candidate.keywords.join(', ') || '（无）'}
+
+\`\`\`markdown
+${truncate(candidate.content)}
+\`\`\`
+
+---
+
+请评估候选 skill 相对于官方 skill 的升级价值，返回 JSON。`;
+
+  return { system, user };
+}

package/tests/unit/daemon/skill-sync.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { syncSkills } from '../../../src/daemon/skill-sync.js';
+
+describe('syncSkills', () => {
+  let tmpRoot: string;
+  let sourceDir: string;
+  let targetDir: string;
+
+  beforeEach(() => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'forge-skill-sync-'));
+    sourceDir = join(tmpRoot, 'src-skills');
+    targetDir = join(tmpRoot, 'target-skills');
+    mkdirSync(sourceDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmpRoot, { recursive: true, force: true });
+  });
+
+  it('source dir not found → returns zero counts, does not throw', () => {
+    const result = syncSkills({ sourceDir: join(tmpRoot, 'nonexistent'), targetDir });
+    expect(result.copied).toBe(0);
+    expect(result.checked).toBe(0);
+    expect(result.skipped_userOwned).toBe(0);
+  });
+
+  it('source and target identical → copied=0, checked=1', () => {
+    const content = '# official-debug skill\nsome content\n';
+    writeFileSync(join(sourceDir, 'official-debug.md'), content);
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, 'official-debug.md'), content);
+
+    const result = syncSkills({ sourceDir, targetDir });
+    expect(result.copied).toBe(0);
+    expect(result.checked).toBe(1);
+  });
+
+  it('source and target differ → copied=1, target updated', () => {
+    writeFileSync(join(sourceDir, 'official-debug.md'), '# new content\n');
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, 'official-debug.md'), '# old content\n');
+
+    const result = syncSkills({ sourceDir, targetDir });
+    expect(result.copied).toBe(1);
+    expect(result.checked).toBe(1);
+    expect(readFileSync(join(targetDir, 'official-debug.md'), 'utf-8')).toContain('new content');
+  });
+
+  it('target missing file → copies it from source', () => {
+    writeFileSync(join(sourceDir, 'official-debug.md'), '# official-debug\n');
+    mkdirSync(targetDir, { recursive: true });
+    // target has no official-debug.md
+
+    const result = syncSkills({ sourceDir, targetDir });
+    expect(result.copied).toBe(1);
+    expect(existsSync(join(targetDir, 'official-debug.md'))).toBe(true);
+  });
+
+  it('user-only skill in target (not in source) → untouched', () => {
+    // source has one official skill
+    writeFileSync(join(sourceDir, 'official-debug.md'), '# official-debug\n');
+    mkdirSync(targetDir, { recursive: true });
+    // target also has a user-custom skill not present in source
+    writeFileSync(join(targetDir, 'my-custom-skill.md'), '# custom\n');
+
+    syncSkills({ sourceDir, targetDir });
+
+    // user skill must still exist and be unchanged
+    expect(existsSync(join(targetDir, 'my-custom-skill.md'))).toBe(true);
+    expect(readFileSync(join(targetDir, 'my-custom-skill.md'), 'utf-8')).toContain('custom');
+  });
+});