@qualisoft/ai-skills 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# 변경 이력
+
+## 1.1.0 — 2026-09-11
+
+설치 위치와 소유 판정을 고쳤습니다. **1.0.0 사용자는 전원 재설치가 필요합니다.**
+
+```bash
+npx @qualisoft/ai-skills@latest install --force
+```
+
+> 직접 고친 스킬이 있으면 `--force` 가 그 디렉터리를 지웁니다. 먼저 백업하세요.
+
+### 고친 것
+
+**① npx 캐시를 직접 가리키던 문제** — 모든 플랫폼 해당
+
+`npx @qualisoft/ai-skills install` 이 만드는 링크가 npx 캐시(`_npx/<해시>/`)를
+가리켰습니다. 그 캐시는 정리 대상이라, 비워지는 순간 스킬 전체가 죽은 링크가
+됩니다. README 첫 줄 명령이 이 상태를 만들고 있었습니다.
+
+이제 임시 위치(npx 캐시 · `node_modules`)에서 실행되면 **먼저
+`~/.ai-skills/qualisoft/` 로 복사하고 도구들은 그곳을 가리킵니다.** 캐시가
+정리돼도 스킬은 살아 있습니다.
+
+저장소를 클론해 개발할 때는 `--direct` 로 저장소를 직접 가리킵니다 — 고친
+내용이 즉시 반영되는 기존 동작 그대로입니다.
+
+**② 복사 설치의 소유 판정** — Windows 해당
+
+`isOurs()` 가 `realpath` 비교뿐이라 복사본은 항상 "남의 것"으로 판정됐습니다.
+Windows 는 심볼릭 링크에 관리자 권한이 필요해 복사가 기본이므로, 이 때문에
+
+- `uninstall` 이 자기 설치본조차 지우지 못하고 (전부 "건너뜀")
+- 재설치·업그레이드마다 `--force` 가 필요하고
+- `--force` 는 `rmSync` 하므로 직접 수정한 내용이 날아갔습니다
+
+복사본에 `.qualisoft-ai-skills.json` 표식을 남겨 판정합니다. 이제 Windows 도
+링크 환경과 동일하게 동작합니다.
+
+### 곁들여 고친 것
+
+- **죽은 링크도 소유로 인정합니다.** 그러지 않으면 캐시가 정리된 뒤
+  `uninstall` 이 자기 링크를 못 지웁니다. 1.0.0 설치본도 정리됩니다
+- `symlink` 이 `EPERM`·`EACCES` 로 막히면 예외로 죽지 않고 **복사로
+  내려갑니다**
+- `cursor` 자동 탐지가 `~/.cursor/rules` 를 보고 있었습니다. 그 폴더는 없을 수
+  있어 `~/.cursor` 를 봅니다
+- `uninstall` 이 빈 정본 폴더를 남기지 않습니다
+- `status` 가 `link` / `copy` / `other` 를 구분하고 설치된 버전을 함께
+  보여줍니다
+
+### 검증
+
+| 시나리오 | 결과 |
+| --- | --- |
+| npx 캐시에서 설치 → 캐시 전체 삭제 | 스킬 동작, `selftest` 통과 |
+| Windows 조건(복사 + 캐시 삭제) | 동작, `uninstall` 5개 제거 |
+| 죽은 링크 정리 | 제거 |
+| `--direct` (개발 모드) | 저장소 직접 링크 |
+| 링크 모드 회귀 | 연결 5 / 이미 연결 5 / 제거 5 / 잔여 0 |
+| 사용자가 직접 만든 스킬 | 건너뜀, 내용 보존 |
+| `--dry-run` | 아무것도 쓰지 않음 |
+| 실제 tarball 설치 | 정본 경유 확인 |
+
+**보고** — Windows `uninstall` 문제는 팀 내부 검토에서 제기되었습니다. 원인
+분석(`realpath` 비교 → 복사본 판정 불가)과 해결 방향(표식 기반 판정)이 정확했고,
+그 실마리를 따라가 ① 을 함께 찾았습니다.
+
+---
+
+## 1.0.0 — 2026-09-11
+
+최초 공개. 스킬 5종 (`project-interview` · `project-init` · `project-design` ·
+`project-build` · `erd-visual`), 도구별 설치기, 외부 의존성 없음.

