skill-linker 2.0.0 → 3.0.0

package/README.md

@@ -1,22 +1,23 @@
-# AI Agent Skill Installer
+# AI Agent Skill Installer (skill-linker)
 
-一個互動式 CLI 工具，用於將 AI Agent Skills 快速連結（Symlink）到各種 AI Agent 的專案或全域目錄中。
+一個現代化的互動式 CLI 工具，用於將 AI Agent Skills 快速連結（Symlink）到各種 AI Agent 的專案或全域目錄中。
 
 ## ✨ 功能特色
 
-- **多 Agent 支援**：支援 Claude Code, GitHub Copilot, Antigravity, Cursor, Windsurf, OpenCode 等。
+- **現代化 TUI 介面**：使用 `prompts` 提供流暢的互動體驗。
+- **模糊搜尋 (Fuzzy Search)**：在選擇 Skill 時可輸入關鍵字快速過濾。
+- **智慧偵測**：自動偵測系統中已安裝的 Agent，並在選單中預設勾選。
+- **多 Agent 支援**：支援 Claude Code, GitHub Copilot, Antigravity, Cursor, Windsurf, OpenCode, Gemini CLI 等。
 - **雙重範圍 (Scope)**：可選擇安裝到當前 `專案目錄 (Project)` 或 `全域目錄 (Global)`。
-- **自動 Clone**：使用 `--from` 參數可直接從 GitHub Clone Skill。
-- **Skill Library 支援**：自動偵測統一的 Skill 存放區。
+- **自動 Clone**：支援從 GitHub Clone 並自動處理 Multi-skill Repos。
+- **完全相容 npx**：無需安裝，隨插即用。
 
 ## 🚀 快速開始
 
 ### 方式 1：使用 npx (推薦)
 
-無需安裝，直接執行：
-
 ```bash
-# 互動式選擇本地 Skill
+# 啟動互動式安裝介面
 npx skill-linker
 
 # 從 GitHub Clone 並安裝
@@ -26,88 +27,58 @@ npx skill-linker --from https://github.com/user/my-skill
 npx skill-linker /path/to/my-skill
 ```
 
-### 方式 2：Clone 此專案
+### 方式 2：本地開發/安裝
 
 ```bash
-git clone https://github.com/user/skill-installer.git
-cd skill-installer
-./link-skill.sh
+git clone https://github.com/raybird/skill-linker.git
+cd skill-linker
+npm install
+npm link # 之後可直接使用 skill-linker 指令
 ```
 
 ## 🛠️ 命令說明
 
 ```
-Usage: link-skill.sh [OPTIONS] [SKILL_PATH]
-
-Options:
-  --from <github_url>   從 GitHub Clone Skill 後再連結
-  --list                列出已 Clone 的 Repos 並選擇 Skills
-  --help                顯示說明
-
-Examples:
-  ./link-skill.sh                           # 互動式選擇
-  ./link-skill.sh --list                    # 瀏覽已 Clone 的 Repos
-  ./link-skill.sh /path/to/skill            # 指定本地 Skill
-  ./link-skill.sh --from https://github.com/user/my-skill
-  ./link-skill.sh --from https://github.com/anthropics/skills/tree/main/skills/pdf
-```
-
-### Multi-Skill Repo 支援
+Usage: skill-linker [options] [command] [skill-path]
 
-對於包含多個 Skills 的 Repo（如 `anthropics/skills`），腳本會：
-1. 自動偵測 `skills/` 子目錄
-2. 列出所有可用的 Skills 讓您選擇
-3. 或者您可以直接在 URL 中指定子路徑（如 `/tree/main/skills/pdf`）
+Interactive CLI to link AI Agent Skills to various agents
 
-### 📋 List Mode - 瀏覽已 Clone 的 Repos
+Arguments:
+  skill-path           指定本地 Skill 目錄路徑
 
-使用 `--list` 參數可以瀏覽 Skill Library 中已 clone 的所有 repos：
+Options:
+  -V, --version        顯示版本號
+  --from <github-url>  從 GitHub Clone Skill 後再連結
+  -l, --list           列出庫中的 Skills (可互動選擇)
+  -h, --help           顯示說明
 
