skill-linker 4.1.1 → 4.1.3

package/README.md

@@ -6,6 +6,18 @@
 
 一個現代化的 CLI 工具，用於將 AI Agent Skills 快速連結（Symlink）到各種 AI Agent 的專案或全域目錄中。
 
+## 🤔 這是什麼？
+
+**AI Agent Skill** 是一包能擴充 AI 助手能力的檔案（例如讓 Claude 會處理 PDF、Word、Excel）。各家 AI 工具（Claude Code、Cursor、Gemini…）都會去自己的 `skills/` 目錄尋找這些技能。
+
+`skill-linker` 幫你把一份 Skill 一次**連結（symlink）**到一個或多個 AI 工具的 skills 目錄，免去手動複製、也讓日後更新一處即可同步生效。
+
+> 💡 **最快上手**：幫你的 Claude Code 安裝官方 Skills（PDF / Word / Excel / PPT 等），複製這行即可：
+>
+> ```bash
+> npx skill-linker install --from https://github.com/anthropics/skills --agent claude
+> ```
+
 ## ✨ 功能特色
 
 - **CLI 優先設計**：專為 AI Agent 打造的命令列介面，無需互動問答。
@@ -21,13 +33,13 @@
 
 ```bash
 # 安裝技能（需要 --skill 或 --from）
-npx /app/workspace/projects/skill-linker install --skill <路徑> --agent opencode --scope both --yes
+npx skill-linker install --skill <路徑> --agent opencode --scope both --yes
 npx skill-linker install --from https://github.com/anthropics/skills --agent claude --scope both
 
-# 列出已安裝的 Repos
+# 列出 Skill Library 中的 Repos
 npx skill-linker list
-npx skill-linker list --repo skill-name
-npx skill-linker list --repo skill-name --json
+npx skill-linker list --repo anthropics/skills
+npx skill-linker list --repo anthropics/skills --json
 ```
 
 ### 方式 2：本地開發/安裝
@@ -58,50 +70,57 @@ Options:
 ### install 命令
 
 ```
-Usage: skill-linker install --skill <path>
+Usage: skill-linker install [--skill <path> | --from <github-url>] [options]
 
 Options:
-  --skill <path>         指定本地 Skill 目錄路徑（必需）
-  --from <github-url>    從 GitHub Clone 後再進行連結
-  -a, --agent <names>    指定 Agent 名稱（opencode, claude, cursor 等）
-  -s, --scope <scope>    範圍：project, global, both（預設 both）
-  -y, --yes              自動覆寫已存在的連結
+  --skill <path>          指定本地 Skill 目錄路徑
+  --from <github-url>     從 GitHub Clone 後再進行連結
+  -a, --agent <names...>  指定一個或多個 Agent 名稱（opencode claude cursor …）
+  -s, --scope <scope>     範圍：project, global, both（預設 both）
+  -y, --yes              自動覆寫已存在的連結，並在 repo 已存在時更新
 ```
 
+> `--skill` 與 `--from` 至少要提供一個（兩者皆可省略其一）。
+>
+> **`--agent` 省略時**：會自動安裝到所有「已偵測到」的 Agent —— 也就是那些全域目錄（如 `~/.claude`、`~/.cursor`）已存在於你系統上的工具。
+
 範例：
 
 ```bash
-# 指定路徑安裝到 opencode
+# 指定本地路徑安裝到 opencode
 npx skill-linker install --skill /path/to/skill --agent opencode
 
-# 從 GitHub Clone 並安裝到多個 Agents
+# 從 GitHub Clone 並一次安裝到多個 Agents
 npx skill-linker install --from https://github.com/anthropics/skills --agent claude cursor --scope both
 
-# 安裝到所有已偵測到的 Agents
+# 省略 --agent：安裝到所有已偵測到的 Agents
 npx skill-linker install --skill /path/to/skill --scope both --yes
+
+# 只安裝 multi-skill repo 中的「單一」子技能（用 GitHub 的 /tree/<branch>/<子路徑> 連結）
+npx skill-linker install --from https://github.com/anthropics/skills/tree/main/skills/pdf --agent claude
 ```
 
-### list 命令
+`list` 會掃描你的 Skill Library（`~/Documents/AgentSkills`，由 `--from` 自動建立），顯示曾經 Clone 過的 repos 與其中的 skills。
 
 ```
 Usage: skill-linker list [options]
 
 Options:
-  -r, --repo <name>   指定 Repository 名稱
+  -r, --repo <name>   指定 Repository 名稱（格式為 owner/repo）
   --json              JSON 輸出格式
 ```
 
 範例：
 
 ```bash
-# 列出所有 Repos
+# 列出 Library 中所有 Repos
 npx skill-linker list
 
-# 列出特定 Repo 的 Skills
-npx skill-linker list --repo skill-name
+# 列出特定 Repo 的 Skills（名稱為 owner/repo）
+npx skill-linker list --repo anthropics/skills
 
-# JSON 輸出
-npx skill-linker list --repo skill-name --json
+# JSON 輸出（適合腳本處理）
+npx skill-linker list --repo anthropics/skills --json
 ```
 
 ## 📂 Skill Library 管理