package/README.md

@@ -63,11 +63,24 @@ npx @qualisoft/ai-skills list        # 스킬 설명 전문
 npx @qualisoft/ai-skills install --dry-run   # 바뀔 것만 미리 본다
 npx @qualisoft/ai-skills install --copy      # 링크 대신 복사 (Windows 기본)
 npx @qualisoft/ai-skills install --force     # 같은 이름 디렉터리를 덮어쓴다
+npx @qualisoft/ai-skills install --direct   # 저장소를 직접 가리킨다 (개발용)
 npx @qualisoft/ai-skills uninstall
 ```
 
 **같은 이름의 스킬이 이미 있으면 건너뜁니다.** 직접 고쳐 쓰던 스킬을 지우지 않기 위해서입니다. 바꿀 생각이면 백업하고 `--force`를 붙이세요.
 
+### Windows
+
+심볼릭 링크에 관리자 권한이 필요해 **복사로 자동 전환**됩니다(`--copy`가 기본). 복사본에는 `.qualisoft-ai-skills.json` 표식이 들어가고, 이걸로 소유를 판정합니다. 그래서 링크 환경과 똑같이 동작합니다 — 재설치는 `--force` 없이 갱신되고, `uninstall`도 정상 제거됩니다.
+
+> **1.0.0으로 설치하신 분은 다시 설치해 주세요.** 그 버전은 npx 캐시를 직접 가리켜서, 캐시가 정리되면 스킬이 죽은 링크로 남습니다. 표식도 없어 `uninstall` 이 자기 설치본을 알아보지 못합니다.
+>
+> ```bash
+> npx @qualisoft/ai-skills@latest install --force
+> ```
+>
+> 직접 고친 내용이 있으면 `--force` 가 그 디렉터리를 지우므로 먼저 백업하세요.
+
 ---
 
 ## 어떻게 세 도구에서 다 되나
@@ -75,14 +88,19 @@ npx @qualisoft/ai-skills uninstall
 스킬의 실체는 **마크다운 지시문 + Node 스크립트**입니다. 도구마다 다른 것은 실행 방식이 아니라 **스킬을 발견하는 방식**뿐입니다. 그래서 설치기가 하는 일도 그 하나입니다.
 
 ```
-Claude Code · Codex          스킬 디렉터리를 직접 읽는다  →  심볼릭 링크만 걸면 끝
-                             ~/.claude/skills/<이름>/SKILL.md
-
-Gemini · Cursor · 그 외       스킬 개념이 없다  →  공용 위치에 두고
-                             ~/.ai-skills/qualisoft/     지시문 파일에 목록을 적는다
-                             + GEMINI.md / AGENTS.md
+①  정본을 안정된 곳에 둔다
+    ~/.ai-skills/qualisoft/<이름>/
+    npx 캐시·node_modules 는 정리 대상이라 그 자리를 직접 가리키면
+    캐시가 비워질 때 스킬이 통째로 죽는다. 그래서 먼저 여기로 복사한다.
+
+②  도구가 보는 곳에서 정본을 가리킨다
+    Claude Code · Codex   ~/.claude/skills/<이름>  →  링크 (Windows 는 복사)
+    Gemini · Cursor · 그 외  정본 경로를 지시문에 적는다
+                          GEMINI.md / .cursor/rules / AGENTS.md
 ```
 
+저장소를 클론해 개발할 때는 `--direct` 를 붙입니다. 복사를 건너뛰고 저장소를 직접 가리켜서, 고친 내용이 곧바로 반영됩니다.
+
 주입되는 블록은 표식으로 감싸여 있어(`<!-- qualisoft-ai-skills:begin -->`) **기존 지시문을 건드리지 않고** 그 부분만 갈아끼웁니다. `uninstall`은 블록만 빼고 나머지는 남깁니다.
 
 > **경로 정확도** — `claude` · `codex` · `agents`는 실제로 확인한 경로입니다. `gemini` · `cursor`는 각 도구 문서를 근거로 넣었고 버전에 따라 다를 수 있습니다. 어긋나면 `bin/cli.mjs` 상단 `TARGETS` 한 곳만 고치면 됩니다.
@@ -193,12 +211,12 @@ Claude Code · Codex 에서는 `/project-init` 처럼 직접 호출할 수도
 
 ## 직접 고쳐 쓰기
 
-설치는 **심볼릭 링크**입니다. 저장소의 `skills/`를 고치면 모든 도구에 즉시 반영됩니다.
+`--direct` 로 설치하면 도구들이 저장소의 `skills/` 를 직접 가리킵니다. 고치면 즉시 반영됩니다.
 
 ```bash
 git clone https://github.com/qualisoft-service/project-ai-skills
 cd project-ai-skills
