create-dwy 0.16.0 → 0.17.0

package/src/sync-all.js

@@ -1,6 +1,15 @@
 import fs from 'fs-extra'
 import path from 'path'
-import { confirm, isCancel, multiselect } from '@clack/prompts'
+import { confirm, isCancel } from '@clack/prompts'
+import { SEARCH_PLACEHOLDER, searchableMultiselect, searchableSelect } from './searchable-select.js'
+import {
+  DEFAULT_SKILL_DESTINATIONS,
+  copySkillsToGlobalDirs,
+  copySkillsToProjectPlatforms,
+  listSkillDestOptions,
+  normalizeSkillScope,
+  resolveProjectSkillDir,
+} from './sync-global-skills.js'
 import { chalk } from './utils.js'
 import {
   interactiveSelect,
@@ -27,10 +36,10 @@ import { syncOpenCode } from './sync-opencode.js'
 import { ensureSkillsInstalled } from './skills-install.js'
 
 const PLATFORM_OPTIONS = [
-  { value: 'claude', label: 'Claude Code', hint: '支持 rules / skills / commands / hooks' },
-  { value: 'codex', label: 'Codex', hint: '支持 rules / skills / hooks' },
-  { value: 'cursor', label: 'Cursor', hint: '支持 rules' },
-  { value: 'opencode', label: 'OpenCode', hint: '支持 rules / skills / commands' },
+  { value: 'claude', label: 'Claude Code', description: '支持 rules / skills / commands / hooks' },
+  { value: 'codex', label: 'Codex', description: '支持 rules / skills / hooks' },
+  { value: 'cursor', label: 'Cursor', description: '支持 rules' },
+  { value: 'opencode', label: 'OpenCode', description: '支持 rules / skills / commands' },
 ]
 
 const CURSOR_BASELINE_RULE_NAME = '00-dwy-global.mdc'
@@ -54,6 +63,24 @@ const TYPE_LABELS = {
   hooks: 'hooks',
 }
 
+/** 完整同步：skills / rules / commands / hooks 都走平台写入 */
+export const SYNC_MODE_ALL = 'all'
+/** 仅 Skills：不写、不删 rules / commands / hooks */
+export const SYNC_MODE_SKILLS = 'skills'
+export const DEFAULT_SYNC_MODE = SYNC_MODE_ALL
+
+const SKILL_ONLY_CATEGORIES = [{ key: 'skills', label: 'Skills' }]
+
+/**
+ * 规范化同步范围。未知值回退完整同步，避免误进仅 Skills 删不该删的东西。
+ *
+ * @param {unknown} raw
+ * @returns {'all' | 'skills'}
+ */
+export function normalizeSyncMode(raw) {
+  return raw === SYNC_MODE_SKILLS ? SYNC_MODE_SKILLS : DEFAULT_SYNC_MODE
+}
+
 function unionSets(...sets) {
   return new Set(sets.flatMap(set => [...set]))
 }
@@ -143,6 +170,132 @@ export async function buildPlatformDefaultsFromLocalState(projectDir) {
   return defaults.length > 0 ? defaults : ['claude', 'codex']
 }
 
+/**
+ * 开头选同步范围。仅 Skills 时后面不再问 rules / commands / hooks。
+ *
+ * @param {'all' | 'skills'} initialValue
+ * @returns {Promise<'all' | 'skills' | null>}
+ */
+async function promptSyncMode(initialValue) {
+  const result = await searchableSelect({
+    message: '选择同步范围',
+    options: [
+      {
+        value: SYNC_MODE_ALL,
+        label: '完整同步',
+        description: '同步 Skills / Rules / Commands / Hooks',
+      },
+      {
+        value: SYNC_MODE_SKILLS,
+        label: '仅 Skills',
+        description: '只处理 skill，不改动已有 Rules / Commands / Hooks',
+      },
+    ],
+    initialValue,
+    placeholder: SEARCH_PLACEHOLDER,
+  })
+  if (isCancel(result)) return null
+  return normalizeSyncMode(result)
+}
+
+/**
+ * 仅 Skills 模式：只写项目/全局 skill，并清理未选中的模板 skill。
+ * 禁止调用完整平台 sync，否则空 rules/commands 会删掉项目已有项。
+ *
+ * @param {{ projectDir: string, selectedPlatforms: string[], skills: Array<{ name: string, sourcePath: string }>, templateSkillNames: Set<string>, staleSkillNames: Set<string>, skillScope: { destinations: string[] } }} opts
+ */
+async function syncSkillsOnly({
+  projectDir,
+  selectedPlatforms,
+  skills,
+  templateSkillNames,
+  staleSkillNames,
+  skillScope,
+}) {
+  const writeProject = skillScope.destinations.includes('project')
+  if (!writeProject) return
+
+  const skillPlatforms = selectedPlatforms.filter(platform => resolveProjectSkillDir(projectDir, platform))
+  if (skillPlatforms.length === 0) {
+    console.log(chalk.yellow('已选平台不支持项目内 skills，跳过项目写入。'))
+    return
+  }
+
+  console.log(chalk.blue('\nSyncing skills only (rules / commands / hooks untouched)...\n'))
+  await copySkillsToProjectPlatforms({
+    projectDir,
+    platforms: skillPlatforms,
+    skills,
+  })
+
+  const selectedNames = new Set(skills.map(item => item.name))
+  const toRemove = new Set(
+    [...templateSkillNames, ...staleSkillNames].filter(name => !selectedNames.has(name)),
+  )
+  for (const platform of skillPlatforms) {
+    const destRoot = resolveProjectSkillDir(projectDir, platform)
+    const existingNames = await scanExisting(path.dirname(destRoot), 'skills')
+    await removeManagedItems(
+      destRoot,
+      existingNames,
+      toRemove,
+      path.relative(projectDir, destRoot),
+    )
+  }
+}
+
+/**
+ * 交互最后一步：选 skill 同步位置，默认仅项目。
+ * 勾了全局 dest 后再问哪些 skill 额外拷到全局；不删用户 home 里其它 skill。
+ *
+ * @param {{ selectedSkills: Array<{ name: string }>, syncState: { skillScope?: object } }} args
+ * @returns {Promise<{ destinations: string[], globalSkills: string[] } | null>}
+ */
+async function promptSkillScope({ selectedSkills, syncState }) {
+  const previous = normalizeSkillScope(syncState.skillScope)
+  const destInitial = previous.destinations.length > 0
+    ? previous.destinations
+    : [...DEFAULT_SKILL_DESTINATIONS]
+
+  console.log(chalk.gray('\nSkill 默认同步到项目目录。勾选全局目录可把部分 skill 额外拷到本机 home。'))
+
+  const destResult = await searchableMultiselect({
+    message: '选择 skill 同步位置（默认项目）',
+    options: listSkillDestOptions(),
+    initialValues: destInitial,
+    required: true,
+    maxItems: 8,
+    placeholder: SEARCH_PLACEHOLDER,
+  })
+  if (isCancel(destResult)) return null
+
+  const destinations = destResult
+  const globalDests = destinations.filter(id => id !== 'project')
+  if (globalDests.length === 0 || selectedSkills.length === 0) {
+    return { destinations, globalSkills: [] }
+  }
+
+  const selectedNames = selectedSkills.map(item => item.name)
+  const globalInitial = previous.globalSkills.filter(name => selectedNames.includes(name))
+  const globalResult = await searchableMultiselect({
+    message: '哪些 skill 额外同步到全局？',
+    options: selectedSkills.map(item => ({
+      value: item.name,
+      label: item.name,
+      description: item.description,
+    })),
+    initialValues: globalInitial,
+    required: false,
+    placeholder: SEARCH_PLACEHOLDER,
+  })
+  if (isCancel(globalResult)) return null
+
+  return {
+    destinations,
+    globalSkills: globalResult,
+  }
+}
+
 async function selectPlatforms(projectDir) {
   const initialValues = await buildPlatformDefaultsFromLocalState(projectDir)
 
@@ -152,12 +305,14 @@ async function selectPlatforms(projectDir) {
   console.log(chalk.gray('  Cursor      → rules'))
   console.log(chalk.gray('  OpenCode    → rules / skills / commands\n'))
 
-  const result = await multiselect({
+  // 可搜索多选 + 底部说明区
+  const result = await searchableMultiselect({
     message: '选择要同步的平台',
     options: PLATFORM_OPTIONS,
     initialValues,
     required: true,
     maxItems: 6,
+    placeholder: SEARCH_PLACEHOLDER,
   })
   if (isCancel(result)) return null
   return result
@@ -194,6 +349,8 @@ async function loadSyncState(projectDir) {
     return {
       version: 1,
       platforms: {},
+      skillScope: normalizeSkillScope(undefined),
+      syncMode: DEFAULT_SYNC_MODE,
     }
   }
 
@@ -201,6 +358,8 @@ async function loadSyncState(projectDir) {
   return {
     version: 1,
     platforms: state.platforms || {},
+    skillScope: normalizeSkillScope(state.skillScope),
+    syncMode: normalizeSyncMode(state.syncMode),
   }
 }
 
@@ -310,11 +469,12 @@ async function promptStaleRemovals(staleEntries) {
         console.log(chalk.gray(`  - ${name}`))
       }
 
-      const selected = await multiselect({
+      const selected = await searchableMultiselect({
         message: `选择要删除的 ${PLATFORM_LABELS[platform]} ${TYPE_LABELS[type]}`,
         options: names.map(name => ({ value: name, label: name })),
         initialValues: names,
         required: false,
+        placeholder: SEARCH_PLACEHOLDER,
       })
       if (isCancel(selected)) return null
       approvals[platform][type] = new Set(selected)
@@ -324,6 +484,19 @@ async function promptStaleRemovals(staleEntries) {
   return approvals
 }
 
+/**
+ * 仅 Skills 模式：陈旧项提示只保留 skills，避免问 rules/commands/hooks。
+ *
+ * @param {Record<string, Record<string, string[]>>} staleEntries
+ */
+function retainSkillStaleEntries(staleEntries) {
+  const next = createEmptyRemovalState()
+  for (const [platform, types] of Object.entries(staleEntries)) {
+    if (types.skills?.length) next[platform] = { skills: types.skills }
+  }
+  return next
+}
+
 function getPreservedStaleNames(staleEntries, approvedRemovals, platform, type) {
   const staleNames = staleEntries[platform]?.[type] || []
   const approvedNames = approvedRemovals[platform]?.[type] || new Set()
@@ -552,6 +725,12 @@ export async function syncAll({
   selected: selectedOverride,
   selectedPlatforms: selectedPlatformsOverride,
   staleRemovals: staleRemovalsOverride,
+  // 测试/脚本可注入；交互模式在平台选择之后再问
+  skillScope: skillScopeOverride,
+  // all = 完整同步；skills = 只写 skill，测试/脚本可注入
+  syncMode: syncModeOverride,
+  // 全局 skill 写入的 home，测试注入假目录，禁止默认写真实 $HOME
+  homeDir,
 } = {}) {
   const sourceDir = sourceDirOverride || await resolveSourceDir()
   if (!await fs.pathExists(sourceDir)) {
@@ -601,7 +780,20 @@ export async function syncAll({
     console.log(chalk.gray('首次同步，进入交互式选择...\n'))
   }
 
-  const selected = selectedOverride || await interactiveSelect(scans, selectionDefaults)
+  const skipInteractive = !!(selectedOverride || selectedPlatformsOverride)
+  const syncMode = syncModeOverride
+    ? normalizeSyncMode(syncModeOverride)
+    : (skipInteractive
+      ? normalizeSyncMode(syncState.syncMode)
+      : await promptSyncMode(normalizeSyncMode(syncState.syncMode)))
+  if (syncMode === null) {
+    console.log(chalk.yellow('\n已取消同步。'))
+    return
+  }
+
+  const selected = selectedOverride || await interactiveSelect(scans, selectionDefaults, {
+    categories: syncMode === SYNC_MODE_SKILLS ? SKILL_ONLY_CATEGORIES : undefined,
+  })
   if (selected === null) {
     console.log(chalk.yellow('\n已取消同步。'))
     return
@@ -613,7 +805,10 @@ export async function syncAll({
     return
   }
 
-  const staleEntries = await collectStaleEntries(projectDir, scans, syncState, selectedPlatforms)
+  const staleEntriesRaw = await collectStaleEntries(projectDir, scans, syncState, selectedPlatforms)
+  const staleEntries = syncMode === SYNC_MODE_SKILLS
+    ? retainSkillStaleEntries(staleEntriesRaw)
+    : staleEntriesRaw
   const approvedStaleRemovals = staleRemovalsOverride
     ? normalizeRemovalInput(staleRemovalsOverride)
     : await promptStaleRemovals(staleEntries)
@@ -622,79 +817,132 @@ export async function syncAll({
     return
   }
 
+  const skillScope = skillScopeOverride
+    ? normalizeSkillScope(skillScopeOverride)
+    : (selectedOverride
+      ? normalizeSkillScope(syncState.skillScope)
+      : await promptSkillScope({ selectedSkills: selected.skills || [], syncState }))
+  if (skillScope === null) {
+    console.log(chalk.yellow('\n已取消同步。'))
+    return
+  }
+
+  const selectedSkillNames = new Set((selected.skills || []).map(item => item.name))
+  const skillsToWrite = scans.skills.filter(item => selectedSkillNames.has(item.name))
   let syncedAnySupportedPlatform = false
 
-  if (selectedPlatforms.includes('claude')) {
-    syncedAnySupportedPlatform = true
-    console.log(chalk.blue('\nSyncing Claude Code configuration...\n'))
-    await syncClaude({
-      sourceDir,
+  if (syncMode === SYNC_MODE_SKILLS) {
+    const staleSkillNames = new Set()
+    for (const platform of selectedPlatforms) {
+      for (const name of approvedStaleRemovals[platform]?.skills || []) staleSkillNames.add(name)
+    }
+    await syncSkillsOnly({
       projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.claude,
+      selectedPlatforms,
+      skills: skillsToWrite,
+      templateSkillNames: new Set(scans.skills.map(item => item.name)),
+      staleSkillNames,
+      skillScope,
     })
-  }
+    syncedAnySupportedPlatform = selectedPlatforms.some(platform => resolveProjectSkillDir(projectDir, platform))
+      || skillScope.destinations.some(id => id !== 'project')
+  } else {
+    if (selectedPlatforms.includes('claude')) {
+      syncedAnySupportedPlatform = true
+      console.log(chalk.blue('\nSyncing Claude Code configuration...\n'))
+      await syncClaude({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.claude,
+      })
+    }
 
-  if (selectedPlatforms.includes('codex')) {
-    syncedAnySupportedPlatform = true
-    console.log(chalk.blue('\nSyncing Codex configuration...\n'))
-    await syncCodex({
-      sourceDir,
-      projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.codex,
-      preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'codex', 'rules'),
-    })
-  }
+    if (selectedPlatforms.includes('codex')) {
+      syncedAnySupportedPlatform = true
+      console.log(chalk.blue('\nSyncing Codex configuration...\n'))
+      await syncCodex({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.codex,
+        preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'codex', 'rules'),
+      })
+    }
 
-  if (selectedPlatforms.includes('cursor')) {
-    syncedAnySupportedPlatform = true
-    await syncCursor({
-      sourceDir,
-      projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.cursor,
-    })
-  }
+    if (selectedPlatforms.includes('cursor')) {
+      syncedAnySupportedPlatform = true
+      await syncCursor({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.cursor,
+      })
+    }
 
-  if (selectedPlatforms.includes('opencode')) {
-    syncedAnySupportedPlatform = true
-    await syncOpenCode({
-      sourceDir,
-      projectDir,
-      selected,
-      staleRemovals: approvedStaleRemovals.opencode,
-      preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'opencode', 'rules'),
-    })
-  }
+    if (selectedPlatforms.includes('opencode')) {
+      syncedAnySupportedPlatform = true
+      await syncOpenCode({
+        sourceDir,
+        projectDir,
+        selected,
+        staleRemovals: approvedStaleRemovals.opencode,
+        preserveMissingRules: getPreservedStaleNames(staleEntries, approvedStaleRemovals, 'opencode', 'rules'),
+      })
+    }
 
-  if (!selectedPlatforms.includes('codex') && !selectedPlatforms.includes('opencode')) {
-    await clearProjectAgentsMd(projectDir)
-  }
+    if (!selectedPlatforms.includes('codex') && !selectedPlatforms.includes('opencode')) {
+      await clearProjectAgentsMd(projectDir)
+    }
 
-  if (!selectedPlatforms.includes('claude')) {
-    await cleanupClaudePlatform(projectDir, scans, claudeManagedHookNames, baseline)
-  }
+    if (!selectedPlatforms.includes('claude')) {
+      await cleanupClaudePlatform(projectDir, scans, claudeManagedHookNames, baseline)
+    }
 
-  if (!selectedPlatforms.includes('cursor')) {
-    await cleanupCursorPlatform(projectDir, scans, baseline)
-  }
+    if (!selectedPlatforms.includes('cursor')) {
+      await cleanupCursorPlatform(projectDir, scans, baseline)
+    }
 
-  if (!selectedPlatforms.includes('codex')) {
-    await cleanupCodexPlatform(projectDir, scans, codexManagedHookNames)
+    if (!selectedPlatforms.includes('codex')) {
+      await cleanupCodexPlatform(projectDir, scans, codexManagedHookNames)
+    }
+
+    if (!selectedPlatforms.includes('opencode')) {
+      await cleanupOpenCodePlatform(projectDir, scans)
+    }
   }
 
-  if (!selectedPlatforms.includes('opencode')) {
-    await cleanupOpenCodePlatform(projectDir, scans)
+  const globalSkillNameSet = new Set(skillScope.globalSkills)
+  const globalSkills = scans.skills.filter(item => globalSkillNameSet.has(item.name))
+  if (globalSkills.length > 0 && skillScope.destinations.some(id => id !== 'project')) {
+    console.log(chalk.blue('\nSyncing selected skills to global directories...\n'))
+    await copySkillsToGlobalDirs({
+      skills: globalSkills,
+      destIds: skillScope.destinations,
+      homeDir,
+    })
   }
 
-  for (const platform of Object.keys(PLATFORM_SYNC_TYPES)) {
-    if (selectedPlatforms.includes(platform)) {
-      syncState.platforms[platform] = buildNextPlatformState(selected, staleEntries, approvedStaleRemovals, platform)
-    } else {
-      syncState.platforms[platform] = createEmptyPlatformState()
+  if (syncMode === SYNC_MODE_SKILLS) {
+    for (const platform of selectedPlatforms) {
+      const previous = syncState.platforms[platform] || createEmptyPlatformState()
+      const skillsOnlySelected = { skills: selected.skills || [], rules: [], commands: [], hooks: [] }
+      syncState.platforms[platform] = {
+        ...previous,
+        skills: buildNextPlatformState(skillsOnlySelected, staleEntries, approvedStaleRemovals, platform).skills,
+      }
+    }
+  } else {
+    for (const platform of Object.keys(PLATFORM_SYNC_TYPES)) {
+      if (selectedPlatforms.includes(platform)) {
+        syncState.platforms[platform] = buildNextPlatformState(selected, staleEntries, approvedStaleRemovals, platform)
+      } else {
+        syncState.platforms[platform] = createEmptyPlatformState()
+      }
     }
   }
+  syncState.skillScope = skillScope
+  syncState.syncMode = syncMode
   await saveSyncState(projectDir, syncState)
 
   if (!syncedAnySupportedPlatform) {

package/src/sync-global-skills.js

@@ -0,0 +1,167 @@
+/**
+ * 将已选 skill 额外拷到用户全局目录。
+ * 项目目录同步仍由各平台 sync 负责；本模块只处理 ~/.claude / ~/.grok 等 home 下目录。
+ * 只覆盖本次点名的 skill，不删除全局目录里其它个人 skill。
+ */
+
+import fs from 'fs-extra'
+import os from 'node:os'
+import path from 'path'
+import { copyFilter, logAction } from './sync.js'
+
+/** 项目目录：随所选平台落到 .claude/skills、.agents/skills 等 */
+export const SKILL_DEST_PROJECT = 'project'
+
+/** 默认同步位置：只写项目，不碰用户 home */
+export const DEFAULT_SKILL_DESTINATIONS = [SKILL_DEST_PROJECT]
+
+/**
+ * 全局 dest id → home 下相对路径。
+ * 路径跟各工具官方发现目录对齐；测试通过 homeDir 注入，避免写真实 $HOME。
+ */
+const GLOBAL_SKILL_DIR_SEGMENTS = {
+  claude: ['.claude', 'skills'],
+  grok: ['.grok', 'skills'],
+  agents: ['.agents', 'skills'],
+  cursor: ['.cursor', 'skills'],
+  opencode: ['.config', 'opencode', 'skills'],
+}
+
+export const GLOBAL_SKILL_DEST_IDS = Object.keys(GLOBAL_SKILL_DIR_SEGMENTS)
+
+/**
+ * 项目内 skill 目录（按已选平台）。Cursor 无 skills，不列入。
+ * 仅 Skills 模式用这张表写项目，避免走完整 sync 误改 rules/commands/hooks。
+ */
+export const PROJECT_SKILL_DIR_BY_PLATFORM = {
+  claude: ['.claude', 'skills'],
+  codex: ['.agents', 'skills'],
+  opencode: ['.opencode', 'skills'],
+}
+
+/**
+ * 解析某平台在项目内的 skills 目录。不支持的平台返回 null。
+ *
+ * @param {string} projectDir
+ * @param {string} platform
+ */
+export function resolveProjectSkillDir(projectDir, platform) {
+  const segments = PROJECT_SKILL_DIR_BY_PLATFORM[platform]
+  if (!segments) return null
+  return path.join(projectDir, ...segments)
+}
+
+const DEST_LABELS = {
+  project: '项目目录',
+  claude: 'Claude Code 全局',
+  grok: 'Grok 全局',
+  agents: 'Codex / 跨运行时全局',
+  cursor: 'Cursor 全局',
+  opencode: 'OpenCode 全局',
+}
+
+/**
+ * 规范化交互/缓存里的 skill 同步范围。
+ * 未知 dest、空 skill 名丢弃；无 destinations 时回退到仅项目。
+ *
+ * @param {{ destinations?: string[], globalSkills?: string[] } | null | undefined} raw
+ */
+export function normalizeSkillScope(raw) {
+  const allowed = new Set([SKILL_DEST_PROJECT, ...GLOBAL_SKILL_DEST_IDS])
+  const destinations = (raw?.destinations || [])
+    .filter(id => allowed.has(id))
+  const globalSkills = [...new Set((raw?.globalSkills || []).filter(name => typeof name === 'string' && name.trim()))]
+
+  return {
+    destinations: destinations.length > 0 ? destinations : [...DEFAULT_SKILL_DESTINATIONS],
+    globalSkills,
+  }
+}
+
+/**
+ * 解析全局 dest 的绝对目录。project 返回 null（由平台 sync 写项目）。
+ *
+ * @param {string} destId
+ * @param {string} [homeDir]
+ */
+export function resolveGlobalSkillDir(destId, homeDir = os.homedir()) {
+  const segments = GLOBAL_SKILL_DIR_SEGMENTS[destId]
+  if (!segments) return null
+  return path.join(homeDir, ...segments)
+}
+
+/**
+ * 最后一步 UI 的位置选项。project 放第一项，默认勾选。
+ *
+ * @param {string} [homeDir]
+ * @returns {Array<{ value: string, label: string, description: string }>}
+ */
+export function listSkillDestOptions(homeDir = os.homedir()) {
+  return [
+    {
+      value: SKILL_DEST_PROJECT,
+      label: DEST_LABELS.project,
+      description: '默认。随上面所选平台写入项目 .claude/skills、.agents/skills 等',
+    },
+    ...GLOBAL_SKILL_DEST_IDS.map(id => {
+      const dir = resolveGlobalSkillDir(id, homeDir)
+      return {
+        value: id,
+        label: DEST_LABELS[id],
+        description: dir,
+      }
+    }),
+  ]
+}
+
+/**
+ * 把 skill 目录拷到已选全局 dest。destIds 含 project 时跳过（项目侧已同步）。
+ * 只写传入的 skills，不清理目标根目录里其它条目。
+ *
+ * @param {{ skills: Array<{ name: string, sourcePath: string }>, destIds: string[], homeDir?: string }} opts
+ * @returns {Promise<number>} 写入次数（每个 dest × 每个 skill）
+ */
+export async function copySkillsToGlobalDirs({ skills, destIds, homeDir = os.homedir() }) {
+  let count = 0
+
+  for (const destId of destIds) {
+    const destRoot = resolveGlobalSkillDir(destId, homeDir)
+    if (!destRoot) continue
+
+    for (const skill of skills) {
+      const dest = path.join(destRoot, skill.name)
+      await fs.ensureDir(path.dirname(dest))
+      await fs.copy(skill.sourcePath, dest, { overwrite: true, filter: copyFilter })
+      logAction(`${DEST_LABELS[destId] || destId}/${skill.name}`)
+      count++
+    }
+  }
+
+  return count
+}
+
+/**
+ * 仅 Skills 模式：把 skill 拷到项目内已选平台的 skills 目录。
+ * 不写 rules / commands / hooks。
+ *
+ * @param {{ projectDir: string, platforms: string[], skills: Array<{ name: string, sourcePath: string }> }} opts
+ * @returns {Promise<number>}
+ */
+export async function copySkillsToProjectPlatforms({ projectDir, platforms, skills }) {
+  let count = 0
+
+  for (const platform of platforms) {
+    const destRoot = resolveProjectSkillDir(projectDir, platform)
+    if (!destRoot) continue
+
+    for (const skill of skills) {
+      const dest = path.join(destRoot, skill.name)
+      await fs.ensureDir(path.dirname(dest))
+      await fs.copy(skill.sourcePath, dest, { overwrite: true, filter: copyFilter })
+      logAction(`${path.relative(projectDir, destRoot)}/${skill.name}`)
+      count++
+    }
+  }
+
+  return count
+}