@@ -155,10 +174,26 @@ npx skill-linker install --from https://github.com/moltbot/skills --agent openco
 npx skill-linker install --from https://github.com/obra/superpowers --agent claude cursor
 ```
 
+## 🗑️ 移除已安裝的 Skill
+
+本工具目前沒有 `uninstall` 命令。由於安裝動作只是建立一個 **symlink**，要移除時直接刪掉對應 Agent skills 目錄中的那個連結即可，**不會**影響到原始的 Skill 來源：
+
+```bash
+# 例如移除 Claude Code 專案目錄中名為 pdf 的 skill
+rm .claude/skills/pdf
+
+# 或移除全域安裝
+rm ~/.claude/skills/pdf
+```
+
+各 Agent 的 skills 目錄位置請參考上方[支援的 Agent 與路徑](#-支援的-agent-與路徑)。若要刪除整份已 Clone 的來源，移除 `~/Documents/AgentSkills/<owner>/<repo>` 即可。
+
 ## ⚠️ 注意事項
 
 1. **權限問題**：在建立 Symlink 時，請確保您有對應目錄的寫入權限。
 2. **環境需求**：需安裝 Node.js 18.0.0 以上版本。
+3. **Windows**：建立 Symlink 需開啟「開發者模式」或以系統管理員權限執行，否則 `fs.symlinkSync` 會失敗。
+4. **覆寫保護**：`--yes` 只會覆寫既有的 Symlink；若目標是「真實目錄／檔案」，工具會拒絕刪除以保護資料。
 
 ## 授權
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "skill-linker",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "description": "CLI to link AI Agent Skills to various agents (Claude, Copilot, Antigravity, Cursor, etc.)",
   "main": "bin/cli.js",
   "bin": {
     "skill-linker": "bin/cli.js"
   },
   "scripts": {
-    "test": "echo \"No tests yet\""
+    "test": "node --test"
   },
   "keywords": [
     "ai",

package/src/cli.js

@@ -19,10 +19,7 @@ program
 program
   .command("install")
   .description("Install a skill to specified agents")
-  .requiredOption(
-    "--skill <path>",
-    "Path to skill directory or --from clone URL",
-  )
+  .option("--skill <path>", "Path to a local skill directory")
   .option("--from <github-url>", "Clone skill from GitHub URL first, then link")
   .option(
     "-a, --agent <names...>",

package/src/commands/install.js

@@ -75,6 +75,15 @@ async function install(options) {
     skillPaths = [options.skill];
   }
 
+  // Require at least one source: --skill or --from
+  if (skillPaths.length === 0) {
+    console.error(
+      chalk.red("[ERROR]"),
+      "No skill source provided. Use --skill <path> or --from <github-url>.",
+    );
+    process.exit(1);
+  }
+
   // Validate skill paths
   for (const p of skillPaths) {
     if (!dirExists(p)) {
@@ -147,6 +156,9 @@ async function install(options) {
   }
   console.log(chalk.blue("[INFO]"), `Scope: ${scope}`);
 
+  let linkedCount = 0;
+  let failedCount = 0;
+
   // Process each selected agent
   for (const agentIndex of selectedAgents) {
     const agent = agents[agentIndex];
@@ -189,15 +201,27 @@ async function install(options) {
 
         if (createSymlink(sPath, targetLink)) {
           console.log(chalk.green("[SUCCESS]"), `Linked ${sName}`);
+          linkedCount++;
         } else {
           console.error(chalk.red("[ERROR]"), `Failed to link ${sName}`);
+          failedCount++;
         }
       }
     }
   }
 
   console.log("");
-  console.log(chalk.green("[SUCCESS]"), "All operations completed.");
+  if (failedCount > 0) {
+    console.error(
+      chalk.red("[ERROR]"),
+      `Completed with errors: ${linkedCount} linked, ${failedCount} failed.`,
+    );
+    process.exit(1);
+  }
+  console.log(
+    chalk.green("[SUCCESS]"),
+    `All operations completed (${linkedCount} linked).`,
+  );
 }
 
 module.exports = install;

package/src/utils/file-system.js

@@ -35,9 +35,27 @@ function createSymlink(source, target) {
         // Ensure parent directory exists
         ensureDir(path.dirname(target));
 
-        // Remove existing link/file/directory if present
-        // force: true makes it ignore the error if file doesn't exist
-        fs.rmSync(target, { recursive: true, force: true });
+        // Inspect the target itself without following symlinks.
+        let stat = null;
+        try {
+            stat = fs.lstatSync(target);
+        } catch {
+            // Target does not exist — nothing to remove.
+        }
+
+        if (stat) {
+            if (stat.isSymbolicLink()) {
+                // Safe: we are replacing a link, not real content.
+                fs.rmSync(target, { force: true });
+            } else {
+                // A real file or directory lives here. Refuse to delete it so
+                // we never destroy user data that we did not create.
+                console.error(
+                    `Refusing to overwrite non-symlink target: ${target}`,
+                );
+                return false;
+            }
+        }
 
         fs.symlinkSync(source, target, 'dir');
         return true;