-node bin/cli.mjs install --tool=all --force
+node bin/cli.mjs install --tool=all --direct --force
 
 # skills/project-init/modules/*.json 을 고치면 곧바로 적용된다
 node skills/project-init/build.mjs selftest
@@ -219,7 +237,18 @@ node skills/project-init/build.mjs selftest
 ## 요구 사항
 
 - **Node.js 18 이상** (`node -v`로 확인)
-- macOS · Linux · Windows. Windows는 링크 대신 복사로 자동 전환됩니다
+- macOS · Linux · Windows. Windows는 링크 대신 복사로 자동 전환되며, 기능 차이는 없습니다
+
+## 변경 이력
+
+버전별 변경 내용은 [CHANGELOG.md](./CHANGELOG.md) 에 있습니다.
+
+**1.0.0 을 쓰고 계시면 재설치가 필요합니다** — 그 버전은 npx 캐시를 직접
+가리켜서, 캐시가 정리되면 스킬이 죽은 링크로 남습니다.
+
+```bash
+npx @qualisoft/ai-skills@latest install --force
+```
 
 ## 저장소 · 문의
 

package/bin/cli.mjs

@@ -8,19 +8,42 @@
  */
 import {
   existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync,
-  lstatSync, rmSync, symlinkSync, cpSync, realpathSync,
+  lstatSync, rmSync, symlinkSync, cpSync, realpathSync, readlinkSync,
 } from "node:fs";
 import { homedir, platform } from "node:os";
