@rch4com/agent-setup 1.11.1 → 1.12.0

package/lib/bootstrap/manifest.mjs

@@ -52,8 +52,20 @@ export const MANIFEST = {
     { path: '.vscode/settings.json', key: 'chat.useAgentsMdFile', value: true },
   ],
 
-  // .agents/skills 를 가리키는 도구별 어댑터
-  // 두 Copilot은 .agents/skills를 네이티브로 탐색하므로 여기에 없다.
+  // .agents/skills 를 가리키는 도구별 어댑터.
+  //
+  // 여기에 없는 도구는 그 경로를 네이티브로 읽는다 — 2026-08-15에 도구별로
+  // 실측했다. Codex는 `codex debug prompt-input`이 프로젝트 SKILL.md 경로를
+  // 그대로 찍고, OpenCode·Kilo Code는 `debug skill`이, Copilot CLI는
+  // `skill list`가 같은 것을 보여 준다. Kimi Code는 배포본에
+  // `PROJECT_GENERIC_DIRS = [".agents/skills"]`가 있고, VS Code Copilot 확장은
+  // 프로젝트 경로 표에 `.agents/skills/<name>/`를 싣는다. Antigravity 바이너리도
+  // `{workspace}/.agents/skills/{skill_name}/SKILL.md`를 갖고 있다.
+  //
+  // 네이티브로 읽는 도구에 어댑터를 더하면 같은 스킬이 두 경로에서 잡혀 중복
+  // 등록된다 — 목록을 늘리기 전에 반드시 그 도구가 못 읽는 것을 먼저 확인한다.
+  // Kiro가 그 증거다: 확장이 `~/.kiro/skills/`와 `<workspace>/.kiro/skills/`만
+  // 훑고 `.agents/skills`는 한 번도 참조하지 않아, 이 어댑터가 있어야만 닿는다.
   adapters: [
     { tool: 'Claude Code', path: '.claude/skills' },
     { tool: 'Kiro', path: '.kiro/skills' },

package/lib/catalog.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs'
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { execFile } from 'node:child_process'
@@ -140,12 +140,12 @@ export function defineMcp({ id, label, server, supports = [...CLI_IDS], unsuppor
 // 배선은 Claude 한 곳이라도 미배선 "사유"는 CLI마다 다를 수 있다 — 상류가
 // 자체 경로로 지원하는 CLI에 일괄 "Claude 전용" 사유를 붙이면 거짓 정보가 된다.
 // 항목이 사유를 넘기면 그 CLI만 덮고, 나머지는 기본 사유로 채운다.
-export function definePlugin({ id, label, installId, detectIds, marketplace, note, group = null, unsupported: reasons = {} }) {
+export function definePlugin({ id, label, installId, detectIds, marketplace, note, group = null, exclusive = null, unsupported: reasons = {} }) {
   const unsupported = Object.fromEntries(
     CLI_IDS.filter((c) => c !== 'claude').map((c) => [c, reasons[c] ?? msg('item.unsupported.claudePlugin')]),
   )
   return {
-    id, category: 'plugin', label, scope: 'project', supports: ['claude'], unsupported, note, group,
+    id, category: 'plugin', label, scope: 'project', supports: ['claude'], unsupported, note, group, exclusive,
     async detect({ root }) {
       return { status: isPluginEnabled(root, detectIds) ? 'installed' : 'absent' }
     },
@@ -207,28 +207,91 @@ function findSkillDir(root, skill) {
   return null
 }
 
+// 레지스트리가 저장소 루트에 남기는 잠금 파일. 스킬 이름마다 어느 출처에서
+// 왔는지를 적어 두므로, 한 상류가 여러 스킬을 깔았을 때 "우리가 넣은 것"만
+// 골라 지울 수 있는 유일한 근거다.
+const SKILLS_LOCK = 'skills-lock.json'
+
+// 잠금 파일의 source는 `owner/repo`로 정규화돼 있고 항목은 URL을 넘긴다.
+function sourceKey(source) {
+  return String(source).replace(/^https?:\/\/github\.com\//, '').replace(/\.git$/, '').replace(/\/+$/, '')
+}
+
+function readLock(root) {
+  const file = repoPath(root, SKILLS_LOCK)
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch {
+    // 잠금 파일이 깨졌다고 제거를 막지는 않는다 — 디렉터리 스캔 폴백이 있다.
+    return null
+  }
+}
+
+function lockedSkills(root, source) {
+  const want = sourceKey(source)
+  return Object.entries(readLock(root)?.skills ?? {})
+    .filter(([, v]) => sourceKey(v?.source ?? '') === want)
+    .map(([name]) => name)
+}
+
+// 레지스트리의 remove는 디렉터리도, 잠금 파일의 항목도 남긴다(실측). 디렉터리는
+// 아래에서 우리가 지우는데 잠금 항목을 그대로 두면 파일이 "설치돼 있다"고
+// 거짓말한다 — 커밋해서 팀과 나누는 파일이라, 동료가 experimental_install로
+// 복원하면 지운 스킬이 되살아난다.
+function pruneLock(root, names) {
+  const parsed = readLock(root)
+  const skills = parsed?.skills
+  if (!skills) return
+  const gone = names.filter((n) => Object.hasOwn(skills, n))
+  if (gone.length === 0) return
+  for (const n of gone) delete skills[n]
+  const file = repoPathStrict(root, SKILLS_LOCK)
+  // 남은 스킬이 없으면 파일째 지운다. 이 파일은 레지스트리가 만든 산출물이라
+  // 빈 껍데기를 남기면 우리가 만든 흔적이 저장소에 계속 남는다.
+  if (Object.keys(skills).length === 0) rmSync(file, { force: true })
+  else writeFileSync(file, `${JSON.stringify(parsed, null, 2)}\n`)
+}
+
 // vercel-labs/skills 레지스트리로 설치하는 스킬. `--agent universal`의 프로젝트
 // 경로가 .agents/skills라, 한 번 설치하면 10개 CLI가 함께 본다 — Claude·Kiro·
-// Grok은 부트스트랩이 만든 Junction으로, 나머지는 그 경로를 네이티브로 읽는다.
+// Grok은 부트스트랩이 만든 Junction으로, 나머지는 그 경로를 네이티브로 읽는다
+// (도구별 실측 근거는 bootstrap/manifest.mjs의 adapters 주석에 있다).
 // `--copy`로 실물을 남긴다: 커밋해서 팀과 나누는 자리라 링크는 클론 뒤 깨진다.
-export function defineRegistrySkill({ id, label, source, skill, note, group = null }) {
+//
+// skill에 `*`를 주면 그 상류의 스킬을 전부 넣는다. 그때 detect가 볼 대표
+// 스킬을 anchor로 지정해야 한다 — 디렉터리가 여럿이라 "무엇이 있으면 설치된
+// 것인가"를 이름 하나로 정해 두지 않으면 판정이 흔들린다.
+//
+// exclusive는 같은 상류를 플러그인으로도 넣을 수 있을 때 쓴다. 두 경로가 겹치면
+// 같은 스킬이 두 번 등록되므로 하나만 고르게 막는다.
+export function defineRegistrySkill({ id, label, source, skill, anchor = null, note, group = null, exclusive = null }) {
+  const probe = anchor ?? skill
+  if (skill === '*' && !anchor) throw new LocalizedError('error.registrySkillAnchor', { id })
   return {
-    id, category: 'skill', label, scope: 'project', supports: [...CLI_IDS], unsupported: {}, note, group,
+    id, category: 'skill', label, scope: 'project', supports: [...CLI_IDS], unsupported: {}, note, group, exclusive,
     async detect({ root }) {
-      return { status: findSkillDir(root, skill) ? 'installed' : 'absent' }
+      return { status: findSkillDir(root, probe) ? 'installed' : 'absent' }
     },
     async install({ root, exec }) {
       const r = await exec('npx', ['-y', 'skills@latest', 'add', source, '--skill', skill, '--agent', 'universal', '--yes', '--copy'], { cwd: root })
       if (!r.ok) throw new LocalizedError('error.registrySkillInstall', { skill, output: r.output })
     },
     async uninstall({ root, dryRun, exec }) {
-      // 레지스트리의 remove는 --agent universal에서 "Done!"을 찍고도 디렉터리를
-      // 남긴다(실측). 그래서 성공/실패와 무관하게 남은 디렉터리를 우리가 지운다 —
-      // 남겨 두면 detect가 계속 installed로 읽어 제거가 안 된 채 성공으로 보인다.
-      await exec('npx', ['-y', 'skills@latest', 'remove', skill, '--agent', 'universal', '--yes'], { cwd: root })
-      if (dryRun) return
-      const dir = findSkillDir(root, skill)
-      if (dir) rmSync(repoPathStrict(root, `${SHARED_SKILLS}/${dir}`), { recursive: true, force: true })
+      // 지울 이름을 먼저 정한다. 여러 스킬을 깐 항목은 잠금 파일이 알려 주고,
+      // 잠금 파일이 없거나 깨졌으면 대표 스킬 하나라도 치운다.
+      const names = skill === '*' ? lockedSkills(root, source) : [skill]
+      const targets = names.length > 0 ? names : [probe]
+      for (const name of targets) {
+        // 레지스트리의 remove는 --agent universal에서 "Done!"을 찍고도 디렉터리를
+        // 남긴다(실측). 그래서 성공/실패와 무관하게 남은 디렉터리를 우리가 지운다 —
+        // 남겨 두면 detect가 계속 installed로 읽어 제거가 안 된 채 성공으로 보인다.
+        await exec('npx', ['-y', 'skills@latest', 'remove', name, '--agent', 'universal', '--yes'], { cwd: root })
+        if (dryRun) continue
+        const dir = findSkillDir(root, name)
+        if (dir) rmSync(repoPathStrict(root, `${SHARED_SKILLS}/${dir}`), { recursive: true, force: true })
+      }
+      if (!dryRun) pruneLock(root, targets)
     },
   }
 }

package/lib/i18n/catalog/en.mjs

@@ -264,6 +264,8 @@ export default {
   'item.skill.taste.note': 'anti-slop frontend skill for landing pages, portfolios and redesigns (skill name: design-taste-frontend)',
   'item.skill.hallmark.note': 'anti-AI-slop design skill with four verbs (build, audit, redesign, study). 21 themes and 57 slop-test gates. Upstream also documents Cursor and Codex paths; the shared skills directory covers all 10 CLIs at once',
   'item.skill.diagram-design.note': 'draws 27 diagram types in HTML/SVG using your brand colors and fonts; also redraws Mermaid and draw.io sources. The default fonts (Instrument Serif, Geist) carry no CJK glyphs — swap them in style-guide.md — and PNG export needs Playwright and Chromium separately. The three upstream slash commands are left out, but the references/ they delegate to come along',
+  'item.skill.superpowers.note': 'copies 14 skills into the shared .agents/skills so all 10 CLIs see them. Only one of this and the plugin edition can be chosen — this route has no session-start hook, so nothing is injected at the start of a conversation and skills are invoked on demand',
+  'item.skill.mattpocock-skills.note': 'copies 35 skills into the shared .agents/skills so all 10 CLIs see them. Upstream documents this route itself, and with no hooks involved nothing is lost against the plugin edition. Only one of the two can be chosen',
   'item.skill.karpathy.note': 'behavioral guidelines that curb overbuilding and vague success criteria',
   'item.skill.gstack.note': 'repo-local clone + setup (needs bash; Git Bash on Windows). Runtime state (~/.gstack) may be created globally.',
   'item.skill.gsd.note': 'npx @opengsd/gsd-core, installed per project. Upstream supports 18 runtimes (Codex, Antigravity, …); this item wires --claude only',
@@ -276,13 +278,14 @@ export default {
   'log.gitmessage.remove': '  [dry-run] remove {path}',
   'error.gitmessageForeign': '{path} already exists and was not written by this tool. A hand-written template is never overwritten — move or delete it first.',
   'error.gitmessageConfig': 'git config commit.template failed: {output}',
-  'error.exclusiveItems': 'These items write the same file, so only one can be chosen: {ids}',
+  'error.exclusiveItems': 'These items compete for the same slot, so only one can be chosen: {ids}',
   'error.gstackClone': 'gstack clone failed: {output}',
   'error.gstackSetup': 'gstack setup failed: {output}',
   'error.gsdInstall': 'GSD install failed: {output}',
   'error.gsdUninstall': 'GSD uninstall failed: {output}',
   'error.ponytailOpencodePlugin': '{file}: the plugin key is not an array. Leaving it alone — add "@dietrichgebert/ponytail" by hand.',
   'error.registrySkillInstall': 'skill registry install failed ({skill}): {output}',
+  'error.registrySkillAnchor': "{id}: when skill is '*', an anchor skill must be named for detect to look at",
   'error.itemFieldMissing': '{file}: {field} missing',
   'error.itemReasonMissing': '{id}: needs a reason for unsupported CLI \'{cli}\' (unsupported.{cli})',
   'error.shellQuote': 'The argument contains a double quote that cannot be passed to the shell: {value}',
@@ -319,7 +322,7 @@ export default {
   'tui.toggledAll': 'Selected every visible item in the {tab} tab.',
   'tui.toggledNone': 'Cleared every visible item in the {tab} tab.',
   // 배타 묶음에서 형제가 함께 꺼졌을 때. 조용히 뒤집히면 오조작으로 읽힌다.
-  'tui.exclusiveSwitched': 'Switched to {kept} — they share one file, so {dropped} was cleared.',
+  'tui.exclusiveSwitched': 'Switched to {kept} — they compete for the same slot, so {dropped} was cleared.',
   'tui.nonInteractive': 'The interactive screen only opens in a terminal. --list and --set work too.',
   'tui.pressAnyKey': 'Press any key to continue…',
   'tui.confirmSuffix': ' [y/N] ',

package/lib/i18n/catalog/ko.mjs

@@ -257,6 +257,8 @@ export default {
   'item.skill.taste.note': '랜딩 페이지·포트폴리오·리디자인용 안티슬롭 프런트엔드 스킬 (스킬 이름: design-taste-frontend)',
   'item.skill.hallmark.note': '네 가지 동사(신규 제작·audit·redesign·study)를 갖춘 안티 AI슬롭 디자인 스킬. 테마 21종과 슬롭 테스트 57종. 상류는 Cursor·Codex 경로도 안내하지만 공유 스킬 디렉터리 하나로 10개 CLI가 함께 봅니다',
   'item.skill.diagram-design.note': '브랜드 색·폰트로 다이어그램 27종을 그리는 HTML/SVG 스킬. Mermaid·draw.io 원본도 다시 그립니다. 기본 폰트(Instrument Serif·Geist)에 한글 글리프가 없어 style-guide.md에서 바꿔야 하고, PNG 내보내기는 Playwright·Chromium이 따로 필요합니다. 상류 플러그인의 명령 3개는 빠지지만 그 본문인 references/는 그대로 옵니다',
+  'item.skill.superpowers.note': '공유 .agents/skills에 스킬 14종을 복사해 10개 CLI가 함께 봅니다. 플러그인 판과 하나만 고를 수 있습니다 — 이쪽은 session-start 훅이 없어 대화 시작 시 자동 주입이 되지 않고, 스킬을 불러서 씁니다',
+  'item.skill.mattpocock-skills.note': '공유 .agents/skills에 스킬 35종을 복사해 10개 CLI가 함께 봅니다. 상류가 직접 안내하는 경로이며 훅이 없어 플러그인 판에 견줘 잃는 것이 없습니다. 둘 중 하나만 고를 수 있습니다',
   'item.skill.karpathy.note': '과설계와 모호한 완료 기준을 줄이는 행동 지침',
   'item.skill.gstack.note': '저장소 로컬 clone + setup (bash 필요, Windows는 Git Bash). 런타임 상태(~/.gstack)는 전역에 생길 수 있음.',
   'item.skill.gsd.note': 'npx @opengsd/gsd-core 프로젝트 로컬 설치. 상류는 Codex·Antigravity 등 18개 런타임을 지원합니다(이 항목은 --claude)',
@@ -268,13 +270,14 @@ export default {
   'log.gitmessage.remove': '  [dry-run] {path} 제거',
   'error.gitmessageForeign': '{path}가 이미 있고 이 도구가 쓴 내용이 아닙니다. 손으로 쓴 템플릿은 덮어쓰지 않습니다 — 먼저 옮기거나 지우세요.',
   'error.gitmessageConfig': 'git config commit.template 실패: {output}',
-  'error.exclusiveItems': '같은 파일을 쓰는 항목이라 하나만 고를 수 있습니다: {ids}',
+  'error.exclusiveItems': '한 자리를 두고 다투는 항목이라 하나만 고를 수 있습니다: {ids}',
   'error.gstackClone': 'gstack clone 실패: {output}',
   'error.gstackSetup': 'gstack setup 실패: {output}',
   'error.gsdInstall': 'GSD 설치 실패: {output}',
   'error.gsdUninstall': 'GSD 제거 실패: {output}',
   'error.ponytailOpencodePlugin': '{file}: plugin 키가 배열이 아닙니다. 덮어쓰지 않고 그대로 둡니다 — "@dietrichgebert/ponytail"을 직접 추가하세요.',
   'error.registrySkillInstall': '스킬 레지스트리 설치 실패 ({skill}): {output}',
+  'error.registrySkillAnchor': "{id}: skill이 '*'이면 detect가 볼 대표 스킬을 anchor로 지정해야 합니다",
   'error.itemFieldMissing': '{file}: {field} 누락',
   'error.itemReasonMissing': '{id}: 미지원 CLI \'{cli}\'의 사유(unsupported.{cli})가 필요합니다',
   'error.shellQuote': '셸에 넘길 수 없는 큰따옴표가 인자에 있습니다: {value}',
@@ -309,7 +312,7 @@ export default {
   'tui.toggledAll': '{tab} 탭의 보이는 항목을 모두 선택했습니다.',
   'tui.toggledNone': '{tab} 탭의 보이는 항목을 모두 해제했습니다.',
   // 배타 묶음에서 형제가 함께 꺼졌을 때. en.mjs 쪽 주석 참고.
-  'tui.exclusiveSwitched': '{kept}(으)로 바꿨습니다 — 같은 파일이라 {dropped}은(는) 해제했습니다.',
+  'tui.exclusiveSwitched': '{kept}(으)로 바꿨습니다 — 한 자리를 두고 다투므로 {dropped}은(는) 해제했습니다.',
   'tui.nonInteractive': '대화형 화면은 터미널에서만 열립니다. --list · --set 으로도 다룰 수 있습니다.',
   'tui.pressAnyKey': '계속하려면 아무 키나 누르세요…',
   'tui.confirmSuffix': ' [y/N] ',

package/lib/items/plugin.mattpocock-skills.mjs

@@ -7,7 +7,8 @@ import { msg } from '../i18n/index.mjs'
 // 아니라 "우리가 플러그인 쪽을 골랐다"이고, 사유가 그렇게 말해야 레지스트리
 // 항목으로 옮길 수 있다는 것도 화면에서 읽힌다.
 export default definePlugin({
-  id: 'plugin.mattpocock-skills', label: 'Matt Pocock skills', group: '__flow',
+  id: 'plugin.mattpocock-skills', label: 'Matt Pocock (plugin)', group: '__flow',
+  exclusive: 'mattpocock',
   installId: 'mattpocock-skills@mattpocock',
   detectIds: ['mattpocock-skills@mattpocock'],
   marketplace: { name: 'mattpocock', repo: 'mattpocock/skills' },

package/lib/items/plugin.superpowers.mjs

@@ -13,7 +13,8 @@ import { msg } from '../i18n/index.mjs'
 const SEPARATE = ['codex', 'gemini', 'opencode', 'kimi', 'copilot', 'grok']
 
 export default definePlugin({
-  id: 'plugin.superpowers', label: 'superpowers', group: '__flow',
+  id: 'plugin.superpowers', label: 'superpowers (plugin)', group: '__flow',
+  exclusive: 'superpowers',
   installId: 'superpowers@claude-plugins-official',
   detectIds: ['superpowers@claude-plugins-official', 'superpowers@superpowers-marketplace'],
   note: 'item.plugin.superpowers.note',

package/lib/items/skill.mattpocock-skills.mjs

@@ -0,0 +1,16 @@
+import { defineRegistrySkill } from '../catalog.mjs'
+// 상류가 "Codex, and other agents" 절에서 이 경로를 직접 안내한다 —
+// `npx skills add mattpocock/skills`다. 그러니 이쪽이 곁길이 아니라 상류가
+// 의도한 두 경로 중 하나다. 훅이 없는 스킬 묶음이라 플러그인 판에 견줘 잃는
+// 것도 없다(35개 실측, skills/<분류>/<이름>/SKILL.md 배치).
+//
+// anchor는 setup-matt-pocock-skills다. 상류 README가 "이것만은 반드시 고르라"고
+// 적어 둔 스킬이라 설치 판정의 기준으로도 맞는다.
+export default defineRegistrySkill({
+  id: 'skill.mattpocock-skills', label: 'Matt Pocock (skills)', group: '__flow',
+  source: 'https://github.com/mattpocock/skills',
+  skill: '*',
+  anchor: 'setup-matt-pocock-skills',
+  exclusive: 'mattpocock',
+  note: 'item.skill.mattpocock-skills.note',
+})

package/lib/items/skill.superpowers.mjs

@@ -0,0 +1,19 @@
+import { defineRegistrySkill } from '../catalog.mjs'
+// 같은 상류를 플러그인(plugin.superpowers)으로도 넣을 수 있다. 그쪽은 Claude
+// 하나만 닿는 대신 session-start 훅으로 알아서 켜지고, 이쪽은 공유
+// .agents/skills라 10개 CLI가 함께 보는 대신 훅이 빠진다 — 스킬은 부르면 되지만
+// "대화 시작 시 using-superpowers 주입"은 오지 않는다.
+// 둘을 함께 켜면 같은 스킬이 플러그인 캐시와 공유 디렉터리 양쪽에서 잡혀 중복
+// 등록되므로 배타로 묶는다.
+//
+// 상류 배치가 skills/<이름>/SKILL.md라 레지스트리가 그대로 읽는다(14개 실측).
+// anchor는 using-superpowers다 — 상류가 "대화 시작 시 반드시 읽으라"고 못 박은
+// 부트스트랩 스킬이라, 이것이 없으면 나머지가 있어도 설치로 볼 수 없다.
+export default defineRegistrySkill({
+  id: 'skill.superpowers', label: 'superpowers (skills)', group: '__flow',
+  source: 'https://github.com/obra/superpowers',
+  skill: '*',
+  anchor: 'using-superpowers',
+  exclusive: 'superpowers',
+  note: 'item.skill.superpowers.note',
+})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rch4com/agent-setup",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Repository-scoped bootstrap and optional-item installer for using multiple coding-agent CLIs in one repository | 여러 코딩 에이전트 CLI를 한 저장소에서 함께 쓰기 위한 저장소 범위 부트스트랩과 선택 항목 설치기",
   "keywords": [
     "agents-md",