@rch4com/agent-setup 1.27.0 → 2.0.0

package/lib/probe.mjs

@@ -0,0 +1,111 @@
+// 감지 질의. 항목 detect는 여기 캐시만 조회한다 — CLI 목록 명령은 스캔
+// 한 번에 질의마다 한 번만 돈다. 쓰기는 하지 않는다: 읽는 파일도 CLI가
+// 소유한 설정이라, 고치는 일은 그 CLI의 명령이 맡는다.
+import { existsSync, readdirSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { CLIS } from './clis.mjs'
+import { readJson } from './jsonfile.mjs'
+import { findSkillDir } from './skills-registry.mjs'
+
+// 목록 명령 하나에 주는 시간. 설치 명령(10분)과 달리 목록은 금방 끝나야
+// 정상이다 — 멈춘 CLI 하나가 화면 전체의 스캔을 붙잡지 않게 한다.
+const PROBE_TIMEOUT_MS = 60 * 1000
+
+// 구분자는 실행 중인 OS가 아니라 platform 인자를 따른다 — Windows의 PATH를
+// 콜론으로 쪼개면 드라이브 문자(C:)에서 끊긴다.
+export function onPath(bin, { env = process.env, platform = process.platform, exists = existsSync } = {}) {
+  const win = platform === 'win32'
+  const dirs = String(env.PATH ?? env.Path ?? '').split(win ? ';' : ':').filter(Boolean)
+  // Windows는 확장자 없는 파일을 실행하지 않는다 — PATHEXT 후보만 본다.
+  const exts = win ? String(env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean) : ['']
+  return dirs.some((dir) => exts.some((ext) => exists(join(dir, `${bin}${ext}`))))
+}
+
+// `agy mcp list`는 JSON을 주지 않는다. 머리줄(NAME …) 뒤 각 줄의 첫 열이 이름이다.
+export function parseAgyMcpList(text) {
+  const lines = String(text).split(/\r?\n/).map((l) => l.trim()).filter(Boolean)
+  const head = lines.findIndex((l) => /^NAME\s/.test(l))
+  return head === -1 ? [] : lines.slice(head + 1).map((l) => l.split(/\s+/)[0])
+}
+
+// OpenCode 설정 파일. 둘 다 없으면 OpenCode가 새로 만들 자리를 돌려준다.
+export function opencodeConfigFile({ root, scope, home = homedir(), env = process.env }) {
+  const dir = scope === 'project' ? root : join(env.XDG_CONFIG_HOME || join(home, '.config'), 'opencode')
+  for (const name of ['opencode.jsonc', 'opencode.json']) {
+    if (existsSync(join(dir, name))) return join(dir, name)
+  }
+  return join(dir, scope === 'project' ? 'opencode.jsonc' : 'opencode.json')
+}
+
+export function readOpencodeConfig(opts) {
+  const file = opencodeConfigFile(opts)
+  return { file, data: readJson(file) ?? null }
+}
+
+function samePath(a, b, platform) {
+  if (!a) return false
+  const norm = (p) => (platform === 'win32' ? resolve(p).toLowerCase() : resolve(p))
+  return norm(a) === norm(b)
+}
+
+export function createProbe({ root, scope, exec, env = process.env, home = homedir(), platform = process.platform }) {
+  const memo = new Map()
+  // 실패도 캐시한다 — 같은 스캔에서 항목마다 죽은 CLI를 다시 부르지 않는다.
+  const once = (key, fn) => {
+    if (!memo.has(key)) memo.set(key, Promise.resolve().then(fn))
+    return memo.get(key)
+  }
+  const run = (cli, args) => once(`${cli} ${args.join(' ')}`, async () => {
+    const r = await exec(CLIS[cli]?.bin ?? cli, args, { cwd: root, timeout: PROBE_TIMEOUT_MS })
+    if (!r.ok) throw new Error(String(r.output ?? '').trim() || `${cli} ${args.join(' ')} failed`)
+    return r.output
+  })
+  const json = async (cli, args) => JSON.parse(await run(cli, args))
+  const opencode = () => readOpencodeConfig({ root, scope, home, env }).data
+
+  return {
+    root, scope, home,
+    has: (cli) => onPath(CLIS[cli].bin, { env, platform }),
+    async claudePlugin(ids) {
+      const list = await json('claude', ['plugin', 'list', '--json'])
+      return list.some((p) => ids.includes(p.id) && p.scope === scope
+        && (scope !== 'project' || samePath(p.projectPath, root, platform)))
+    },
+    async codexPlugin(id) {
+      const data = await json('codex', ['plugin', 'list', '--json'])
+      return (data.installed ?? []).some((p) => p.pluginId === id && p.installed !== false)
+    },
+    async agyPlugin(name) {
+      return (await json('antigravity', ['plugin', 'list', '--json'])).some((p) => p.name === name)
+    },
+    async opencodePlugin(module) {
+      const list = opencode()?.plugin
+      return Array.isArray(list) && list.includes(module)
+    },
+    async mcp(cli, name) {
+      if (cli === 'claude') {
+        // `claude mcp list`는 서버마다 연결을 검사해 느리고 네트워크를 탄다.
+        const file = scope === 'project' ? join(root, '.mcp.json') : join(home, '.claude.json')
+        return readJson(file)?.mcpServers?.[name] !== undefined
+      }
+      if (cli === 'codex') return (await json('codex', ['mcp', 'list', '--json'])).some((s) => s.name === name)
+      if (cli === 'antigravity') return parseAgyMcpList(await run('antigravity', ['mcp', 'list'])).includes(name)
+      if (cli === 'opencode') return opencode()?.mcp?.[name] !== undefined
+      return false
+    },
+    async skill(name) {
+      if (scope === 'project') return findSkillDir(root, name) !== null
+      const list = JSON.parse(await run('npx', ['-y', 'skills@latest', 'list', '-g', '--json']))
+      return list.some((s) => s.name === name)
+    },
+    exists: (rel) => existsSync(join(root, rel)),
+    dirHasPrefix(rel, prefix) {
+      try {
+        return readdirSync(join(root, rel)).some((f) => f.startsWith(prefix))
+      } catch {
+        return false
+      }
+    },
+  }
+}

package/lib/recipe-helpers.mjs

@@ -0,0 +1,205 @@
+// 항목 파일이 거의 다 쓰는 레시피 세 갈래. 명령 문법은 2026-10-24 이 머신의
+// --help 실측(claude 2.1.304, codex-cli 0.163.0, agy)과 opencode.ai/docs/cli를
+// 따른다.
+import { rmSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { repoPathStrict } from './context.mjs'
+import { LocalizedError } from './i18n/index.mjs'
+import { readOpencodeConfig } from './probe.mjs'
+import { SHARED } from './recipe.mjs'
+import { SHARED_SKILLS, findSkillDir, isSafeSkillName, lockedSkills, pruneLock, sourceKey } from './skills-registry.mjs'
+
+const SKILLS = ['npx', '-y', 'skills@latest']
+
+// 전역 설치 에이전트. skills@1.7.4 docs/agents.md의 전역 경로 기준:
+// claude-code → ~/.claude/skills, codex → ~/.agents/skills,
+// antigravity-cli → ~/.gemini/antigravity-cli/skills(agy가 읽는 전역 경로,
+// antigravity.google/docs/skills). OpenCode는 ~/.claude/skills와
+// ~/.agents/skills를 둘 다 읽으므로(opencode.ai/docs/skills) 따로 넣지 않는다 —
+// 넣으면 같은 스킬을 세 번 본다.
+export const SKILLS_AGENTS = ['claude-code', 'codex', 'antigravity-cli']
+
+const OPENCODE_FILE = {
+  project: 'the project config ./opencode.jsonc (or ./opencode.json if only that one exists)',
+  user: 'the global config ~/.config/opencode/opencode.json (or opencode.jsonc there if only that one exists)',
+}
+
+// `opencode mcp add`는 대화형뿐이라 OpenCode 에이전트에게 편집을 맡긴다.
+// 지시문에는 큰따옴표를 남기지 않는다 — Windows에서 명령 한 줄은 cmd.exe를
+// 거치고, shellQuote는 그 안의 큰따옴표를 안전하게 이스케이프할 수 없어 거부한다.
+export function opencodePrompt(scope, task) {
+  return `Edit ${OPENCODE_FILE[scope]}. ${task} Keep comments and every other key unchanged. Do not run any other command. Reply only DONE.`
+    .replace(/"/g, "'")
+}
+
+// JSON을 작은따옴표로 적고 "파일에는 표준 JSON으로"라고 덧붙인다.
+const quotedJson = (value) => `${JSON.stringify(value)} (written with single quotes here; use standard JSON double quotes in the file)`
+
+// LLM 실행이라 결과가 비결정적이다 — 파일을 다시 읽는 이 단계가 유일한 성공 근거다.
+function verifyOpencode(scope, check, describe) {
+  return {
+    describe,
+    fn: ({ root }) => {
+      const { file, data } = readOpencodeConfig({ root, scope, home: homedir() })
+      if (!check(data)) throw new LocalizedError('error.opencodeVerify', { file })
+    },
+  }
+}
+
+const fileName = (scope) => (scope === 'project' ? './opencode.jsonc' : '~/.config/opencode/opencode.json')
+
+// `codex mcp add --url`은 OAuth를 쓰는 서버면 설정을 쓴 뒤 로그인 콜백을 기다리다
+// 약 5분 뒤 실패로 끝난다(2026-10-24 supabase 실측, codex-cli 0.163.0). 등록은 이미
+// 끝났으므로 짧게 끊고, 목록 명령으로 등록됐는지 확인한다. 로그인은 사용자가
+// `codex mcp login <이름>`으로 따로 한다(postInstall 안내).
+const CODEX_LOGIN_WAIT_MS = 20 * 1000
+
+function verifyCodexMcp(name) {
+  return {
+    describe: `check codex mcp list has ${name}`,
+    fn: async ({ root, exec }) => {
+      const r = await exec('codex', ['mcp', 'list', '--json'], { cwd: root })
+      let names = []
+      try { names = JSON.parse(r.output).map((s) => s.name) } catch { /* 목록을 못 읽으면 아래에서 실패로 보고한다 */ }
+      if (!r.ok || !names.includes(name)) throw new LocalizedError('error.codexMcpVerify', { name })
+    },
+  }
+}
+
+export function marketplacePlugin({ claude, codex, opencode, antigravity }) {
+  const recipes = {}
+  const detect = {}
+  if (claude) {
+    const at = (scope) => ({
+      install: [
+        ...(claude.marketplace ? [{ argv: ['claude', 'plugin', 'marketplace', 'add', claude.marketplace, '--scope', scope], tolerateFail: true }] : []),
+        ['claude', 'plugin', 'install', claude.id, '--scope', scope],
+      ],
+      uninstall: [['claude', 'plugin', 'uninstall', claude.id, '--scope', scope]],
+    })
+    recipes.claude = { project: at('project'), user: at('user') }
+    detect.claude = (p) => p.claudePlugin(claude.detectIds ?? [claude.id])
+  }
+  if (codex) {
+    // Codex는 범위 플래그가 없다 — 활성 CODEX_HOME 하나에 깔린다(전역).
+    recipes.codex = {
+      user: {
+        install: [{ argv: ['codex', 'plugin', 'marketplace', 'add', codex.marketplace], tolerateFail: true }, ['codex', 'plugin', 'add', codex.id]],
+        uninstall: [['codex', 'plugin', 'remove', codex.id]],
+      },
+    }
+    detect.codex = (p) => p.codexPlugin(codex.id)
+  }
+  if (opencode) {
+    // 설치 명령은 있지만 제거 명령은 문서에 없다 — 제거는 run 지시문 + 검증이다.
+    const at = (scope) => ({
+      install: [['opencode', 'plugin', opencode.module, ...(scope === 'user' ? ['-g'] : [])]],
+      uninstall: [
+        ['opencode', 'run', opencodePrompt(scope, `Remove the string '${opencode.module}' from the top-level 'plugin' array; delete the array if it becomes empty.`)],
+        verifyOpencode(scope, (d) => !(Array.isArray(d?.plugin) && d.plugin.includes(opencode.module)), `check ${fileName(scope)} no longer lists plugin ${opencode.module}`),
+      ],
+    })
+    recipes.opencode = { project: at('project'), user: at('user') }
+    detect.opencode = (p) => p.opencodePlugin(opencode.module)
+  }
+  if (antigravity) {
+    // agy plugin install에도 범위 플래그가 없다 — ~/.gemini 아래 전역에 깔린다.
+    recipes.antigravity = {
+      user: {
+        install: [['agy', 'plugin', 'install', antigravity.source]],
+        uninstall: [['agy', 'plugin', 'uninstall', antigravity.name]],
+      },
+    }
+    detect.antigravity = (p) => p.agyPlugin(antigravity.name)
+  }
+  return { recipes, detect }
+}
+
+export function mcpServer({ name, server, clis = ['claude', 'codex', 'opencode', 'antigravity'] }) {
+  const http = server.kind === 'http'
+  // stdio 명령 앞의 `--`: 인자가 `-y`처럼 대시로 시작해도 CLI가 자기 플래그로 읽지 않는다.
+  const tail = http ? [] : ['--', server.command, ...server.args]
+  const entry = http
+    ? { type: 'remote', url: server.url, enabled: true }
+    : { type: 'local', command: [server.command, ...server.args], enabled: true }
+  const opencodeAt = (scope) => ({
+    install: [
+      ['opencode', 'run', opencodePrompt(scope, `Under the top-level 'mcp' object (create it, and the file with '$schema': 'https://opencode.ai/config.json', if missing) set the key '${name}' to this value: ${quotedJson(entry)}.`)],
+      verifyOpencode(scope, (d) => d?.mcp?.[name] !== undefined, `check ${fileName(scope)} has mcp.${name}`),
+    ],
+    uninstall: [
+      ['opencode', 'run', opencodePrompt(scope, `Delete the key '${name}' from the top-level 'mcp' object.`)],
+      verifyOpencode(scope, (d) => d?.mcp?.[name] === undefined, `check ${fileName(scope)} no longer has mcp.${name}`),
+    ],
+  })
+  const claudeAt = (scope) => ({
+    install: [http ? ['claude', 'mcp', 'add', '-s', scope, '-t', 'http', name, server.url] : ['claude', 'mcp', 'add', '-s', scope, name, ...tail]],
+    uninstall: [['claude', 'mcp', 'remove', '-s', scope, name]],
+  })
+  const all = {
+    claude: { project: claudeAt('project'), user: claudeAt('user') },
+    // Codex·Antigravity의 mcp add에는 범위 플래그가 없다 — 사용자 전역 설정에 쓴다.
+    codex: {
+      user: {
+        install: http
+          ? [{ argv: ['codex', 'mcp', 'add', name, '--url', server.url], tolerateFail: true, timeout: CODEX_LOGIN_WAIT_MS }, verifyCodexMcp(name)]
+          : [['codex', 'mcp', 'add', name, ...tail]],
+        uninstall: [['codex', 'mcp', 'remove', name]],
+      },
+    },
+    opencode: { project: opencodeAt('project'), user: opencodeAt('user') },
+    antigravity: { user: { install: [http ? ['agy', 'mcp', 'add', name, server.url] : ['agy', 'mcp', 'add', name, ...tail]], uninstall: [['agy', 'mcp', 'remove', name]] } },
+  }
+  const recipes = Object.fromEntries(clis.map((c) => [c, all[c]]))
+  const detect = Object.fromEntries(clis.map((c) => [c, (p) => p.mcp(c, name)]))
+  return { recipes, detect }
+}
+
+// 레지스트리의 remove는 --agent universal에서 "Done!"을 찍고도 디렉터리와
+// 잠금 항목을 남긴다(실측) — 남은 것을 우리가 치운다. 남겨 두면 detect가
+// 계속 설치됨으로 읽고, 동료가 잠금 파일로 복원하면 지운 스킬이 되살아난다.
+// 잠금 항목은 lockNames 전부를 지운다 — 인자·경로로 못 써 건너뛴 이름까지.
+// 남기면 다음 제거가 같은 자리에서 또 멈춘다.
+function cleanup(root, names, lockNames = names) {
+  for (const name of names) {
+    const dir = findSkillDir(root, name)
+    if (dir) rmSync(repoPathStrict(root, `${SHARED_SKILLS}/${dir}`), { recursive: true, force: true })
+  }
+  pruneLock(root, lockNames)
+}
+
+export function skillsAdd({ source, skill, anchor = null }) {
+  const wildcard = skill === '*'
+  // 스킬 전부(*)를 넣으면 detect가 볼 이름을 정해 둬야 한다 — 없으면 설치해도
+  // 계속 absent로 읽히는 항목이 조용히 카탈로그에 들어간다.
+  if (wildcard && !anchor) throw new LocalizedError('error.registrySkillAnchor', { id: sourceKey(source) })
+  const probeName = anchor ?? skill
+  const project = {
+    install: [[...SKILLS, 'add', source, '--skill', skill, '--agent', 'universal', '--yes', '--copy']],
+    uninstall: wildcard
+      ? [{
+          describe: `npx -y skills@latest remove <each skill from ${sourceKey(source)} in skills-lock.json> --agent universal --yes, then remove leftover ${SHARED_SKILLS} dirs`,
+          fn: async ({ root, exec }) => {
+            // 잠금 파일의 이름은 상류 frontmatter에서 온다 — 인자·경로로 못 쓰는 이름은 건너뛴다.
+            const locked = lockedSkills(root, source)
+            const all = locked.length > 0 ? locked : [probeName]
+            const names = all.filter(isSafeSkillName)
+            for (const name of names) await exec('npx', ['-y', 'skills@latest', 'remove', name, '--agent', 'universal', '--yes'], { cwd: root })
+            cleanup(root, names, all)
+          },
+        }]
+      : [
+          { argv: [...SKILLS, 'remove', skill, '--agent', 'universal', '--yes'], tolerateFail: true },
+          { describe: `remove leftover ${SHARED_SKILLS}/${skill} and its skills-lock.json entry`, fn: ({ root }) => cleanup(root, [skill]) },
+        ],
+  }
+  const byScope = { project }
+  // 한 상류의 스킬 전부(*)는 전역에서 무엇을 지울지 추적할 근거가 없다.
+  if (!wildcard) {
+    byScope.user = {
+      install: [[...SKILLS, 'add', source, '--skill', skill, '-g', '-a', ...SKILLS_AGENTS, '--yes', '--copy']],
+      uninstall: [[...SKILLS, 'remove', skill, '-g', '-a', ...SKILLS_AGENTS, '--yes']],
+    }
+  }
+  return { recipes: { [SHARED]: byScope }, detect: { [SHARED]: (p) => p.skill(probeName) } }
+}

package/lib/recipe.mjs

@@ -0,0 +1,181 @@
+// 레시피 = CLI·범위별 설치 명령 목록. 항목 파일은 데이터만 적고, 이 모듈이
+// 그것을 엔진·TUI가 아는 항목 모양으로 바꾼다. 실행(install)과 출력(--print)이
+// 같은 steps()에서 명령을 얻으므로 둘이 어긋날 수 없다.
+import { join } from 'node:path'
+import { CLIS, CLI_IDS as RECIPE_CLIS } from './clis.mjs'
+import { LocalizedError, msg } from './i18n/index.mjs'
+
+export const SCOPES = ['project', 'user']
+// 한 단계 묶음이 네 CLI를 한꺼번에 덮는 자리(.agents/skills).
+export const SHARED = 'shared'
+// 실패 보고에 싣는 출력 줄 수. 설치 로그 전체는 화면을 덮는다.
+const TAIL_LINES = 5
+
+export function normalizeStep(step, cli) {
+  if (Array.isArray(step)) return { cli, argv: step, cwd: null, tolerateFail: false, undo: null, timeout: null }
+  if (step && Array.isArray(step.argv)) {
+    return { cli, argv: step.argv, cwd: step.cwd ?? null, tolerateFail: Boolean(step.tolerateFail), undo: step.undo ?? null, timeout: step.timeout ?? null }
+  }
+  if (step && typeof step.fn === 'function' && step.describe) return { cli, fn: step.fn, describe: String(step.describe) }
+  return null
+}
+
+function assertRecipe(def) {
+  const bad = (why) => { throw new LocalizedError('error.recipeInvalid', { id: def?.id ?? '?', why }) }
+  for (const field of ['id', 'category', 'label']) if (!def?.[field]) bad(`missing ${field}`)
+  const entries = Object.entries(def.recipes ?? {})
+  if (entries.length === 0) bad('no recipes')
+  if (def.recipes[SHARED] && entries.length > 1) bad('shared cannot be combined with per-CLI recipes')
+  for (const [cli, byScope] of entries) {
+    if (cli !== SHARED && !RECIPE_CLIS.includes(cli)) bad(`unknown CLI ${cli}`)
+    for (const [scope, recipe] of Object.entries(byScope)) {
+      if (!SCOPES.includes(scope)) bad(`unknown scope ${scope}`)
+      for (const action of ['install', 'uninstall']) {
+        if (!Array.isArray(recipe?.[action])) bad(`${cli}.${scope}.${action} is not a list`)
+        for (const raw of recipe[action]) {
+          const step = normalizeStep(raw, cli)
+          if (!step || (step.argv && (step.argv.length === 0 || !step.argv.every((a) => typeof a === 'string')))) {
+            bad(`${cli}.${scope}.${action} has a bad step`)
+          }
+        }
+      }
+    }
+    if (typeof def.detect?.[cli] !== 'function') bad(`detect.${cli} missing`)
+  }
+}
+
+export function defineRecipe(def) {
+  assertRecipe(def)
+  return { ...def, kind: 'recipe' }
+}
+
+const reasonOf = (r) => (typeof r === 'string' ? msg(r) : r)
+
+export function bindScope(def, scope) {
+  const shared = def.recipes[SHARED]
+  if (shared && !shared[scope]) return null
+  const supports = shared ? [...RECIPE_CLIS] : RECIPE_CLIS.filter((c) => def.recipes[c]?.[scope])
+  if (supports.length === 0) return null
+
+  // 다른 범위엔 레시피가 있으면 "범위를 바꾸면 된다"가 사유다. 어느 범위에도
+  // 없을 때만 항목이 사유를 직접 대야 한다 — 빠뜨리면 로드 오류로 막는다.
+  const other = scope === 'project' ? 'user' : 'project'
+  const unsupported = {}
+  for (const cli of RECIPE_CLIS) {
+    if (supports.includes(cli)) continue
+    if (def.recipes[cli]?.[other]) unsupported[cli] = msg(`item.unsupported.${other}Only`)
+    else if (def.reasons?.[cli]) unsupported[cli] = reasonOf(def.reasons[cli])
+    else throw new LocalizedError('error.itemReasonMissing', { id: def.id, cli })
+  }
+
+  const recipeOf = (cli) => def.recipes[cli][scope]
+
+  return {
+    id: def.id, category: def.category, label: def.label,
+    group: def.group ?? null, exclusive: def.exclusive ?? null, note: def.note ?? null,
+    verified: def.verified ?? null, hooks: Boolean(def.hooks), postInstall: def.postInstall ?? null,
+    scope, supports, unsupported,
+
+    async detect({ probe }) {
+      const reach = supports.filter((c) => probe.has(c))
+      // 공유 스킬은 CLI가 아니라 디렉터리에 깔린다 — PATH와 무관하다.
+      const excluded = shared ? [] : supports.filter((c) => !reach.includes(c))
+      const targets = shared ? [SHARED] : reach
+      const present = []
+      const failed = []
+      for (const cli of targets) {
+        try {
+          if (await def.detect[cli](probe)) present.push(cli)
+        } catch {
+          // 목록 명령 실패(로그인 만료 등)를 "없음"으로 읽으면 깔린 것을 또 깐다.
+          failed.push(cli)
+        }
+      }
+      const live = targets.filter((c) => !failed.includes(c))
+      const status = present.length === 0 ? 'absent' : present.length === live.length ? 'installed' : 'partial'
+      let detail = null
+      if (failed.length > 0) detail = msg('item.probeFailed', { list: failed.join(', ') })
+      else if (status === 'partial') {
+        detail = msg('item.plugin.partial', { present: present.join(', '), missing: live.filter((c) => !present.includes(c)).join(', ') })
+      } else if (targets.length === 0) detail = msg('item.global.noCli', { list: excluded.join(', ') })
+      return { status, detail, excluded, present, failed, targets, reach }
+    },
+
+    steps(action, state = {}) {
+      const present = state.present ?? []
+      const failed = state.failed ?? []
+      const targets = state.targets ?? (shared ? [SHARED] : supports)
+      const removing = action === 'uninstall'
+      const clis = removing
+        ? targets.filter((c) => present.includes(c))
+        : targets.filter((c) => !present.includes(c) && !failed.includes(c))
+      return clis.flatMap((cli) => recipeOf(cli)[removing ? 'uninstall' : 'install'].map((s) => normalizeStep(s, cli)))
+    },
+
+    async install(ctx) {
+      const state = ctx.state ?? {}
+      const steps = this.steps('install', state)
+      // 실행할 명령이 없는데 ✔로 끝나면 --set을 쓰는 CI가 무동작을 성공으로 받는다.
+      // 감지 실패는 실패로, CLI가 이 머신에 없는 것은 사연 있는 성공으로 돌려준다.
+      if (steps.length === 0) {
+        const failed = state.failed ?? []
+        const excluded = state.excluded ?? []
+        if (failed.length > 0) throw new LocalizedError('item.probeFailed', { list: failed.join(', ') })
+        if (excluded.length > 0) return { message: msg('item.global.noCli', { list: excluded.join(', ') }) }
+        return undefined
+      }
+      await runSteps(steps, ctx)
+      return undefined
+    },
+
+    async uninstall(ctx) {
+      await runSteps(this.steps('uninstall', ctx.state), ctx)
+    },
+  }
+}
+
+function tail(output) {
+  return String(output ?? '').trim().split(/\r?\n/).slice(-TAIL_LINES).join('\n    ')
+}
+
+const cliLabel = (cli) => CLIS[cli]?.label ?? cli
+
+// 한 CLI의 단계가 실패하면 그 CLI의 남은 단계만 건너뛴다. 다른 CLI는 계속
+// 간다 — 로그인이 풀린 Codex 하나 때문에 Claude 설치까지 막을 이유가 없다.
+export async function runSteps(steps, ctx) {
+  const { root, exec, dryRun = false, log = () => {} } = ctx
+  const broken = new Set()
+  // 참아 준 실패(마켓플레이스 "이미 등록됨")는 뒤 단계가 실패할 때만 함께 보인다.
+  const soft = new Map()
+  const failures = []
+  for (const step of steps) {
+    if (broken.has(step.cli)) continue
+    if (step.fn) {
+      if (dryRun) { log(`  [dry-run] ${step.describe}`); continue }
+      try {
+        await step.fn(ctx)
+      } catch (err) {
+        failures.push({ cli: step.cli, what: step.describe, output: err.message })
+        broken.add(step.cli)
+      }
+      continue
+    }
+    const [cmd, ...args] = step.argv
+    const opts = { cwd: step.cwd ? join(root, step.cwd) : root }
+    if (step.timeout) opts.timeout = step.timeout
+    const r = await exec(cmd, args, opts)
+    if (r.ok) continue
+    const failure = { cli: step.cli, what: step.argv.join(' '), output: tail(r.output) }
+    if (step.tolerateFail) { soft.set(step.cli, failure); continue }
+    if (step.undo && !dryRun) {
+      try { await step.undo(ctx) } catch { /* 되돌리기 실패가 원래 실패를 가리면 안 된다 */ }
+    }
+    if (soft.has(step.cli)) failures.push(soft.get(step.cli))
+    failures.push(failure)
+    broken.add(step.cli)
+  }
+  if (failures.length > 0) {
+    const details = failures.map((f) => `  ${cliLabel(f.cli)}: ${f.what}${f.output ? `\n    ${f.output}` : ''}`).join('\n')
+    throw new LocalizedError('error.stepsFailed', { details })
+  }
+}

package/lib/skills-registry.mjs

@@ -0,0 +1,93 @@
+// 공유 스킬 디렉터리(.agents/skills)와 레지스트리 잠금 파일을 읽고 정리하는
+// 보조 함수. 감지(probe)와 레지스트리 스킬 레시피가 함께 쓴다.
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { repoPath, repoPathStrict } from './context.mjs'
+import { escapeRegExp, isSafeSegment } from './untrusted.mjs'
+
+// 이 저장소가 공유 스킬 자리로 쓰는 디렉터리. vercel-labs/skills 레지스트리의
+// `--agent universal` 프로젝트 경로와 같은 값이다 — 그래서 레지스트리 설치가
+// 우리 배선 위에 그대로 얹힌다.
+export const SHARED_SKILLS = '.agents/skills'
+
+function skillDirs(root) {
+  const dir = repoPath(root, SHARED_SKILLS)
+  if (!existsSync(dir)) return []
+  return readdirSync(dir).filter((name) => {
+    try {
+      return statSync(join(dir, name)).isDirectory()
+    } catch {
+      return false
+    }
+  })
+}
+
+// 설치된 디렉터리 이름이 스킬 이름과 다를 수 있다(레지스트리는 SKILL.md의
+// frontmatter name으로 고르는데, 저장소의 폴더 이름은 다른 경우가 있다 —
+// taste-skill/이 design-taste-frontend를 담는 식이다). 이름이 같은 디렉터리를
+// 먼저 보고, 없으면 frontmatter를 읽어 찾는다. 디렉터리 이름만 보면 설치해
+// 놓고도 계속 '미설치'로 읽힌다.
+export function findSkillDir(root, skill) {
+  const base = repoPath(root, SHARED_SKILLS)
+  if (existsSync(join(base, skill, 'SKILL.md'))) return skill
+  for (const name of skillDirs(root)) {
+    const file = join(base, name, 'SKILL.md')
+    if (!existsSync(file)) continue
+    const head = readFileSync(file, 'utf8').slice(0, 2000)
+    if (new RegExp(`^name:\\s*['"]?${escapeRegExp(skill)}['"]?\\s*$`, 'm').test(head)) return name
+  }
+  return null
+}
+
+// 잠금 파일의 이름은 상류 SKILL.md frontmatter에서 온다 — 신뢰 경계 밖이다.
+// `npx skills remove <이름>`의 인자이자 `.agents/skills/<이름>` 경로가 되므로,
+// 플래그로 읽히는 선행 대시와 경로 구분자·상위 이동은 어느 쪽으로도 쓸 수 없다.
+export function isSafeSkillName(name) {
+  return isSafeSegment(name) && !name.startsWith('-')
+}
+
+// 레지스트리가 저장소 루트에 남기는 잠금 파일. 스킬 이름마다 어느 출처에서
+// 왔는지를 적어 두므로, 한 상류가 여러 스킬을 깔았을 때 "우리가 넣은 것"만
+// 골라 지울 수 있는 유일한 근거다.
+export const SKILLS_LOCK = 'skills-lock.json'
+
+// 잠금 파일의 source는 `owner/repo`로 정규화돼 있고 항목은 URL을 넘긴다.
+export 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
+  }
+}
+
+export 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로
+// 복원하면 지운 스킬이 되살아난다.
+export 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`)
+}

package/lib/status.mjs

@@ -7,6 +7,8 @@ import { MANIFEST } from './bootstrap/manifest.mjs'
 import { updateBlocks, updateFiles } from './bootstrap/apply.mjs'
 import { readRecord, toolVersion } from './bootstrap/record.mjs'
 import { createT } from './i18n/index.mjs'
+import { makeExec } from './catalog.mjs'
+import { createProbe } from './probe.mjs'
 
 // 미배선 사유는 상류를 실측한 날의 사실이다. 그 날짜(item.verified)가 이보다
 // 오래되면 status가 알린다 — 사유 문장이 화면에 낡은 채 남는 것을 막는 유일한
@@ -18,7 +20,7 @@ function daysSince(iso, now) {
   return Number.isFinite(ms) ? Math.floor(ms / 86_400_000) : 0
 }
 
-export async function collectStatus(root, { manifest = MANIFEST, items = [], latest, now = Date.now() } = {}) {
+export async function collectStatus(root, { manifest = MANIFEST, items = [], latest, now = Date.now(), probe = null } = {}) {
   const record = readRecord(root)
 
   // dry-run으로 갱신 판정만 얻는다 — 판정 로직을 두 벌 두면 status와 update가
@@ -33,10 +35,12 @@ export async function collectStatus(root, { manifest = MANIFEST, items = [], lat
 
   const count = (action) => verdicts.filter((v) => v.action === action).length
 
+  // 화면·--list와 같은 감지 경로 — 레시피 항목은 CLI 목록 캐시(probe)를 읽는다.
+  const shared = probe ?? createProbe({ root, scope: 'project', exec: makeExec(false) })
   const states = []
   for (const item of items) {
     try {
-      const r = await item.detect({ root })
+      const r = await item.detect({ root, probe: shared })
       states.push({ id: item.id, status: r.status })
     } catch {
       // 감지 실패로 status 전체가 죽으면 진단 도구가 아니다.
@@ -123,7 +127,7 @@ export async function fetchLatestVersion(fetchImpl = fetch) {
 
 export async function runStatus(root, { json = false, log = console.log, fetchImpl = fetch, t = createT('en') } = {}) {
   const { loadItems } = await import('./catalog.mjs')
-  const report = await collectStatus(root, { items: await loadItems(), latest: await fetchLatestVersion(fetchImpl) })
+  const report = await collectStatus(root, { items: await loadItems({ scope: 'project' }), latest: await fetchLatestVersion(fetchImpl) })
   log(json ? JSON.stringify(report, null, 2) : formatStatus(report, t))
   return report
 }