@morya-ui/setup 0.3.7 → 0.3.8

package/README.md

@@ -38,6 +38,12 @@ npx @morya-ui/setup ai --skills=all
 # Only Cursor + VS Code MCP targets (still writes .mcp.json)
 npx @morya-ui/setup ai --editors=cursor,vscode
 
+# Narrow skill agents (default: cursor, github-copilot, zed, claude-code, windsurf)
+npx @morya-ui/setup ai --agents=github-copilot,zed
+
+# Install companion skills to every skills-CLI agent (many dirs)
+npx @morya-ui/setup ai --agents=all
+
 # Refresh AI template / MCP without touching dependencies
 npx @morya-ui/setup ai --skip-install
 ```
@@ -50,8 +56,9 @@ npx @morya-ui/setup ai --skip-install
 | `--pm pnpm\|yarn\|npm` | Package manager (default: detect from lockfile, else `pnpm`) |
 | `--skills <list>` | Comma-separated skill ids, or `all` (skips the prompt) |
 | `--editors <list>` | MCP targets: `cursor`, `vscode`, `zed`, or `all` (default: all three). Always also writes root `.mcp.json` |
+| `--agents <list>` | Skill agents: `cursor`, `github-copilot`, `zed`, `claude-code`, `windsurf` (default), or `all` (`-a '*'`) |
 | `--yes` / `-y` | Use default skills without prompting |
-| `--force` | Overwrite existing template files and the `morya-ui` MCP entry |
+| `--force` | Overwrite existing template files, MCP `morya-ui` entry, and skill-dir links |
 | `--dry-run` | Print actions without writing or installing |
 | `--skip-install` | Do not install / upgrade `morya-ui` or `@morya-ui/*` |
 | `--skip-template` | Do not copy AI skill / rules / docs (also skips companion skill install) |
@@ -75,7 +82,8 @@ Catalog: [`catalog/skills.json`](./catalog/skills.json).
 
 - Dependencies: always install / upgrade `morya-ui@latest` and any existing `@morya-ui/*` (e.g. `@morya-ui/nuxt`) to `@latest` unless `--skip-install`.
 - Template files and `.cursor/rules/*`: **skip** if the destination exists (unless `--force`).
-- Companion skills (`skills-cli`): always reinstall/update to **latest** when selected.
+- Companion skills (`skills-cli`): always reinstall/update to **latest** when selected (default agents: the five listed under `--agents`).
+- Mirrored skill dirs (`.claude/skills`, `.windsurf/skills`, `.github/skills`): **skip** if the destination exists (unless `--force`).
 - MCP configs: merge other servers / settings; skip existing `morya-ui` entry unless `--force`. New or forced entries use `npx -y @morya-ui/mcp@latest`.
 - `package.json` `check:colors`: add only if missing (unless `--force`).
 - Styles: inject only when an entry file is found and the import is not already present.
@@ -90,10 +98,20 @@ From the package `template/` (synced from repo `design-kit/`):
 - `.cursor/rules/` — Cursor-specific always-apply rules
 - `scripts/check-raw-colors.mjs`
 
-Via `npx skills add …` when optional companions are selected:
+Via `npx skills add …` when optional companions are selected (default agents: Cursor, GitHub Copilot, Zed, Claude Code, Windsurf):
 
 - `.agents/skills/frontend-design/`, `fixing-accessibility/`, and/or `impeccable/` (latest upstream)
 
+Setup then mirrors selected skills from `.agents/skills/` into agent-specific dirs that do not share that path:
+
+| Agent | Extra project dir |
+| --- | --- |
+| Claude Code | `.claude/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| GitHub Copilot | `.github/skills/` (in addition to `.agents/skills`) |
+
+Cursor / Zed / Copilot already read `.agents/skills` directly.
+
 ### MCP (multi-editor)
 
 | Editor | Path | JSON key |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morya-ui/setup",
   "type": "module",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "description": "One-shot setup for morya-ui: install the library, multi-editor MCP, Agent skills, and design config.",
   "license": "MIT",
   "homepage": "https://github.com/morya-space/morya-ui/tree/main/packages/setup#readme",

package/src/__tests__/skills.test.mjs

@@ -0,0 +1,174 @@
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, it } from 'node:test'
+import {
+  DEFAULT_SKILL_AGENTS,
+  extraSkillDirsForAgents,
+  installSkillsCli,
+  parseAgentsFlag,
+  skillAgentCliFlags,
+  syncProjectSkillsToAgents,
+} from '../skills.mjs'
+
+/** @type {string[]} */
+const temps = []
+
+function makeCwd() {
+  const cwd = mkdtempSync(join(tmpdir(), 'morya-setup-skills-'))
+  temps.push(cwd)
+  return cwd
+}
+
+afterEach(() => {
+  while (temps.length) {
+    rmSync(temps.pop(), { recursive: true, force: true })
+  }
+})
+
+function seedSkill(cwd, name) {
+  const dir = join(cwd, '.agents', 'skills', name)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: test\n---\n`, 'utf8')
+  return dir
+}
+
+describe('parseAgentsFlag', () => {
+  it('defaults to the five curated agents', () => {
+    assert.deepEqual(parseAgentsFlag(), [...DEFAULT_SKILL_AGENTS])
+    assert.deepEqual(parseAgentsFlag(''), [...DEFAULT_SKILL_AGENTS])
+  })
+
+  it('returns * for all', () => {
+    assert.equal(parseAgentsFlag('all'), '*')
+    assert.equal(parseAgentsFlag('*'), '*')
+  })
+
+  it('parses and dedupes a subset', () => {
+    assert.deepEqual(parseAgentsFlag('zed,cursor,zed'), ['zed', 'cursor'])
+  })
+
+  it('rejects unknown agents', () => {
+    assert.throws(() => parseAgentsFlag('cursor,not-a-real-agent'), /Unknown skill agent/)
+  })
+})
+
+describe('skillAgentCliFlags', () => {
+  it('emits one -a per default agent', () => {
+    const flags = skillAgentCliFlags(DEFAULT_SKILL_AGENTS)
+    assert.match(flags, /-a cursor/)
+    assert.match(flags, /-a github-copilot/)
+    assert.match(flags, /-a zed/)
+    assert.match(flags, /-a claude-code/)
+    assert.match(flags, /-a windsurf/)
+  })
+
+  it('emits wildcard for all', () => {
+    assert.equal(skillAgentCliFlags('*'), "-a '*'")
+  })
+})
+
+describe('extraSkillDirsForAgents', () => {
+  it('mirrors claude / windsurf / github dirs for defaults', () => {
+    assert.deepEqual(extraSkillDirsForAgents(DEFAULT_SKILL_AGENTS), [
+      '.github/skills',
+      '.claude/skills',
+      '.windsurf/skills',
+    ])
+  })
+
+  it('skips extras for agents that only use .agents/skills', () => {
+    assert.deepEqual(extraSkillDirsForAgents(['cursor', 'zed']), [])
+  })
+})
+
+describe('installSkillsCli', () => {
+  it('dry-run builds multi-agent commands', () => {
+    const cwd = makeCwd()
+    const skills = [
+      {
+        id: 'frontend-design',
+        name: 'Frontend Design',
+        description: 'x',
+        install: 'skills-cli',
+        source: 'anthropics/skills',
+        skill: 'frontend-design',
+        path: '.agents/skills/frontend-design',
+      },
+    ]
+    const result = installSkillsCli(cwd, ['frontend-design'], skills, {
+      dryRun: true,
+      agents: ['cursor', 'zed', 'github-copilot'],
+    })
+    assert.equal(result.dryRun, true)
+    assert.equal(result.commands.length, 1)
+    assert.match(result.commands[0], /skills add anthropics\/skills/)
+    assert.match(result.commands[0], /-s frontend-design/)
+    assert.match(result.commands[0], /-a cursor/)
+    assert.match(result.commands[0], /-a zed/)
+    assert.match(result.commands[0], /-a github-copilot/)
+    assert.doesNotMatch(result.commands[0], /-a cursor -y$/)
+  })
+})
+
+describe('syncProjectSkillsToAgents', () => {
+  it('links into claude / windsurf / github skill dirs', () => {
+    const cwd = makeCwd()
+    seedSkill(cwd, 'morya-ui-pages')
+
+    const { results } = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: DEFAULT_SKILL_AGENTS,
+    })
+
+    const byDir = Object.fromEntries(results.map((r) => [r.dir, r]))
+    assert.ok(byDir['.claude/skills'])
+    assert.ok(byDir['.windsurf/skills'])
+    assert.ok(byDir['.github/skills'])
+    assert.ok(['linked', 'copied'].includes(byDir['.claude/skills'].action))
+
+    assert.ok(readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'))
+    assert.ok(readFileSync(join(cwd, '.windsurf', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'))
+    assert.ok(readFileSync(join(cwd, '.github', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'))
+  })
+
+  it('skips existing links unless force', () => {
+    const cwd = makeCwd()
+    seedSkill(cwd, 'morya-ui-pages')
+    mkdirSync(join(cwd, '.claude', 'skills', 'morya-ui-pages'), { recursive: true })
+    writeFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'old\n', 'utf8')
+
+    const skipped = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: ['claude-code'],
+    })
+    assert.equal(skipped.results[0].action, 'skipped')
+    assert.equal(
+      readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'),
+      'old\n',
+    )
+
+    const forced = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: ['claude-code'],
+      force: true,
+    })
+    assert.ok(['linked', 'copied'].includes(forced.results[0].action))
+    assert.match(
+      readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'),
+      /morya-ui-pages/,
+    )
+  })
+
+  it('dry-run does not create dirs', () => {
+    const cwd = makeCwd()
+    seedSkill(cwd, 'morya-ui-pages')
+    const { results } = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: ['claude-code'],
+      dryRun: true,
+    })
+    assert.equal(results[0].action, 'linked')
+    assert.throws(
+      () => readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md')),
+      /ENOENT/,
+    )
+  })
+})

package/src/cli.mjs

@@ -5,11 +5,17 @@ import { installMoryaUi } from './install.mjs'
 import { DEFAULT_EDITORS, mergeMcpConfig, parseEditorsFlag } from './mcp.mjs'
 import { ensureCheckColorsScript } from './package-json.mjs'
 import {
+  DEFAULT_SKILL_AGENTS,
   buildAiInclude,
   installSkillsCli,
+  listCanonicalSkillFolders,
   loadSkillsCatalog,
+  parseAgentsFlag,
   parseSkillsFlag,
+  resolveSkillAgents,
   resolveSkillSelection,
+  skillFolderNames,
+  syncProjectSkillsToAgents,
 } from './skills.mjs'
 import { ensureStylesImport } from './styles.mjs'
 
@@ -54,6 +60,7 @@ Commands:
 Default command:
   - install / upgrade morya-ui@latest and any existing @morya-ui/* to @latest
   - copy DESIGN.md, AGENTS.md, selected Agent skills, Cursor rules
+  - install companion skills + sync into multi-agent skill dirs
   - merge MCP configs for @morya-ui/mcp@latest (Cursor, VS Code, Zed, + .mcp.json)
   - inject import 'morya-ui/styles.css' into the app entry when found
   - add check:colors script when missing
@@ -63,8 +70,9 @@ Options:
   --pm <name>       Package manager: pnpm | yarn | npm (auto-detect by lockfile)
   --skills <list>   Comma-separated skill ids, or "all" (skips interactive prompt)
   --editors <list>  MCP targets: cursor,vscode,zed (default: all); always also writes .mcp.json
+  --agents <list>   Skill agents: cursor,github-copilot,zed,claude-code,windsurf (default), or all
   --yes             Use default skills without prompting (CI / non-interactive)
-  --force           Overwrite existing template files and MCP server entry
+  --force           Overwrite existing template files, MCP entry, and skill dir links
   --dry-run         Print actions without writing or installing
   --skip-install    Skip dependency install / upgrade
   --skip-template   Skip copying AI template files
@@ -88,6 +96,7 @@ export function parseArgs(argv) {
     pm: undefined,
     skills: undefined,
     editors: undefined,
+    agents: undefined,
     yes: false,
     force: false,
     dryRun: false,
@@ -165,6 +174,16 @@ export function parseArgs(argv) {
       options.editors = arg.slice('--editors='.length)
       continue
     }
+    if (arg === '--agents') {
+      const value = argv[++i]
+      if (!value) throw new Error('--agents requires a comma-separated list or "all"')
+      options.agents = value
+      continue
+    }
+    if (arg.startsWith('--agents=')) {
+      options.agents = arg.slice('--agents='.length)
+      continue
+    }
     throw new Error(`Unknown argument: ${arg}`)
   }
 
@@ -198,10 +217,13 @@ export async function runSetup(options) {
     pm,
     skills: skillsFlag,
     editors: editorsFlag,
+    agents: agentsFlag,
     yes,
   } = options
 
   const editors = editorsFlag != null ? parseEditorsFlag(editorsFlag) : [...DEFAULT_EDITORS]
+  const agents = agentsFlag != null ? parseAgentsFlag(agentsFlag) : [...DEFAULT_SKILL_AGENTS]
+  const agentsLabel = agents === '*' ? 'all (*)' : resolveSkillAgents(agents).join(',')
 
   console.log(`@morya-ui/setup [${mode}] → ${cwd}${dryRun ? ' (dry-run)' : ''}`)
   console.log('')
@@ -221,6 +243,7 @@ export async function runSetup(options) {
     }
     aiInclude = buildAiInclude(selectedSkills, catalog.skills)
     console.log(`Skills: ${selectedSkills.join(', ')}`)
+    console.log(`Skill agents: ${agentsLabel}`)
     console.log('')
   }
 
@@ -236,8 +259,21 @@ export async function runSetup(options) {
       })
 
   const remoteSkills = skipTemplate || !selectedSkills.length
-    ? { installed: [], commands: [], skipped: true }
-    : installSkillsCli(cwd, selectedSkills, catalog.skills, { dryRun })
+    ? { installed: [], commands: [], agents, skipped: true }
+    : installSkillsCli(cwd, selectedSkills, catalog.skills, { dryRun, agents })
+
+  const skillNamesForSync = needsTemplate
+    ? [
+        ...new Set([
+          ...skillFolderNames(selectedSkills, catalog.skills),
+          ...(dryRun ? [] : listCanonicalSkillFolders(cwd)),
+        ]),
+      ]
+    : []
+
+  const skillSync = skipTemplate || !skillNamesForSync.length
+    ? { results: [], skipped: true }
+    : syncProjectSkillsToAgents(cwd, skillNamesForSync, { force, dryRun, agents })
 
   const mcp = skipMcp
     ? { skipped: true, results: [] }
@@ -278,10 +314,27 @@ export async function runSetup(options) {
   if (remoteSkills.skipped) {
     // no companions selected or template step skipped
   } else if (remoteSkills.dryRun) {
-    console.log(`Skills CLI: dry-run — would install ${remoteSkills.installed.join(', ')}`)
+    console.log(`Skills CLI: dry-run — would install ${remoteSkills.installed.join(', ')} → ${agentsLabel}`)
     for (const command of remoteSkills.commands) console.log(`  $ ${command}`)
   } else {
-    console.log(`Skills CLI: installed ${remoteSkills.installed.join(', ')} (latest)`)
+    console.log(`Skills CLI: installed ${remoteSkills.installed.join(', ')} (latest) → ${agentsLabel}`)
+  }
+
+  if (skillSync.skipped) {
+    // nothing to mirror
+  } else {
+    const linked = skillSync.results.filter((r) => r.action === 'linked' || r.action === 'copied')
+    const skippedLinks = skillSync.results.filter((r) => r.action === 'skipped')
+    console.log(
+      `Skill dirs: ${linked.length} linked/copied, ${skippedLinks.length} skipped` +
+        (skillSync.dryRun ? ' (dry-run)' : ''),
+    )
+    for (const entry of skillSync.results.slice(0, 8)) {
+      console.log(`  ${entry.action} ${entry.dir}/${entry.skill}`)
+    }
+    if (skillSync.results.length > 8) {
+      console.log(`  … and ${skillSync.results.length - 8} more`)
+    }
   }
 
   if (mcp.skipped) {
@@ -326,5 +379,17 @@ export async function runSetup(options) {
     console.log('  4. Optional: pnpm check:colors')
   }
 
-  return { mode, install, template, remoteSkills, mcp, styles, scripts, skills: selectedSkills, editors }
+  return {
+    mode,
+    install,
+    template,
+    remoteSkills,
+    skillSync,
+    mcp,
+    styles,
+    scripts,
+    skills: selectedSkills,
+    editors,
+    agents,
+  }
 }

package/src/skills.mjs

@@ -1,12 +1,53 @@
 import { execSync } from 'node:child_process'
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs'
+import { dirname, join, relative } from 'node:path'
 import { createInterface } from 'node:readline'
-import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { readJson } from './fs-utils.mjs'
+import { ensureDir, readJson } from './fs-utils.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const CATALOG_PATH = join(__dirname, '..', 'catalog', 'skills.json')
 
+/** Canonical project skills root shared by Cursor / Zed / GitHub Copilot. */
+export const CANONICAL_SKILLS_DIR = '.agents/skills'
+
+/**
+ * Default skills CLI agents for consumer projects.
+ * VS Code Copilot uses `github-copilot` (reads `.agents/skills`).
+ */
+export const DEFAULT_SKILL_AGENTS = [
+  'cursor',
+  'github-copilot',
+  'zed',
+  'claude-code',
+  'windsurf',
+]
+
+/**
+ * Project-relative skills directories for agents that do **not** share
+ * `.agents/skills`. Agents that already use the canonical dir are omitted.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const EXTRA_AGENT_SKILL_DIRS = {
+  'claude-code': ['.claude/skills'],
+  windsurf: ['.windsurf/skills'],
+  // Copilot also discovers `.github/skills`; keep a link for clients that prefer it.
+  'github-copilot': ['.github/skills'],
+}
+
+export const KNOWN_SKILL_AGENTS = [
+  ...new Set([...DEFAULT_SKILL_AGENTS, ...Object.keys(EXTRA_AGENT_SKILL_DIRS)]),
+]
+
 /**
  * @typedef {{
  *   id: string
@@ -49,6 +90,72 @@ export function defaultSkillIds(skills) {
   return skills.filter((s) => s.required || s.default).map((s) => s.id)
 }
 
+/**
+ * @param {string | undefined} raw
+ * @returns {string[] | '*'}
+ */
+export function parseAgentsFlag(raw) {
+  if (raw == null || raw.trim() === '') return [...DEFAULT_SKILL_AGENTS]
+  if (raw.trim() === 'all' || raw.trim() === '*') return '*'
+
+  const ids = raw
+    .split(',')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean)
+
+  if (!ids.length) return [...DEFAULT_SKILL_AGENTS]
+  if (ids.includes('*') || ids.includes('all')) return '*'
+
+  const unknown = ids.filter((id) => !KNOWN_SKILL_AGENTS.includes(id))
+  if (unknown.length) {
+    throw new Error(
+      `Unknown skill agent id(s): ${unknown.join(', ')}. Available: ${KNOWN_SKILL_AGENTS.join(', ')}, or all`,
+    )
+  }
+
+  return [...new Set(ids)]
+}
+
+/**
+ * Resolve concrete agent names for CLI / sync (expands `*`).
+ * @param {string[] | '*'} agents
+ * @returns {string[]}
+ */
+export function resolveSkillAgents(agents) {
+  if (agents === '*') return [...DEFAULT_SKILL_AGENTS]
+  if (!Array.isArray(agents) || !agents.length) return [...DEFAULT_SKILL_AGENTS]
+  return [...new Set(agents)]
+}
+
+/**
+ * Build `-a` flags for the skills CLI.
+ * @param {string[] | '*'} agents
+ */
+export function skillAgentCliFlags(agents) {
+  if (agents === '*') return "-a '*'"
+  const list = resolveSkillAgents(agents)
+  return list.map((name) => `-a ${name}`).join(' ')
+}
+
+/**
+ * Extra project skill dirs to mirror for the selected agents.
+ * @param {string[] | '*'} agents
+ * @returns {string[]}
+ */
+export function extraSkillDirsForAgents(agents) {
+  const list = agents === '*' ? [...DEFAULT_SKILL_AGENTS] : resolveSkillAgents(agents)
+  /** @type {string[]} */
+  const dirs = []
+  for (const agent of list) {
+    const extras = EXTRA_AGENT_SKILL_DIRS[agent]
+    if (!extras) continue
+    for (const dir of extras) {
+      if (!dirs.includes(dir)) dirs.push(dir)
+    }
+  }
+  return dirs
+}
+
 /**
  * @param {string | undefined} raw
  * @param {SkillEntry[]} skills
@@ -111,18 +218,38 @@ export function buildAiInclude(skillIds, skills) {
   ]
 }
 
+/**
+ * Folder names under `.agents/skills` for the selected skill ids.
+ * @param {string[]} skillIds
+ * @param {SkillEntry[]} skills
+ * @returns {string[]}
+ */
+export function skillFolderNames(skillIds, skills) {
+  const byId = new Map(skills.map((s) => [s.id, s]))
+  return skillIds.map((id) => {
+    const entry = byId.get(id)
+    if (!entry) throw new Error(`Unknown skill id: ${id}`)
+    return entry.skill || entry.id
+  })
+}
+
 /**
  * Install selected companion skills via the skills CLI (always latest from source).
  * @param {string} cwd
  * @param {string[]} skillIds
  * @param {SkillEntry[]} skills
- * @param {{ dryRun?: boolean }} [options]
- * @returns {{ installed: string[], commands: string[], dryRun?: boolean, skipped?: boolean }}
+ * @param {{ dryRun?: boolean, agents?: string[] | '*' }} [options]
+ * @returns {{ installed: string[], commands: string[], agents: string[] | '*', dryRun?: boolean, skipped?: boolean }}
  */
-export function installSkillsCli(cwd, skillIds, skills, { dryRun = false } = {}) {
+export function installSkillsCli(
+  cwd,
+  skillIds,
+  skills,
+  { dryRun = false, agents = DEFAULT_SKILL_AGENTS } = {},
+) {
   const selected = skills.filter((s) => skillIds.includes(s.id) && isSkillsCliSkill(s))
   if (!selected.length) {
-    return { installed: [], commands: [], skipped: true }
+    return { installed: [], commands: [], agents, skipped: true }
   }
 
   for (const entry of selected) {
@@ -140,14 +267,15 @@ export function installSkillsCli(cwd, skillIds, skills, { dryRun = false } = {})
     bySource.set(entry.source, list)
   }
 
+  const agentFlags = skillAgentCliFlags(agents)
   const commands = []
   for (const [source, names] of bySource) {
     const skillFlags = names.map((name) => `-s ${name}`).join(' ')
-    commands.push(`npx -y skills add ${source} ${skillFlags} -a cursor -y`)
+    commands.push(`npx -y skills add ${source} ${skillFlags} ${agentFlags} -y`)
   }
 
   if (dryRun) {
-    return { installed: selected.map((s) => s.id), commands, dryRun: true }
+    return { installed: selected.map((s) => s.id), commands, agents, dryRun: true }
   }
 
   console.log('Companion skills (latest via skills CLI):')
@@ -156,7 +284,116 @@ export function installSkillsCli(cwd, skillIds, skills, { dryRun = false } = {})
     execSync(command, { cwd, stdio: 'inherit', shell: true })
   }
 
-  return { installed: selected.map((s) => s.id), commands }
+  return { installed: selected.map((s) => s.id), commands, agents }
+}
+
+/**
+ * Link (or copy) canonical `.agents/skills/<name>` into agent-specific dirs.
+ * @param {string} cwd
+ * @param {string[]} skillNames folder names under `.agents/skills`
+ * @param {{ force?: boolean, dryRun?: boolean, agents?: string[] | '*' }} [options]
+ * @returns {{ results: Array<{ skill: string, dir: string, action: string }>, dryRun?: boolean, skipped?: boolean }}
+ */
+export function syncProjectSkillsToAgents(
+  cwd,
+  skillNames,
+  { force = false, dryRun = false, agents = DEFAULT_SKILL_AGENTS } = {},
+) {
+  const names = [...new Set(skillNames.filter(Boolean))]
+  const targetDirs = extraSkillDirsForAgents(agents)
+
+  if (!names.length || !targetDirs.length) {
+    return { results: [], skipped: true, dryRun }
+  }
+
+  /** @type {Array<{ skill: string, dir: string, action: string }>} */
+  const results = []
+
+  for (const dir of targetDirs) {
+    for (const name of names) {
+      const source = join(cwd, CANONICAL_SKILLS_DIR, name)
+      const dest = join(cwd, dir, name)
+
+      if (!existsSync(source)) {
+        results.push({ skill: name, dir, action: 'missing-source' })
+        continue
+      }
+
+      if (existsSync(dest) || isSymlink(dest)) {
+        if (!force) {
+          results.push({ skill: name, dir, action: 'skipped' })
+          continue
+        }
+        if (!dryRun) {
+          rmSync(dest, { recursive: true, force: true })
+        }
+      }
+
+      if (dryRun) {
+        results.push({ skill: name, dir, action: 'linked' })
+        continue
+      }
+
+      ensureDir(join(cwd, dir))
+      const action = linkOrCopySkill(source, dest)
+      results.push({ skill: name, dir, action })
+    }
+  }
+
+  return { results, dryRun }
+}
+
+/**
+ * @param {string} path
+ */
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Prefer symlink; fall back to recursive copy (e.g. Windows without privilege).
+ * @param {string} source absolute
+ * @param {string} dest absolute
+ * @returns {'linked' | 'copied'}
+ */
+function linkOrCopySkill(source, dest) {
+  mkdirSync(dirname(dest), { recursive: true })
+  // Windows junctions need an absolute target; POSIX prefers a relative link.
+  const rel = relative(dirname(dest), source) || '.'
+  try {
+    if (process.platform === 'win32') {
+      symlinkSync(source, dest, 'junction')
+    } else {
+      symlinkSync(rel, dest, 'dir')
+    }
+    return 'linked'
+  } catch {
+    try {
+      symlinkSync(rel, dest, 'dir')
+      return 'linked'
+    } catch {
+      cpSync(source, dest, { recursive: true })
+      return 'copied'
+    }
+  }
+}
+
+/**
+ * Discover skill folder names already present under `.agents/skills`.
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+export function listCanonicalSkillFolders(cwd) {
+  const root = join(cwd, CANONICAL_SKILLS_DIR)
+  if (!existsSync(root)) return []
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+    .filter((entry) => existsSync(join(root, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
 }
 
 /**

package/template/AGENTS.md

@@ -30,4 +30,4 @@ Editor-neutral always-on guidance for AI agents (Cursor, VS Code, Zed, Copilot,
 | Component pick | `recommend_component`, `get_component`, `get_example` |
 | Offline recipes | skill `references/` under `morya-ui-pages` |
 
-Setup writes editor MCP configs (Cursor / VS Code / Zed) and root `.mcp.json`. Reload MCP after `npx @morya-ui/setup ai`.
+Canonical skills live under `.agents/skills/` (Cursor, Zed, VS Code Copilot). Setup also mirrors them into `.claude/skills`, `.windsurf/skills`, and `.github/skills` for Claude Code / Windsurf / Copilot discovery. MCP configs: Cursor / VS Code / Zed + root `.mcp.json`. Reload MCP after `npx @morya-ui/setup ai`. Zed may require trusting the worktree before project skills load.