-```bash
-npx skill-linker --list
+Commands:
+  list                 列出所有庫中的 Repos 與其 Skills
 ```
 
-操作流程：
-1. 顯示所有已 clone 的 repos（以 `owner/repo` 格式）
-2. 選擇要使用的 repo
-3. 如果該 repo 包含多個 skills，會列出讓您選擇
-4. 選擇後繼續正常的 Agent 安裝流程
-
-這對於管理多個已下載的 skill repos 特別有用！
-
-## 📦 推薦的 Public Skill Repos
+### 📋 瀏覽模式 (List Mode)
 
-| Repo | 說明 |
-|------|------|
-| [anthropics/skills](https://github.com/anthropics/skills) | Claude 官方 Skills (pdf, docx, pptx, xlsx...) |
-| [obra/superpowers](https://github.com/obra/superpowers) | 開發流程 Skills (TDD, debugging, code-review...) |
+使用 `list` 子指令或 `-l` 參數可以啟動兩層式的互動瀏覽：
 
 ```bash
-# 安裝 Anthropic 的 PDF Skill
-npx skill-linker --from https://github.com/anthropics/skills/tree/main/skills/pdf
-
-# 安裝 obra 的所有開發 Skills (可互動選擇)
-npx skill-linker --from https://github.com/obra/superpowers
+npx skill-linker list
 ```
 
-## 📂 Skill Library
+1. **第一層**：選擇已 Clone 的 Repository (會標註是否有 `skills/` 子目錄)。
+2. **第二層**：如果該 Repo 包含多個 Skills，會進階列出供您查看。
+
+## 📂 Skill Library 管理
 
-使用 `--from` 參數時，Skills 會自動存放到 `~/Documents/AgentSkills`，並以 **owner/repo** 結構分層：
+當您使用 `--from` 參數時，Skills 會自動存放到 `~/Documents/AgentSkills`，並以 **owner/repo** 結構分層：
 
 ```
 ~/Documents/AgentSkills/
 ├── anthropics/
 │   └── skills/          # https://github.com/anthropics/skills
-├── obra/
-│   └── superpowers/     # https://github.com/obra/superpowers
 └── your-org/
     └── your-skill/      # https://github.com/your-org/your-skill
 ```
 
-這種命名空間結構可避免不同帳號擁有相同 repo 名稱時的衝突。
-
-腳本會自動偵測此目錄並列出可用的 Skills。
-
 ## 🛠️ 支援的 Agent 與路徑
 
 | 平台 / 工具 | 專案目錄 | 全域目錄 |
@@ -121,11 +92,19 @@ npx skill-linker --from https://github.com/obra/superpowers
 | **Gemini CLI** | `.gemini/skills/` | `~/.gemini/skills/` |
 | **Windsurf** | `.windsurf/skills/` | `~/.codeium/windsurf/skills/` |
 
+## 📦 推薦的 Public Skill Repos
+
+| Repo | 說明 |
+|------|------|
+| [anthropics/skills](https://github.com/anthropics/skills) | Claude 官方 Skills (pdf, docx, pptx, xlsx...) |
+| [moltbot/skills](https://github.com/moltbot/skills) | 各種封存的 AI Agent Skills (來自 clawdhub.com) |
+
 ## ⚠️ 注意事項
 
-1. **Windows 使用者**：請使用 WSL 或 Git Bash 執行此工具。
-2. **Git Clone First**：`--from` 參數會自動處理 clone，但如果不使用該參數，請確保 Skill 已在本地。
+1. **權限問題**：在建立 Symlink 時，請確保您有對應目錄的寫入權限。
+2. **環境需求**：需安裝 Node.js 14.0.0 以上版本。
 
 ## 授權
 
 MIT License
+

package/bin/cli.js

@@ -1,48 +1,8 @@
 #!/usr/bin/env node
 
 /**
- * skill-linker CLI
- * Node.js wrapper for link-skill.sh
+ * skill-linker CLI entry point
+ * Modern Node.js implementation with interactive TUI
  */
 
-const { spawn } = require('child_process');
-const path = require('path');
-const fs = require('fs');
-
-// Get the path to the shell script
-const scriptPath = path.join(__dirname, '..', 'link-skill.sh');
-
-// Check if bash is available
-const isWindows = process.platform === 'win32';
-
-if (isWindows) {
-    console.error('\x1b[31m[ERROR]\x1b[0m This tool requires Bash.');
-    console.error('On Windows, please use WSL (Windows Subsystem for Linux) or Git Bash.');
-    console.error('');
-    console.error('Example with WSL:');
-    console.error('  wsl npx skill-linker');
-    process.exit(1);
-}
-
-// Check if script exists
-if (!fs.existsSync(scriptPath)) {
-    console.error('\x1b[31m[ERROR]\x1b[0m Shell script not found:', scriptPath);
-    process.exit(1);
-}
-
-// Forward all arguments to the shell script
-const args = process.argv.slice(2);
-
-const child = spawn('bash', [scriptPath, ...args], {
-    stdio: 'inherit',
-    cwd: process.cwd()
-});
-
-child.on('error', (err) => {
-    console.error('\x1b[31m[ERROR]\x1b[0m Failed to run script:', err.message);
-    process.exit(1);
-});
-
-child.on('close', (code) => {
-    process.exit(code || 0);
-});
+require('../src/cli.js');

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "skill-linker",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Interactive CLI to link AI Agent Skills to various agents (Claude, Copilot, Antigravity, Cursor, etc.)",
   "main": "bin/cli.js",
   "bin": {
-    "skill-linker": "./bin/cli.js"
+    "skill-linker": "bin/cli.js"
   },
   "scripts": {
     "test": "echo \"No tests yet\""
@@ -25,16 +25,22 @@
   ],
   "author": "",
   "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.0.0",
+    "execa": "^5.1.1",
+    "prompts": "^2.4.2"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/raybird/skill-installer.git"
+    "url": "git+https://github.com/raybird/skill-linker.git"
   },
   "engines": {
     "node": ">=14.0.0"
   },
   "files": [
     "bin/",
-    "link-skill.sh",
+    "src/",
     "README.md"
   ]
-}
+}

package/src/cli.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const chalk = require('chalk');
+const install = require('./commands/install');
+const list = require('./commands/list');
+
+// Package info
+const packageJson = require('../package.json');
+
+program
+    .name('skill-linker')
+    .description('Interactive CLI to link AI Agent Skills to various agents')
+    .version(packageJson.version);
+
+// Default command (install)
+program
+    .argument('[skill-path]', 'Path to skill directory')
+    .option('--from <github-url>', 'Clone skill from GitHub URL first, then link')
+    .option('-l, --list', 'List available skills in library')
+    .action(async (skillPath, options) => {
+        // Handle --list flag
+        if (options.list) {
+            await list();
+            return;
+        }
+
+        // Run install command
+        await install({
+            skill: skillPath,
+            from: options.from
+        });
+    });
+
+// Standalone list command
+program
+    .command('list')
+    .description('List all available skills in the library')
+    .action(async () => {
+        await list();
+    });
+
+// Parse command line arguments
+program.parse(process.argv);
+

package/src/commands/install.js

@@ -0,0 +1,260 @@
+const prompts = require('prompts');
+const chalk = require('chalk');
+const path = require('path');
+const { findSkills, findRepos, dirExists, ensureDir, createSymlink, listDirectories } = require('../utils/file-system');
+const { getAllAgents, detectInstalledAgents } = require('../utils/agents');
+const { DEFAULT_LIB_PATH, cloneOrUpdateRepo, pullRepo } = require('../utils/git');
+
+/**
+ * Main install command
+ * @param {Object} options - Command options
+ */
+async function install(options) {
+    let skillPaths = [];
+
+    // Handle --from flag: Clone from GitHub
+    if (options.from) {
+        console.log(chalk.blue('[INFO]'), `Cloning from ${options.from}...`);
+
+        try {
+            const { skillPath: clonedPath, targetPath, needsUpdate, hasSubpath } = await cloneOrUpdateRepo(options.from);
+
+            if (needsUpdate) {
+                const { shouldUpdate } = await prompts({
+                    type: 'confirm',
+                    name: 'shouldUpdate',
+                    message: `Repository already exists. Update with git pull?`,
+                    initial: false
+                });
+
+                if (shouldUpdate) {
+                    await pullRepo(targetPath);
+                    console.log(chalk.green('[SUCCESS]'), 'Repository updated!');
+                }
+            }
+
+            // If no subpath, check for skills/ subdirectory
+            if (!hasSubpath && dirExists(path.join(targetPath, 'skills'))) {
+                const subSkills = listDirectories(path.join(targetPath, 'skills'));
+
+                if (subSkills.length > 0) {
+                    const { selectedSkills } = await prompts({
+                        type: 'multiselect',
+                        name: 'selectedSkills',
+                        message: 'This repo contains multiple skills. Select skills to install:',
+                        choices: [
+                            ...subSkills.map(s => ({ title: s, value: path.join(targetPath, 'skills', s) })),
+                            { title: 'Link entire repo', value: targetPath }
+                        ],
+                        hint: '- Space to select. Return to submit'
+                    });
+
+                    if (selectedSkills && selectedSkills.length > 0) {
+                        skillPaths = selectedSkills;
+                    } else {
+                        // If nothing selected, maybe they just hit enter without selection? Default to repo path?
+                        // Or better, error out if multiselect returns empty.
+                        // Let's assume empty selection means exit or user made mistake.
+                        // But to be safe, if they chose "Link entire repo" in multiselect (which is weird), handle it.
+                        // Actually multiselect is better for picking subsets.
+                        // If empty, let's fall back to entire repo (or maybe error).
+                        // Let's error to be consistent with agent selection.
+                    }
+                } else {
+                    skillPaths = [targetPath];
+                }
+            } else {
+                skillPaths = [clonedPath];
+            }
+
+            console.log(chalk.green('[SUCCESS]'), 'Clone completed!');
+        } catch (error) {
+            console.error(chalk.red('[ERROR]'), error.message);
+            process.exit(1);
+        }
+    }
+
+    // If no skill path provided, show library selection
+    if (skillPaths.length === 0 && options.skill) {
+        skillPaths = [options.skill];
+    }
+
+    if (skillPaths.length === 0) {
+        if (!dirExists(DEFAULT_LIB_PATH)) {
+            console.error(chalk.red('[ERROR]'), `Skill library not found: ${DEFAULT_LIB_PATH}`);
+            console.log(chalk.blue('[INFO]'), 'Use --from <github_url> to clone skills first.');
+            process.exit(1);
+        }
+
+        const repos = findRepos(DEFAULT_LIB_PATH);
+
+        if (repos.length === 0) {
+            console.error(chalk.red('[ERROR]'), `No repos found in ${DEFAULT_LIB_PATH}`);
+            console.log(chalk.blue('[INFO]'), 'Use --from <github_url> to clone skills first.');
+            process.exit(1);
+        }
+
+        console.log('');
+
+        // 1. Select Repository
+        const { selectedRepo } = await prompts({
+            type: 'autocomplete',
+            name: 'selectedRepo',
+            message: 'Select a repository:',
+            choices: repos.map(repo => ({
+                title: `${repo.name}${repo.hasSkillsDir ? chalk.dim(' (has skills/)') : ''}`,
+                value: repo
+            })),
+            suggest: (input, choices) => {
+                const inputLower = input.toLowerCase();
+                return Promise.resolve(
+                    choices.filter(choice => choice.title.toLowerCase().includes(inputLower))
+                );
+            }
+        });
+
+        if (!selectedRepo) {
+            console.log(chalk.yellow('[WARNING]'), 'No repository selected. Exiting.');
+            process.exit(0);
+        }
+
+        // 2. Select Sub-skills (if applicable)
+        if (selectedRepo.hasSkillsDir) {
+            const skillsDir = path.join(selectedRepo.path, 'skills');
+            const subSkills = listDirectories(skillsDir);
+
+            if (subSkills.length > 0) {
+                const { selectedSubSkills } = await prompts({
+                    type: 'multiselect',
+                    name: 'selectedSubSkills',
+                    message: `Select skills from ${chalk.cyan(selectedRepo.name)} (Space to select):`,
+                    choices: [
+                        ...subSkills.map(s => ({ title: s, value: path.join(skillsDir, s) })),
+                        { title: 'Link entire repo', value: selectedRepo.path }
+                    ],
+                    hint: '- Space to select. Return to submit'
+                });
+
+                if (!selectedSubSkills || selectedSubSkills.length === 0) {
+                    console.log(chalk.yellow('[WARNING]'), 'No skills selected. Exiting.');
+                    process.exit(0);
+                }
+                skillPaths = selectedSubSkills;
+            } else {
+                skillPaths = [selectedRepo.path];
+            }
+        } else {
+            skillPaths = [selectedRepo.path];
+        }
+    }
+
+    // Validate skill paths
+    for (const p of skillPaths) {
+        if (!dirExists(p)) {
+            console.error(chalk.red('[ERROR]'), `Skill directory not found: ${p}`);
+            process.exit(1);
+        }
+    }
+
+    if (skillPaths.length > 1) {
+        console.log(chalk.blue('[INFO]'), `Selected ${skillPaths.length} skills`);
+    } else {
+        const skillName = path.basename(skillPaths[0]);
+        console.log(chalk.blue('[INFO]'), `Selected Skill: ${chalk.cyan(skillName)} (${skillPaths[0]})`);
+    }
+
+    // Agent selection
+    const agents = getAllAgents();
+    const installedIndices = detectInstalledAgents();
+
+    const { selectedAgents } = await prompts({
+        type: 'multiselect',
+        name: 'selectedAgents',
+        message: 'Select agents to install to (Space to select, Enter to confirm):',
+        choices: agents.map((agent, index) => ({
+            title: agent.name + (installedIndices.includes(index) ? chalk.green(' (Installed)') : ''),
+            value: index,
+            selected: installedIndices.includes(index)
+        })),
+        hint: '- Space to select. Return to submit'
+    });
+
+    if (!selectedAgents || selectedAgents.length === 0) {
+        console.log(chalk.yellow('[WARNING]'), 'No agents selected. Exiting.');
+        process.exit(0);
+    }
+
+    // Process each selected agent
+    for (const agentIndex of selectedAgents) {
+        const agent = agents[agentIndex];
+
+        console.log('');
+        console.log(chalk.blue('[INFO]'), `Configuring for ${chalk.cyan(agent.name)}...`);
+
+        const { scope } = await prompts({
+            type: 'select',
+            name: 'scope',
+            message: 'Select scope:',
+            choices: [
+                { title: `Project (${agent.projectDir})`, value: 'project' },
+                { title: `Global (${agent.globalDir})`, value: 'global' },
+                { title: 'Both', value: 'both' },
+                { title: 'Skip', value: 'skip' }
+            ]
+        });
+
+        if (scope === 'skip') continue;
+
+        const targets = [];
+        if (scope === 'project' || scope === 'both') {
+            targets.push(path.join(process.cwd(), agent.projectDir));
+        }
+        if (scope === 'global' || scope === 'both') {
+            targets.push(agent.globalDir);
+        }
+
+        for (const targetBase of targets) {
+            ensureDir(targetBase);
+
+            // Loop through all selected skills and link them
+            for (const sPath of skillPaths) {
+                const sName = path.basename(sPath);
+                const targetLink = path.join(targetBase, sName);
+
+                if (dirExists(targetLink)) {
+                    // Check if already correct link to avoid prompt
+                    // But for simplicity, we prompt or skip. 
+                    // To avoid spamming prompts for multiple skills, maybe auto-overwrite or ask once?
+                    // Let's ask individually for safety for now, or maybe just log and skip if overwrite not confirmed.
+                    // Actually, prompting for every file in a loop is annoying. 
+                    // Let's check overlap first? Or just try createSymlink which handles unlink.
+
+                    // Let's prompt once per agent/target if any conflicts? Too complex.
+                    // Simple approach: Prompt for each conflict.
+                    const { overwrite } = await prompts({
+                        type: 'confirm',
+                        name: 'overwrite',
+                        message: `${targetLink} already exists. Overwrite?`,
+                        initial: false
+                    });
+
+                    if (!overwrite) {
+                        console.log(chalk.blue('[INFO]'), `Skipping ${sName}...`);
+                        continue;
+                    }
+                }
+
+                if (createSymlink(sPath, targetLink)) {
+                    console.log(chalk.green('[SUCCESS]'), `Linked ${sName}`);
+                } else {
+                    console.error(chalk.red('[ERROR]'), `Failed to link ${sName}`);
+                }
+            }
+        }
+    }
+
+    console.log('');
+    console.log(chalk.green('[SUCCESS]'), 'All operations completed.');
+}
+
+module.exports = install;

package/src/commands/list.js

@@ -0,0 +1,78 @@
+const chalk = require('chalk');
+const prompts = require('prompts');
+const path = require('path');
+const { findRepos, listDirectories, dirExists } = require('../utils/file-system');
+const { DEFAULT_LIB_PATH } = require('../utils/git');
+
+/**
+ * List command - shows repos, then skills within selected repo
+ */
+async function list() {
+    if (!dirExists(DEFAULT_LIB_PATH)) {
+        console.error(chalk.red('[ERROR]'), `Skill library not found: ${DEFAULT_LIB_PATH}`);
+        console.log(chalk.blue('[INFO]'), 'Use --from <github_url> to clone skills first.');
+        process.exit(1);
+    }
+
+    const repos = findRepos(DEFAULT_LIB_PATH);
+
+    if (repos.length === 0) {
+        console.log(chalk.yellow('[WARNING]'), `No repos found in ${DEFAULT_LIB_PATH}`);
+        console.log(chalk.blue('[INFO]'), 'Use --from <github_url> to clone skills first.');
+        return;
+    }
+
+    console.log('');
+    console.log(chalk.blue('[INFO]'), `Repositories in library (${DEFAULT_LIB_PATH}):`);
+    console.log('');
+
+    // Show repos with indication if they have skills/ directory
+    const { selectedRepo } = await prompts({
+        type: 'select',
+        name: 'selectedRepo',
+        message: 'Select a repository to view:',
+        choices: repos.map(repo => ({
+            title: `${repo.name}${repo.hasSkillsDir ? chalk.dim(' (has skills/)') : ''}`,
+            value: repo,
+            description: repo.path
+        }))
+    });
+
+    if (!selectedRepo) {
+        console.log(chalk.yellow('[INFO]'), 'No repository selected.');
+        return;
+    }
+
+    console.log('');
+    console.log(chalk.blue('[INFO]'), `Repository: ${chalk.cyan(selectedRepo.name)}`);
+    console.log(chalk.dim(`Path: ${selectedRepo.path}`));
+    console.log('');
+
+    // If repo has skills/ subdirectory, list the skills
+    if (selectedRepo.hasSkillsDir) {
+        const skillsDir = path.join(selectedRepo.path, 'skills');
+        const skills = listDirectories(skillsDir);
+
+        if (skills.length === 0) {
+            console.log(chalk.yellow('[WARNING]'), 'No skills found in skills/ directory');
+            return;
+        }
+
+        console.log(chalk.blue('[INFO]'), 'Skills in this repository:');
+        console.log('');
+
+        skills.forEach((skill, index) => {
+            console.log(`  ${index + 1}. ${chalk.cyan(skill)}`);
+            console.log(`     ${chalk.dim(path.join(skillsDir, skill))}`);
+        });
+
+        console.log('');
+    } else {
+        console.log(chalk.blue('[INFO]'), 'This is a single-skill repository (no skills/ subdirectory)');
+        console.log(chalk.dim('The entire repository acts as one skill'));
+        console.log('');
+    }
+}
+
+module.exports = list;
+