skill-linker 4.1.2 → 4.1.4

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 打造的命令列介面，無需互動問答。
@@ -24,10 +36,10 @@
 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,6 +174,20 @@ 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 時，請確保您有對應目錄的寫入權限。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skill-linker",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "description": "CLI to link AI Agent Skills to various agents (Claude, Copilot, Antigravity, Cursor, etc.)",
   "main": "bin/cli.js",
   "bin": {

package/src/utils/file-system.js

@@ -32,6 +32,11 @@ function ensureDir(dirPath) {
  */
 function createSymlink(source, target) {
     try {
+        // Resolve the source to an absolute path. A relative source (e.g.
+        // "./my-skill") would otherwise be stored verbatim and resolved
+        // relative to the link's own directory, producing a broken link.
+        const resolvedSource = path.resolve(source);
+
         // Ensure parent directory exists
         ensureDir(path.dirname(target));
 
@@ -57,7 +62,7 @@ function createSymlink(source, target) {
             }
         }
 
-        fs.symlinkSync(source, target, 'dir');
+        fs.symlinkSync(resolvedSource, target, 'dir');
         return true;
     } catch (error) {
         console.error(`Failed to create symlink: ${error.message}`);

package/src/utils/git.js

@@ -13,7 +13,8 @@ const DEFAULT_LIB_PATH = path.join(os.homedir(), "Documents/AgentSkills");
 function parseGitHubUrl(url) {
   let cleanUrl = url;
   let subpath = "";
-  let branch = "main";
+  // null means "no explicit branch" — let git use the remote default.
+  let branch = null;
 
   // Check for /tree/branch/path format
   const treeMatch = url.match(/(.+)\/tree\/([^/]+)\/(.+)$/);
@@ -39,19 +40,38 @@ function parseGitHubUrl(url) {
   };
 }
 
+/**
+ * Build the argument list for `git clone`.
+ * @param {string} url - GitHub URL
+ * @param {string} targetPath - Target directory
+ * @param {Object} [opts]
+ * @param {boolean} [opts.shallow] - Use shallow clone (default true)
+ * @param {string|null} [opts.branch] - Branch to check out, or null for default
+ * @returns {string[]} git arguments
+ */
+function buildCloneArgs(url, targetPath, { shallow = true, branch = null } = {}) {
+  const args = ["clone"];
+  if (shallow) {
+    args.push("--depth", "1");
+  }
+  if (branch) {
+    args.push("--branch", branch);
+  }
+  args.push(url, targetPath);
+  return args;
+}
+
 /**
  * Clone a GitHub repository
  * @param {string} url - GitHub URL
  * @param {string} targetPath - Target directory
  * @param {boolean} shallow - Use shallow clone (default true)
+ * @param {string|null} branch - Branch to check out, or null for default
  * @returns {Promise<void>}
  */
-async function cloneRepo(url, targetPath, shallow = true) {
+async function cloneRepo(url, targetPath, shallow = true, branch = null) {
   try {
-    const args = shallow
-      ? ["clone", "--depth", "1", url, targetPath]
-      : ["clone", url, targetPath];
-    await execa("git", args);
+    await execa("git", buildCloneArgs(url, targetPath, { shallow, branch }));
   } catch (error) {
     throw new Error(`Failed to clone repository: ${error.message}`);
   }
@@ -85,8 +105,8 @@ async function cloneOrUpdateRepo(url) {
     // Repo exists, ask if user wants to update
     needsUpdate = true;
   } else {
-    // Clone new repo
-    await cloneRepo(parsed.cleanUrl, targetPath);
+    // Clone new repo (honour an explicit branch from /tree/<branch>/ URLs)
+    await cloneRepo(parsed.cleanUrl, targetPath, true, parsed.branch);
   }
 
   // Determine final skill path
@@ -106,6 +126,7 @@ async function cloneOrUpdateRepo(url) {
 module.exports = {
   DEFAULT_LIB_PATH,
   parseGitHubUrl,
+  buildCloneArgs,
   cloneRepo,
   pullRepo,
   cloneOrUpdateRepo,