-import { join, dirname, resolve } from "node:path";
+import { basename, join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const SKILLS_DIR = join(PKG_ROOT, "skills");
 const HOME = homedir();
+const VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8")).version;
+  } catch {
+    return "unknown";
+  }
+})();
+
+/* 스킬의 안정된 보관 위치.
+ *
+ * npx 는 패키지를 캐시(`_npx/<해시>/`)에 풀고, 그 캐시는 정리 대상이다.
+ * 거기를 직접 링크하면 캐시가 비워지는 순간 모든 스킬이 죽은 링크가 된다.
+ * 그래서 임시 위치에서 실행됐을 때는 먼저 여기로 복사해 두고, 도구들은
+ * 이 경로를 가리키게 한다. */
+const STORE = join(HOME, ".ai-skills", "qualisoft");
+
+/** 패키지가 사라질 수 있는 위치에 있는가 (npx 캐시 · node_modules). */
+function isTransient(dir) {
+  return /[/\\](?:node_modules|_npx)[/\\]/.test(dir + "/");
+}
 
 /* ── 설치 대상 ──────────────────────────────────────────────────────
  * mode: "native" — 도구가 스킬 디렉터리를 직접 읽는다. 링크만 걸면 끝.
- * mode: "inject" — 스킬 개념이 없는 도구. 공용 위치에 두고 지시문에 목록을 적는다.
+ * mode: "inject" — 스킬 개념이 없는 도구. 정본 위치를 지시문에 적는다.
+ *
+ * dir: null 인 대상은 스킬을 따로 놓지 않고 정본(SOURCE)을 그대로 가리킨다.
+ * detect 는 자동 탐지에 쓰는 "이 도구가 설치되어 있나" 경로다.
  *
  * 경로가 바뀌면 여기만 고친다. verified 는 실제로 확인한 경로인지를 뜻한다. */
 const TARGETS = [
@@ -29,6 +52,7 @@ const TARGETS = [
     label: "Claude Code",
     mode: "native",
     dir: join(HOME, ".claude", "skills"),
+    detect: join(HOME, ".claude"),
     verified: true,
   },
   {
@@ -36,30 +60,34 @@ const TARGETS = [
     label: "Codex CLI",
     mode: "native",
     dir: join(HOME, ".codex", "skills"),
+    detect: join(HOME, ".codex"),
     verified: true,
   },
   {
     id: "gemini",
     label: "Gemini CLI",
     mode: "inject",
-    dir: join(HOME, ".ai-skills", "qualisoft"),
+    dir: null,
     instructions: join(HOME, ".gemini", "GEMINI.md"),
+    detect: join(HOME, ".gemini"),
     verified: false,
   },
   {
     id: "cursor",
     label: "Cursor",
     mode: "inject",
-    dir: join(HOME, ".ai-skills", "qualisoft"),
+    dir: null,
     instructions: join(HOME, ".cursor", "rules", "qualisoft-ai-skills.mdc"),
+    detect: join(HOME, ".cursor"),
     verified: false,
   },
   {
     id: "agents",
     label: "AGENTS.md (범용)",
     mode: "inject",
-    dir: join(HOME, ".ai-skills", "qualisoft"),
+    dir: null,
     instructions: resolve("AGENTS.md"),
+    detect: null,
     verified: true,
   },
 ];
@@ -94,31 +122,101 @@ function allSkills() {
 
 /* ── 설치 ─────────────────────────────────────────────────────── */
 
-/** 이미 우리 스킬을 가리키는 링크인가. 남의 디렉터리를 지우지 않기 위한 확인. */
+/* 복사로 설치한 스킬에 남기는 표식.
+ *
+ * 링크 설치는 realpath 비교로 소유를 알 수 있지만 복사본은 알 수 없다.
+ * Windows 는 심볼릭 링크에 권한이 필요해 복사가 기본이므로, 표식이 없으면
+ * uninstall 이 자기가 놓은 것조차 지우지 못한다. */
+const STAMP = ".qualisoft-ai-skills.json";
+
+function writeStamp(dest, skillName, version) {
+  writeFileSync(
+    join(dest, STAMP),
+    JSON.stringify({ package: "@qualisoft/ai-skills", version, skill: skillName,
+                     mode: "copy", installedAt: new Date().toISOString() }, null, 2) + "\n",
+    "utf8",
+  );
+}
+
+function readStamp(dest) {
+  try {
+    const j = JSON.parse(readFileSync(join(dest, STAMP), "utf8"));
+    return j.package === "@qualisoft/ai-skills" ? j : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 이 경로가 우리가 놓은 것인가. 남의 디렉터리를 지우지 않기 위한 확인.
+ *
+ * 두 설치 방식을 모두 본다 — 링크는 realpath 로, 복사는 표식 파일로.
+ * 둘 중 하나라도 맞으면 우리 것이다.
+ */
 function isOurs(path, src) {
   try {
-    return realpathSync(path) === realpathSync(src);
+    if (realpathSync(path) === realpathSync(src)) return true;
+  } catch {
+    /* 링크가 깨졌거나 경로가 없다 — 아래에서 다시 본다 */
+  }
+  if (readStamp(path)) return true;
+  // 죽은 링크: 대상이 사라져 realpath 가 실패한다. 가리키던 경로로 판정한다.
+  // 이걸 놓치면 npx 캐시가 정리된 뒤 uninstall 이 자기 링크를 못 지운다.
+  try {
+    if (lstatSync(path).isSymbolicLink()) {
+      const t = readlinkSync(path);
+      return t.includes("@qualisoft/ai-skills") || t.startsWith(STORE) ||
+             t.startsWith(SKILLS_DIR);
+    }
   } catch {
-    return false;
+    /* 판정 불가 */
   }
+  return false;
 }
 
-function place(src, dest, useCopy, force) {
+function place(src, dest, useCopy, force, version) {
   const st = lstatSync(dest, { throwIfNoEntry: false });
   if (st) {
-    if (!useCopy && isOurs(dest, src)) return "이미 연결됨";
-    // 남이 놓은 실디렉터리는 지우지 않는다. 사용자의 수정이 들어 있을 수 있다.
-    if (st.isDirectory() && !st.isSymbolicLink() && !force) {
-      return "건너뜀 — 기존 디렉터리가 있습니다 (--force 로 덮어씀)";
+    const ours = isOurs(dest, src);
+    if (ours && !useCopy && st.isSymbolicLink()) return "이미 연결됨";
+    // 우리가 놓은 것은 힘 주지 않아도 갱신한다. 그래야 업그레이드가 된다.
+    if (!ours && st.isDirectory() && !st.isSymbolicLink() && !force) {
+      return "건너뜀 — 우리 표식이 없는 디렉터리입니다 (--force 로 덮어씀)";
     }
     rmSync(dest, { recursive: true, force: true });
   }
-  if (useCopy) {
-    cpSync(src, dest, { recursive: true });
-    return "복사";
+  if (!useCopy) {
+    try {
+      symlinkSync(src, dest, "dir");
+      return "연결";
+    } catch (e) {
+      // Windows 외에도 권한·파일시스템 때문에 링크가 막힐 수 있다. 복사로 내려간다.
+      if (!["EPERM", "EACCES", "ENOSYS", "EEXIST"].includes(e.code)) throw e;
+    }
+  }
+  cpSync(src, dest, { recursive: true });
+  writeStamp(dest, basename(dest), version);
+  return useCopy ? "복사" : "복사 (링크 불가)";
+}
+
+/**
+ * 도구들이 가리킬 정본 위치를 정한다.
+ *
+ * npx 캐시나 node_modules 에서 실행됐으면 그 경로는 사라질 수 있으므로
+ * STORE 로 복사해 두고 그곳을 정본으로 쓴다. 저장소를 직접 클론해
+ * 쓰는 경우(개발)에는 고친 내용이 바로 반영되도록 패키지를 그대로 쓴다.
+ */
+function resolveSource(skills, { direct, dryRun }) {
+  if (direct || !isTransient(PKG_ROOT)) return { dir: SKILLS_DIR, staged: false };
+  if (dryRun) return { dir: STORE, staged: true };
+  mkdirSync(STORE, { recursive: true });
+  for (const s of skills) {
+    const dest = join(STORE, s.name);
+    rmSync(dest, { recursive: true, force: true });
+    cpSync(join(SKILLS_DIR, s.name), dest, { recursive: true });
+    writeStamp(dest, s.name, VERSION);
   }
-  symlinkSync(src, dest, "dir");
-  return "연결";
+  return { dir: STORE, staged: true };
 }
 
 /** 지시문 파일의 표식 사이 블록만 갈아끼운다. 나머지 내용은 건드리지 않는다. */
@@ -161,7 +259,7 @@ function injectInstructions(file, skills, baseDir) {
   writeFileSync(file, text, "utf8");
 }
 
-function install(targets, { useCopy, dryRun, force }) {
+function install(targets, { useCopy, dryRun, force, direct }) {
   const skills = allSkills();
   const skipped = [];
   if (!skills.length) {
@@ -169,20 +267,34 @@ function install(targets, { useCopy, dryRun, force }) {
     process.exit(1);
   }
 
+  const source = resolveSource(skills, { direct, dryRun });
+  if (source.staged) {
+    console.log("정본 보관: " + source.dir + "  (npx·node_modules 는 사라질 수 있어 복사해 둡니다)");
+  } else {
+    console.log("정본 위치: " + source.dir + "  (수정하면 즉시 반영됩니다)");
+  }
+
   for (const t of targets) {
-    console.log("\n" + t.label + "  →  " + t.dir + (t.verified ? "" : "  (경로 미확인)"));
+    // dir 이 없는 대상은 정본을 그대로 가리킨다 — 같은 것을 두 번 두지 않는다.
+    const dir = t.dir || source.dir;
+    console.log("\n" + t.label + "  →  " + dir + (t.verified ? "" : "  (경로 미확인)"));
     if (dryRun) {
       skills.forEach((s) => console.log("  · " + s.name + "  (건너뜀 — dry-run)"));
+      if (t.mode === "inject") console.log("  지시문: " + t.instructions);
       continue;
     }
-    mkdirSync(t.dir, { recursive: true });
-    for (const s of skills) {
-      const how = place(join(SKILLS_DIR, s.name), join(t.dir, s.name), useCopy, force);
-      if (how.startsWith("건너뜀")) skipped.push(join(t.dir, s.name));
-      console.log("  · " + s.name.padEnd(20) + how);
+    if (t.dir) {
+      mkdirSync(dir, { recursive: true });
+      for (const s of skills) {
+        const how = place(join(source.dir, s.name), join(dir, s.name), useCopy, force, VERSION);
+        if (how.startsWith("건너뜀")) skipped.push(join(dir, s.name));
+        console.log("  · " + s.name.padEnd(20) + how);
+      }
+    } else {
+      console.log("  · 정본을 그대로 사용합니다 (" + skills.length + "개)");
     }
     if (t.mode === "inject") {
-      injectInstructions(t.instructions, skills, t.dir);
+      injectInstructions(t.instructions, skills, dir);
       console.log("  지시문: " + t.instructions);
     }
   }
@@ -216,14 +328,14 @@ function uninstall(targets) {
   for (const t of targets) {
     console.log("\n" + t.label);
     for (const s of skills) {
-      const dest = join(t.dir, s.name);
+      const dest = join(t.dir || STORE, s.name);
       if (!lstatSync(dest, { throwIfNoEntry: false })) continue;
       // 우리가 놓은 것만 지운다. 사용자가 직접 만든 디렉터리는 남긴다.
       if (isOurs(dest, join(SKILLS_DIR, s.name))) {
         rmSync(dest, { recursive: true, force: true });
         console.log("  · " + s.name.padEnd(20) + "제거");
       } else {
-        console.log("  · " + s.name.padEnd(20) + "건너뜀 — 이 패키지가 놓은 것이 아닙니다");
+        console.log("  · " + s.name.padEnd(20) + "건너뜀 — 우리 표식이 없습니다 (직접 만든 스킬이거나 1.0.0 설치본)");
       }
     }
     // 없는 스킬을 가리키는 지시문을 남기면 에이전트가 빈 경로를 읽으려 한다
@@ -231,6 +343,15 @@ function uninstall(targets) {
       console.log("  지시문 블록 제거: " + t.instructions);
     }
   }
+  // 아무 도구도 STORE 를 안 쓰면 빈 껍데기를 남기지 않는다
+  try {
+    if (existsSync(STORE) && readdirSync(STORE).length === 0) {
+      rmSync(STORE, { recursive: true, force: true });
+      console.log("\n정본 보관 폴더 제거: " + STORE);
+    }
+  } catch {
+    /* 지우지 못해도 문제는 아니다 */
+  }
 }
 
 function status() {
@@ -241,13 +362,26 @@ function status() {
   console.log("스킬".padEnd(w) + "  " + TARGETS.map((t) => t.id.padEnd(8)).join(""));
   for (const s of skills) {
     const cells = TARGETS.map((t) => {
-      const dest = join(t.dir, s.name);
-      if (!lstatSync(dest, { throwIfNoEntry: false })) return "-".padEnd(8);
-      // link = 이 패키지가 놓은 것, other = 다른 내용이 이미 있음
-      return (isOurs(dest, join(SKILLS_DIR, s.name)) ? "link" : "other").padEnd(8);
+      const dest = join(t.dir || STORE, s.name);
+      const st = lstatSync(dest, { throwIfNoEntry: false });
+      if (!st) return "-".padEnd(8);
+      // link/copy = 이 패키지가 놓은 것, other = 우리 표식이 없는 내용
+      if (!isOurs(dest, join(SKILLS_DIR, s.name))) return "other".padEnd(8);
+      return (st.isSymbolicLink() ? "link" : "copy").padEnd(8);
     });
     console.log(s.name.padEnd(w) + "  " + cells.join(""));
   }
+  console.log("\nlink = 링크 설치 · copy = 복사 설치 · other = 우리 표식이 없는 내용 · - = 없음");
+  const versions = new Set();
+  for (const t of TARGETS) {
+    for (const s of skills) {
+      const v = readStamp(join(t.dir || STORE, s.name))?.version;
+      if (v) versions.add(v);
+    }
+  }
+  if (versions.size) {
+    console.log("복사 설치된 버전: " + [...versions].sort().join(", ") + "  (패키지: " + VERSION + ")");
+  }
 }
 
 function list() {
@@ -282,11 +416,8 @@ function pickTargets() {
     return picked;
   }
   // 지정이 없으면 설정 디렉터리가 실제로 있는 도구만 고른다
-  const found = TARGETS.filter((t) =>
-    t.mode === "native"
-      ? existsSync(dirname(t.dir))
-      : t.id !== "agents" && existsSync(dirname(t.instructions)),
-  );
+  // detect 가 있는 대상만 자동 탐지한다. agents 는 명시 지정 전용이다.
+  const found = TARGETS.filter((t) => t.detect && existsSync(t.detect));
   if (!found.length) {
     console.error("설치된 AI 도구를 찾지 못했습니다. --tool=<id> 로 직접 지정하세요.");
     console.error("가능한 값: " + TARGETS.map((t) => t.id).join(", ") + ", all");
@@ -301,6 +432,7 @@ switch (cmd) {
       useCopy: flag("copy") || platform() === "win32",
       dryRun: flag("dry-run"),
       force: flag("force"),
+      direct: flag("direct"),
     });
     break;
   case "uninstall":
@@ -322,6 +454,7 @@ switch (cmd) {
   npx @qualisoft/ai-skills install --copy       링크 대신 복사 (Windows 기본)
   npx @qualisoft/ai-skills install --dry-run    무엇이 바뀔지만 본다
   npx @qualisoft/ai-skills install --force      기존 같은 이름 디렉터리를 덮어씀
+  npx @qualisoft/ai-skills install --direct     저장소를 직접 가리킨다 (개발용)
   npx @qualisoft/ai-skills status               어디에 무엇이 설치됐는지
   npx @qualisoft/ai-skills list                 스킬 목록과 설명
   npx @qualisoft/ai-skills uninstall

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qualisoft/ai-skills",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "기획 인터뷰부터 문서 체계·디자인 시안·구현까지 이어지는 AI 에이전트 스킬 5종. Claude Code · Codex · Gemini 등 어느 도구에서나 쓴다. 외부 의존성 없음.",
   "keywords": [
     "ai-skills",
@@ -39,6 +39,7 @@
     "bin/",
     "skills/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {