@rch4com/agent-setup 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rch4com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# agent-setup
+
+Claude Code, Codex, Gemini CLI, OpenCode, Kilo Code, Kiro, Kimi Code,
+Grok Build, Antigravity, GitHub Copilot CLI, VS Code Copilot을 **한 저장소에서
+함께** 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기입니다.
+
+공통 지침은 루트 `AGENTS.md` 하나, 공통 스킬은 `.agents/skills` 하나로 두고,
+도구별 설정 파일만 각 도구가 읽는 위치에 만듭니다.
+
+## 사용법
+
+Git 저장소 안에서 실행합니다.
+
+```bash
+# 배선 — 공통 지침·스킬·도구별 설정 파일을 만든다
+npx @rch4com/agent-setup bootstrap
+
+# 무엇이 만들어질지만 확인한다
+npx @rch4com/agent-setup bootstrap --dry-run
+
+# 플러그인·MCP·스킬·DESIGN.md를 골라 설치하는 대화형 화면
+npx @rch4com/agent-setup
+```
+
+설치하면 실행 명령은 `agent-setup`으로 짧아집니다. 이름에 스코프가 붙은 것은
+스코프 없는 `agent-setup`이 npm의 유사 이름 제한에 걸리기 때문입니다.
+
+## 안전 원칙
+
+- 반드시 Git 저장소 안에서만 실행되며, 저장소 루트 밖에는 쓰지 않습니다.
+- 홈 디렉터리의 글로벌 설정을 읽거나 수정하지 않습니다.
+- 기존 설정 파일을 덮어쓰지 않습니다.
+- 반복 실행할 수 있습니다.
+
+## 요구 사항
+
+Node.js 20 이상.
+
+## 문서
+
+생성되는 구조, 도구별 연결 방식, 설치 가능한 항목, DESIGN.md 라이브러리 등
+상세 문서는 GitHub에 있습니다.
+
+- [사용법과 생성 구조](https://github.com/rch4com/Agent-Setup/blob/main/AgentSetup-README.md)
+- [저장소](https://github.com/rch4com/Agent-Setup)
+
+## 라이선스
+
+MIT

package/install.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { findRepoRoot } from './lib/context.mjs'
+import { runBootstrap } from './lib/bootstrap/flow.mjs'
+import { withDeps } from './lib/deps.mjs'
+import {
+  BOOTSTRAP_USAGE, DESIGN_USAGE, ROOT_USAGE,
+  parseBootstrapArgs, parseDesignArgs, parseRootArgs,
+} from './lib/args.mjs'
+
+// 위 정적 import는 전부 의존성 없는 모듈이다 — 부트스트랩은 npm install 없이 돌아야 하고,
+// bootstrap.isolation.test.mjs가 이 불변식을 지킨다. lib/ 나머지는 동적 import로만 닿는다.
+
+const STATUS_LABEL = { installed: '설치됨', partial: '일부 설치됨', absent: '미설치' }
+const ACTION_LABEL = { install: '설치', complete: '보완 설치', uninstall: '제거' }
+
+// 대화형 화면은 TUI가 맡는다.
+async function openTui(root, { dryRun, skillMode, designDirs }) {
+  const { runTui } = await withDeps(() => import('./lib/tui/run.mjs'))
+  // skillMode는 화면 안의 '부트스트랩 실행' 작업이 쓴다. design 경로에서는
+  // 없으므로 undefined가 넘어가고 runTui의 기본값(auto)이 적용된다.
+  await runTui(root, { dryRun, skillMode, designDirs })
+}
+
+// --list / --set 전용 비대화형 경로.
+async function runClassic(root, { dryRun, listOnly, setArg }) {
+  const { loadItems } = await withDeps(() => import('./lib/catalog.mjs'))
+  const { scan, planChanges, apply } = await withDeps(() => import('./lib/engine.mjs'))
+  const items = await loadItems()
+  const states = await scan(root, items)
+
+  if (listOnly) {
+    for (const s of states) console.log(`${STATUS_LABEL[s.status].padEnd(7)} ${s.item.id} — ${s.item.label}${s.detail ? ` (${s.detail})` : ''}`)
+    return
+  }
+
+  const selectedIds = new Set(setArg.split(',').map((s) => s.trim()).filter(Boolean))
+  const known = new Set(items.map((i) => i.id))
+  for (const id of selectedIds) if (!known.has(id)) throw new Error(`알 수 없는 항목: ${id}`)
+
+  const changes = planChanges(states, selectedIds)
+  if (changes.length === 0) { console.log('변경할 항목이 없습니다.'); return }
+
+  const results = await apply(root, changes, { dryRun })
+  for (const r of results) {
+    console.log(`${r.ok ? '✔' : '✖'} ${ACTION_LABEL[r.action]} ${r.item.label}${r.message ? ` — ${r.message}` : ''}`)
+  }
+
+  const after = await scan(root, items)
+  console.log('\n최종 상태:')
+  for (const s of after) console.log(`  ${STATUS_LABEL[s.status].padEnd(7)} ${s.item.label}`)
+  console.log('\n설정 파일 변경 내용은 git diff로 확인할 수 있습니다.')
+  if (results.some((r) => !r.ok)) process.exitCode = 1
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const root = findRepoRoot()
+
+  if (argv[0] === 'bootstrap') {
+    const opts = parseBootstrapArgs(argv.slice(1))
+    if (opts.help) { console.log(BOOTSTRAP_USAGE); return }
+    const { failed } = runBootstrap(root, opts)
+    if (failed.length > 0) process.exitCode = 1
+    return
+  }
+
+  if (argv[0] === 'design') {
+    const opts = parseDesignArgs(argv.slice(1))
+    if (opts.help) { console.log(DESIGN_USAGE); return }
+    // 플래그 없는 `design`은 통합 화면을 연다 — DESIGN.MD 섹션이 그 안에 있다.
+    if (opts.interactive) return openTui(root, opts)
+    const { runDesign } = await withDeps(() => import('./lib/design-md/flow.mjs'))
+    await runDesign(root, opts)
+    return
+  }
+
+  const opts = parseRootArgs(argv)
+  if (opts.help) { console.log(ROOT_USAGE); return }
+  if (opts.interactive) return openTui(root, opts)
+  await runClassic(root, opts)
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1) })

package/lib/args.mjs

@@ -0,0 +1,266 @@
+// 인자 파싱만 한다 — 파일시스템도 콘솔도 프로세스도 모른다.
+// install.mjs에서 분리한 이유: 진입점은 최상위에서 main()을 실행하므로
+// import하는 순간 설치기가 돌아버려 순수 함수를 단위 테스트할 수 없었다.
+//
+// 오류는 전부 throw다. 종료 코드는 진입점 한 곳에서 정한다 —
+// 예전에는 --set만 process.exit(2)로 빠져나가 같은 사용자 오류가
+// 경로에 따라 1과 2로 갈렸다.
+
+// `bootstrap` 서브커맨드 사용법. install.mjs와 두 런처(setup-agents.sh/.ps1) 모두에서 안내한다.
+export const BOOTSTRAP_USAGE = `사용법: npx @rch4com/agent-setup bootstrap [--skill-mode auto|link|copy] [--dry-run]
+       node install.mjs bootstrap [옵션]   # 저장소에 설치기를 두고 쓸 때
+
+옵션:
+  --skill-mode auto|link|copy  스킬 연결 방식을 지정합니다. (기본값: auto)
+                                  auto: 심볼릭 링크를 먼저 시도하고, 실패하면 복사로 전환합니다.
+                                  link: 심볼릭 링크만 시도합니다. 실패하면 오류로 종료합니다.
+                                  copy: 항상 복제본을 만듭니다.
+  --dry-run                    아무것도 바꾸지 않고 예정된 동작만 출력합니다.
+  -h, --help                   이 도움말을 출력하고 종료합니다.
+
+런처로도 사용할 수 있습니다:
+  ./setup-agents.sh [옵션]
+  pwsh -File ./setup-agents.ps1 [옵션]
+  --tui (또는 -Tui)를 주면 의존성을 설치하고 대화형 화면을 엽니다.
+  거기서 부트스트랩·에이전트·design.md를 한 목록에서 검색하고 고릅니다.`
+
+// 서브커맨드 없는 최상위 사용법. `design`은 자기 사용법을 따로 갖는다.
+export const ROOT_USAGE = `사용법: npx @rch4com/agent-setup [옵션]
+       npx @rch4com/agent-setup bootstrap [옵션]
+       npx @rch4com/agent-setup design [옵션]
+
+저장소에 설치기를 두고 쓸 때는 npx @rch4com/agent-setup 자리에
+node install.mjs 를 넣으면 됩니다.
+
+옵션이 없으면 대화형 화면을 엽니다 — 부트스트랩·에이전트·design.md를
+한 목록에서 검색하고 고릅니다.
+
+옵션:
+  --list                       현재 설치 상태만 출력하고 종료합니다.
+  --set <목록>                 쉼표로 구분한 항목을 목표 상태로 맞춥니다.
+                               전체 제거는 --set "" 로 명시하세요.
+  --skill-mode auto|link|copy  대화형 화면에서 실행하는 부트스트랩의 스킬
+                               연결 방식입니다. (기본값: auto)
+  --design-dir <경로>          design.md 소스를 더합니다. <소스id>=<경로>
+                               형식도 받으며 반복 지정할 수 있습니다.
+  --dry-run                    아무것도 바꾸지 않고 예정된 동작만 출력합니다.
+  -h, --help                   이 도움말을 출력하고 종료합니다.
+
+--list와 --set은 동작을 고르는 플래그라 함께 쓸 수 없습니다.
+
+서브커맨드 도움말: npx @rch4com/agent-setup bootstrap --help
+                   npx @rch4com/agent-setup design --help`
+
+export const DESIGN_USAGE = `사용법: npx @rch4com/agent-setup design [옵션]
+       node install.mjs design [옵션]   # 저장소에 설치기를 두고 쓸 때
+
+옵션이 없으면 대화형 화면을 엽니다 — DESIGN.MD 섹션이 그 안에 있습니다.
+
+옵션:
+  --list                 카탈로그와 설치 상태를 출력합니다.
+  --set <목록>           쉼표로 구분한 항목을 목표 상태로 맞춥니다.
+                         토큰은 <이름> 또는 <제공자>/<이름> 입니다.
+                         전체 제거는 --set "" 로 명시하세요.
+  --preview <목록>       미리보기를 엽니다.
+  --sync=installed       설치본을 원본 최신으로 다시 받습니다.
+  --sync=catalog         사용 가능 목록·카테고리를 소스에서 다시 만듭니다.
+  --sync=stale           설치본을 원본과 해시 비교합니다.
+  --design-dir <경로>    design.md 소스를 더합니다. <소스id>=<경로>
+                         형식도 받으며 반복 지정할 수 있습니다.
+  --dry-run              아무것도 바꾸지 않고 예정된 동작만 출력합니다.
+  -h, --help             이 도움말을 출력하고 종료합니다.
+
+--list, --set, --preview, --sync는 동작을 고르는 플래그라
+한 번에 하나만 지정할 수 있습니다.`
+
+const SKILL_MODES = ['auto', 'link', 'copy']
+
+// 인자 사양: 플래그 이름 → 'bool'(값 없음) | 'value'(값 하나를 소비).
+// 미지 인자를 조용히 삼키지 않기 위한 것이다 — 오타(`--dryrun`)나 지원하지
+// 않는 형식(`--set=a`)이 무시되면 사용자는 명령이 먹혔다고 믿지만 아무 일도
+// 일어나지 않는다. bootstrap 파서만 지키던 규칙을 세 파서 모두로 넓힌다.
+const HELP_SPEC = { '-h': 'bool', '--help': 'bool' }
+const ROOT_SPEC = {
+  ...HELP_SPEC, '--dry-run': 'bool', '--list': 'bool',
+  '--set': 'value', '--skill-mode': 'value', '--design-dir': 'value',
+}
+const DESIGN_SPEC = {
+  ...HELP_SPEC, '--dry-run': 'bool', '--list': 'bool', '--set': 'value',
+  '--preview': 'value', '--sync': 'value', '--design-dir': 'value',
+}
+const BOOTSTRAP_SPEC = { ...HELP_SPEC, '--dry-run': 'bool', '--skill-mode': 'value' }
+
+export function assertKnownArgs(argv, spec, usage) {
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]
+    const eq = token.startsWith('--') ? token.indexOf('=') : -1
+    const name = eq > 0 ? token.slice(0, eq) : token
+    const kind = spec[name]
+    if (kind === undefined) throw new Error(`알 수 없는 인자입니다: ${token}\n\n${usage}`)
+    if (kind === 'bool' && eq > 0) throw new Error(`${name}에는 값을 줄 수 없습니다: ${token}\n\n${usage}`)
+    // `--플래그 값` 형태는 값 한 칸을 건너뛴다. `--플래그=값`은 이미 한 토큰이다.
+    if (kind === 'value' && eq < 0) i++
+  }
+}
+
+// 동작 플래그는 한 번에 하나만 뜻이 있다. 여러 개를 주면 실행 경로가 먼저 오는
+// 하나를 골라 나머지를 조용히 버렸다 — `--list --set a`는 --set을, design의
+// `--preview x --set y`는 --set을 무시했다. 알 수 없는 인자를 거부하는 것과
+// 같은 이유(준 인자가 먹히지 않은 채 다른 일이 벌어진다)로 같이 거부한다.
+export function assertSingleAction(argv, names, usage) {
+  const given = names.filter((name) => hasFlag(argv, name))
+  if (given.length > 1) {
+    // 조사를 붙이지 않는다 — 플래그 이름에 따라 은/는이 갈려 문장이 어색해진다.
+    throw new Error(`함께 쓸 수 없습니다: ${given.join(', ')} — 동작 플래그는 한 번에 하나만 지정하세요.\n\n${usage}`)
+  }
+}
+
+function checkSkillMode(value, usage) {
+  if (!SKILL_MODES.includes(value)) {
+    throw new Error(`--skill-mode는 ${SKILL_MODES.join(', ')} 중 하나여야 합니다: ${value}\n\n${usage}`)
+  }
+  return value
+}
+
+// `--skill-mode <값>`과 `--skill-mode=<값>`을 모두 받는다. 없으면 기본값 auto.
+export function parseSkillMode(argv, usage) {
+  let mode = 'auto'
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--skill-mode') {
+      const value = argv[i + 1]
+      if (value === undefined || value.startsWith('--')) {
+        throw new Error(`--skill-mode 뒤에 값이 필요합니다 (${SKILL_MODES.join(', ')} 중 하나).\n\n${usage}`)
+      }
+      mode = checkSkillMode(value, usage)
+      i++
+    } else if (a.startsWith('--skill-mode=')) {
+      mode = checkSkillMode(a.slice('--skill-mode='.length), usage)
+    }
+  }
+  return mode
+}
+
+function wantsHelp(argv) {
+  return argv.includes('-h') || argv.includes('--help')
+}
+
+// `--flag` 또는 `--flag=값`이 있는가. 두 형식 중 하나만 인식하면 나머지
+// 형식이 조용히 무시되어, 준 인자가 먹히지 않은 채 화면이 열린다.
+export function hasFlag(argv, name) {
+  return argv.some((a) => a === name || a.startsWith(`${name}=`))
+}
+
+export function requireValue(argv, name) {
+  const eq = argv.find((a) => a.startsWith(`${name}=`))
+  if (eq !== undefined) {
+    const value = eq.slice(name.length + 1)
+    if (!value) throw new Error(`${name} 뒤에 값이 필요합니다.`)
+    return value
+  }
+  const value = argv[argv.indexOf(name) + 1]
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${name} 뒤에 값이 필요합니다.`)
+  }
+  return value
+}
+
+// 반복 지정 가능한 플래그 값 수집: `--flag <값>` 과 `--flag=<값>` 둘 다 받는다.
+export function collectValues(argv, name) {
+  const values = []
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === name) {
+      const value = argv[i + 1]
+      if (value === undefined || value.startsWith('--')) throw new Error(`${name} 뒤에 값이 필요합니다.`)
+      values.push(value)
+      i++
+    } else if (argv[i].startsWith(`${name}=`)) {
+      const value = argv[i].slice(name.length + 1)
+      if (!value) throw new Error(`${name} 뒤에 값이 필요합니다.`)
+      values.push(value)
+    }
+  }
+  return values
+}
+
+// 빈 문자열은 유효한 값이다(전체 제거). 없음(null)과 구별해야 한다.
+// `--set <값>`과 `--set=<값>`을 모두 받는다 — 등호 형식만 인식되지 않으면
+// 목표 집합을 지정했는데도 대화형 화면이 열린다. `--set=`은 빈 값이다.
+export function parseSetArg(argv) {
+  const eq = argv.find((a) => a.startsWith('--set='))
+  if (eq !== undefined) return eq.slice('--set='.length)
+  if (!argv.includes('--set')) return null
+  const value = argv[argv.indexOf('--set') + 1]
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error('--set 뒤에 항목 목록이 필요합니다. 전체 제거는 --set "" 로 명시하세요.')
+  }
+  return value
+}
+
+// --help는 다른 인자 검증보다 앞선다 — 도움말을 보려는 사람에게 인자 오류를
+// 먼저 내밀 이유가 없다. 아래 두 파서가 같은 규칙을 따른다.
+
+// 서브커맨드 없는 최상위 인자.
+export function parseRootArgs(argv) {
+  if (wantsHelp(argv)) {
+    return { help: true, dryRun: false, listOnly: false, setArg: null, skillMode: 'auto', designDirs: [], interactive: false }
+  }
+  assertKnownArgs(argv, ROOT_SPEC, ROOT_USAGE)
+  assertSingleAction(argv, ['--list', '--set'], ROOT_USAGE)
+  const setArg = parseSetArg(argv)
+  return {
+    help: false,
+    dryRun: argv.includes('--dry-run'),
+    listOnly: argv.includes('--list'),
+    setArg,
+    // 대화형 화면에서 실행하는 부트스트랩이 이 값을 쓴다. 예전에는 루트에서
+    // 읽지 않아, 런처가 넘긴 --skill-mode가 조용히 버려졌다.
+    skillMode: parseSkillMode(argv, ROOT_USAGE),
+    designDirs: collectValues(argv, '--design-dir'),
+    // 목록·집합 지정이 없으면 대화형 화면으로 간다.
+    interactive: !argv.includes('--list') && setArg === null,
+  }
+}
+
+// `design` 서브커맨드 플래그.
+export function parseDesignArgs(argv) {
+  if (wantsHelp(argv)) {
+    return { help: true, dryRun: false, list: false, set: null, preview: null, sync: null, designDirs: [], interactive: false }
+  }
+  assertKnownArgs(argv, DESIGN_SPEC, DESIGN_USAGE)
+  assertSingleAction(argv, ['--list', '--set', '--preview', '--sync'], DESIGN_USAGE)
+  const list = argv.includes('--list')
+  const set = parseSetArg(argv)
+  const preview = hasFlag(argv, '--preview') ? requireValue(argv, '--preview') : null
+
+  let sync = null
+  const s = argv.find((a) => a === '--sync' || a.startsWith('--sync='))
+  if (s) {
+    const m = /^--sync=(installed|catalog|stale)$/.exec(s)
+    if (!m) throw new Error('--sync=installed|catalog|stale 형식으로 지정하세요.')
+    sync = m[1]
+  }
+
+  return {
+    help: false,
+    dryRun: argv.includes('--dry-run'),
+    list,
+    set,
+    preview,
+    sync,
+    designDirs: collectValues(argv, '--design-dir'),
+    interactive: !list && set === null && preview === null && sync === null,
+  }
+}
+
+// `bootstrap`에 허용되는 플래그: --dry-run, --skill-mode(+값)/--skill-mode=값, -h/--help.
+// 그 외 인자는 거부한다 — 조용히 삼켜지는 것을 막기 위해서다.
+export function parseBootstrapArgs(argv) {
+  if (wantsHelp(argv)) return { dryRun: false, skillMode: 'auto', help: true }
+  assertKnownArgs(argv, BOOTSTRAP_SPEC, BOOTSTRAP_USAGE)
+  return {
+    dryRun: argv.includes('--dry-run'),
+    skillMode: parseSkillMode(argv, BOOTSTRAP_USAGE),
+    help: false,
+  }
+}

package/lib/bootstrap/adapter.mjs

@@ -0,0 +1,95 @@
+// 스킬 어댑터 — .agents/skills를 도구별 경로에서 보이게 한다.
+// Windows는 Junction을 쓴다. 관리자 권한이 필요 없고, MSYS(Git Bash)의 ln -s가
+// 링크 대신 복사를 만드는 문제도 우회한다.
+import { cpSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { repoPath, repoPathStrict } from '../context.mjs'
+import { pathExists } from './apply.mjs'
+
+const MARKER = '.agent-kit-managed-copy'
+const SOURCE_REL = '.agents/skills'
+
+// 심볼릭 링크/Junction이면 가리키는 절대 경로를, 아니면 null을 돌려준다.
+function linkTarget(target) {
+  try {
+    if (!lstatSync(target).isSymbolicLink()) return null
+    return resolve(dirname(target), readlinkSync(target))
+  } catch {
+    return null
+  }
+}
+
+function createLink(source, target) {
+  if (process.platform === 'win32') {
+    // Junction은 절대 경로를 요구한다.
+    symlinkSync(source, target, 'junction')
+  } else {
+    symlinkSync(relative(dirname(target), source), target)
+  }
+}
+
+function createCopy(source, target) {
+  mkdirSync(target, { recursive: true })
+  cpSync(source, target, { recursive: true })
+  writeFileSync(join(target, MARKER), '', { encoding: 'utf8' })
+}
+
+export function configureAdapter(root, { tool, path: rel }, { dryRun = false, skillMode = 'auto', log }) {
+  // 기존 상태를 살펴보는 데에는 어휘적 경로를 쓴다. target이 저장소 밖을 가리키는
+  // 링크일 수 있는데, 그 경우도 "보존 + 경고"가 정답이라 지켜야 할 쓰기가 없다.
+  // repoPathStrict를 여기서 쓰면 이탈 링크에서 예외가 던져져 경고 대신 죽는다.
+  const target = repoPath(root, rel)
+
+  const linked = linkTarget(target)
+  if (linked !== null) {
+    if (linked === repoPath(root, SOURCE_REL)) {
+      log(`${tool} 스킬 링크 확인: ${rel}`)
+      return { ok: true, action: 'skip', path: rel }
+    }
+    log(`경고: ${rel} 경로가 다른 위치를 가리키는 링크입니다. 변경하지 않습니다.`)
+    return { ok: true, action: 'warn', path: rel, message: '다른 위치를 가리키는 링크' }
+  }
+
+  const managedCopy = pathExists(target) && pathExists(join(target, MARKER))
+  if (pathExists(target) && !managedCopy) {
+    log(`경고: ${rel} 경로가 이미 존재하며 agent-kit 관리 대상이 아닙니다. 변경하지 않습니다.`)
+    return { ok: true, action: 'warn', path: rel, message: '관리 대상이 아닌 기존 항목' }
+  }
+
+  // 여기부터는 실제로 링크/복사본을 만드는 경로다. 엄격 검사는 dry-run 여부와
+  // 무관하게 항상 하고(dry-run에서도 이탈 경로를 걸러내려면), 실제 파일시스템
+  // 쓰기만 !dryRun으로 막는다 — apply.mjs의 ensureDirs와 같은 형태.
+  // source(.agents/skills)는 실제로 읽어 복사하는 대상이므로 여기서 함께 검사한다.
+  const source = repoPathStrict(root, SOURCE_REL)
+  const strictTarget = repoPathStrict(root, rel)
+
+  if (dryRun) {
+    log(`${tool} 스킬 어댑터 생성 예정: ${rel} (${skillMode})`)
+    return { ok: true, action: 'skip', path: rel }
+  }
+
+  if (managedCopy) {
+    log(`${tool} 스킬 복제본 동기화: ${rel}`)
+    // 마커가 확인된 복사본만 지운다.
+    rmSync(strictTarget, { recursive: true, force: true })
+  }
+
+  mkdirSync(dirname(strictTarget), { recursive: true })
+
+  if (skillMode !== 'copy') {
+    try {
+      createLink(source, strictTarget)
+      log(`${tool} 스킬 링크 생성: ${rel} -> ${SOURCE_REL}`)
+      return { ok: true, action: 'link', path: rel }
+    } catch (err) {
+      if (skillMode === 'link') {
+        return { ok: false, action: 'link', path: rel, message: `링크 생성 실패: ${err.message}` }
+      }
+      log(`경고: ${tool} 링크 생성에 실패하여 복사 방식으로 전환합니다.`)
+    }
+  }
+
+  createCopy(source, strictTarget)
+  log(`${tool} 스킬 복제본 생성: ${rel}`)
+  return { ok: true, action: 'copy', path: rel }
+}