@moon791017/neo-skills 1.0.18 → 1.0.20

package/README.md

@@ -1,5 +1,7 @@
 # Neo Skills
 
+[![test-on-develop](https://github.com/Benknightdark/neo-skills/actions/workflows/test-on-develop.yml/badge.svg)](https://github.com/Benknightdark/neo-skills/actions/workflows/test-on-develop.yml)
+
 **Neo Skills** 是專為現代 **AI Agent** 設計的**全方位能力擴充套件**。本專案透過標準化的通訊架構，為 AI 代理安裝可插拔的「技能模組 (Skills)」，使其不僅僅是一個聊天機器人，而是能轉化為具備「感知-推理-行動」能力的**多領域專家**。
 
 無論是 DevOps 自動化、軟體架構設計，或是未來的資料分析與專案管理，Neo Skills 都能透過掛載不同的知識庫與工具，讓 AI 成為您最強大的全能助手。
@@ -74,42 +76,36 @@
 gemini extension install https://github.com/Benknightdark/neo-skills --auto-update
 ```
 
-### Claude Code
+### 安裝指定 AI Agent 技能
 
-```bash
-npx -p @moon791017/neo-skills install-claude-skills
-```
-
-### Copilot CLI
+使用 `--ai-agent` 指定要安裝的 agent（可用值：`claude`、`copilot`、`codex`）：
 
 ```bash
-npx -p @moon791017/neo-skills install-copilot-skills
+npx -p @moon791017/neo-skills install-skills --ai-agent claude
+npx -p @moon791017/neo-skills install-skills --ai-agent copilot
+npx -p @moon791017/neo-skills install-skills --ai-agent codex
 ```
 
-### Codex CLI
+### 安裝至指定專案
 
-```bash
-npx -p @moon791017/neo-skills install-codex-skills
-```
-
-### 自訂安裝根目錄
-
-Claude Code、Copilot CLI、Codex CLI 三種安裝指令皆支援 `--target-path` 參數，可指定安裝的根目錄（取代預設的 `$HOME`）。技能子目錄（如 `.claude/skills`）會自動附加：
+搭配 `--project-path` 可將技能安裝至指定專案目錄（技能子目錄會自動附加）：
 
 ```bash
 # 安裝至 /my/project/.claude/skills
-npx -p @moon791017/neo-skills install-claude-skills --target-path /my/project
+npx -p @moon791017/neo-skills install-skills --ai-agent claude --project-path /my/project
 
-# 安裝至 /my/project/.copilot/skills
-npx -p @moon791017/neo-skills install-copilot-skills --target-path /my/project
+# 安裝至 /my/project/.github/skills
+npx -p @moon791017/neo-skills install-skills --ai-agent copilot --project-path /my/project
 
 # 安裝至 /my/project/.codex/skills
-npx -p @moon791017/neo-skills install-codex-skills --target-path /my/project
+npx -p @moon791017/neo-skills install-skills --ai-agent codex --project-path /my/project
 ```
 
-若未指定 `--target-path`，則使用預設根目錄 `$HOME`（即 `~/.claude/skills`、`~/.copilot/skills`、`~/.codex/skills`）。
+若未指定 `--project-path`，則安裝至全域路徑（`~/.claude/skills`、`~/.copilot/skills`、`~/.codex/skills`）。
+
+### 安裝全部 AI Agent 技能
 
-### 安裝全部AI Agent技能
+不帶 `--ai-agent` 即可一次安裝全部：
 
 ```bash
 npx -p @moon791017/neo-skills install-skills

package/bin/_utils.js

@@ -1,74 +1,65 @@
 /**
  * Shared utilities for agent skill installers.
- *
- * 新增 AI agent 只需兩步：
- * 1. 在 AGENTS 加入設定
- * 2. 建立 bin/install-{key}-skills.js（複製任一現有檔案，改 named export 即可）
  */
-import { realpathSync } from 'node:fs';
 import { cp, mkdir, access } from 'node:fs/promises';
-import { join, resolve, dirname, basename } from 'node:path';
+import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = resolve(__dirname, '..');
 const sourceDir = join(packageRoot, 'skills');
 
 /**
  * Agent 設定中心 — 所有 agent 的安裝參數集中管理於此。
- * key 須與檔名 install-{key}-skills.js 一致。
+ *
+ * 各欄位說明：
+ *   name        — 顯示用名稱，用於 CLI 輸出的 log 標籤。
+ *   homePath    — 全域安裝路徑（相對於 $HOME）。未指定 --project-path 時使用。
+ *   projectPath — （選填）專案安裝路徑（相對於 --project-path）。
+ *                  指定 --project-path 且此欄位有值時，優先使用此路徑取代 homePath。
+ *                  例如 Copilot：全域 ~/.copilot/skills，專案 <project>/.github/skills。
+ *   hint        — 安裝成功後顯示的提示訊息。
  */
 export const AGENTS = {
   claude: {
     name: 'Claude',
-    targetSubDir: '.claude/skills',
+    homePath: '.claude/skills',
     hint: '請確保您的 Claude Desktop 或相關插件已指向此目錄。',
   },
   copilot: {
     name: 'Copilot',
-    targetSubDir: '.copilot/skills',
+    homePath: '.copilot/skills',
+    projectPath: '.github/skills',
     hint: '請確保您的 GitHub Copilot CLI 已指向此目錄。',
   },
   codex: {
     name: 'Codex',
-    targetSubDir: '.codex/skills',
+    homePath: '.codex/skills',
     hint: '請確保您的 Codex CLI 已指向此目錄。',
   },
-  // gemini: {
-  //   name: 'Gemini',
-  //   targetSubDir: '.gemini/skills/neo-skills',
-  //   hint: '請確保您的 Gemini CLI 已指向此目錄。',
-  // },
 };
 
 /**
- * 從 CLI 參數解析 --target-path 值
- * @returns {string | undefined}
- */
-function parseTargetPath() {
-  const idx = process.argv.indexOf('--target-path');
-  if (idx === -1 || idx + 1 >= process.argv.length) return undefined;
-  return process.argv[idx + 1];
-}
-
-/**
- * 從檔名解析 agent key: install-{key}-skills.js → key
- */
-function extractAgentKey(importMetaUrl) {
-  const filename = basename(fileURLToPath(importMetaUrl), '.js');
-  const match = filename.match(/^install-(.+)-skills$/);
-  if (!match) throw new Error(`無法從檔名 "${filename}" 解析 agent key`);
-  return match[1];
-}
-
-/**
- * 根據 agent config 建立 installer 函式
- * @param {object} config - agent 設定
- * @param {string} [targetPath] - 使用者透過 --target-path 指定的自訂路徑
+ * 根據 agent config 建立 installer 函式。
+ *
+ * 路徑解析邏輯：
+ *   1. 決定根目錄 (baseDir)：
+ *      - 有 --project-path → 使用者指定的絕對路徑
+ *      - 無 --project-path → $HOME
+ *   2. 決定子目錄 (subDir)：
+ *      - 有 --project-path 且 config 定義了 projectPath → 使用 projectPath
+ *      - 其餘情況 → 使用 homePath
+ *   3. 最終安裝路徑 = baseDir + subDir
+ *
+ * 範例（以 Copilot 為例）：
+ *   預設:                          ~/.copilot/skills              （homedir + homePath）
+ *   --project-path /my/project:   /my/project/.github/skills     （projectPath + projectPath）
+ *
+ * @param {object} config - AGENTS 中的 agent 設定物件
+ * @param {string} [targetPath] - 使用者透過 --project-path 指定的自訂根目錄
  */
-export function createInstaller({ name: agentName, targetSubDir, hint }, targetPath) {
+export function createInstaller({ name: agentName, homePath, projectPath, hint }, targetPath) {
   return async function install() {
     console.log(`🚀 [${agentName}] 開始同步 Neo Skills...`);
 
@@ -80,8 +71,11 @@ export function createInstaller({ name: agentName, targetSubDir, hint }, targetP
       return { success: false, message: msg };
     }
 
+    // 根目錄：--project-path 優先，否則 $HOME
     const baseDir = targetPath ? resolve(targetPath) : homedir();
-    const targetSkillsDir = join(baseDir, targetSubDir);
+    // 子目錄：專案層級有獨立路徑時採用 projectPath，否則用預設的 homePath
+    const subDir = targetPath && projectPath ? projectPath : homePath;
+    const targetSkillsDir = join(baseDir, subDir);
 
     console.log(`📁 來源路徑: ${sourceDir}`);
     console.log(`🎯 目標路徑: ${targetSkillsDir}`);
@@ -105,62 +99,10 @@ export function createInstaller({ name: agentName, targetSubDir, hint }, targetP
       return { success: true, message: '沒有任何檔案被複製' };
     }
 
-    const displayPath = targetPath || targetSubDir;
+    const displayPath = targetPath || homePath;
     const msg = `已同步 ${copyCount} 個檔案/資料夾至 ${displayPath}`;
     console.log(`✅ [${agentName}] 安裝成功！${msg}`);
     if (hint) console.log(`💡 提示: ${hint}`);
     return { success: true, message: msg };
   };
 }
-
-/**
- * 從呼叫端的檔名自動解析 agent，建立對應的 installer。
- * @param {string} importMetaUrl - 呼叫端的 import.meta.url
- * @param {string} [targetPath] - 使用者透過 --target-path 指定的自訂路徑
- */
-export function createInstallerFromFile(importMetaUrl, targetPath) {
-  const key = extractAgentKey(importMetaUrl);
-  const config = AGENTS[key];
-  if (!config) throw new Error(`未知的 agent: "${key}"。請在 _utils.js 的 AGENTS 中註冊。`);
-  return createInstaller(config, targetPath);
-}
-
-/**
- * 當腳本被直接執行時（非 import），自動呼叫 installer。
- * Agent 名稱從檔名自動推導。
- * @param {() => Promise<{ success: boolean, message: string }>} installFn
- * @param {string} callerUrl - 呼叫端的 import.meta.url
- */
-export function runAsMain(installFn, callerUrl) {
-  const callerPath = fileURLToPath(callerUrl);
-  const argvPath = process.argv[1];
-  const isMain = Boolean(argvPath) && (
-    resolve(argvPath) === resolve(callerPath) ||
-    realpathSync.native(resolve(argvPath)) === realpathSync.native(resolve(callerPath))
-  );
-  if (!isMain) return;
-
-  const key = extractAgentKey(callerUrl);
-  const agentName = AGENTS[key]?.name || key;
-
-  process.on('uncaughtException', (err) => {
-    console.error('💥 [Fatal Error]:', err);
-    process.exit(1);
-  });
-  process.on('unhandledRejection', (reason) => {
-    console.error('💥 [Unhandled Rejection]:', reason);
-    process.exit(1);
-  });
-
-  const targetPath = parseTargetPath();
-  const actualInstallFn = targetPath
-    ? createInstallerFromFile(callerUrl, targetPath)
-    : installFn;
-
-  actualInstallFn().then((result) => {
-    if (!result.success) process.exit(1);
-  }).catch((error) => {
-    console.error(`❌ [${agentName}] 安裝失敗:`, error.message || error);
-    process.exit(1);
-  });
-}

package/bin/install-skills.js

@@ -1,17 +1,67 @@
 #!/usr/bin/env node
+/**
+ * Neo Skills 統一安裝程式
+ *
+ * 用法：
+ *   install-skills                                         安裝全部 AI Agent 技能至 $HOME
+ *   install-skills --ai-agent claude                       只安裝 Claude 技能至 $HOME
+ *   install-skills --ai-agent copilot --project-path .     安裝 Copilot 技能至指定專案
+ *
+ * 參數：
+ *   --ai-agent <name>      指定要安裝的 agent（可用值見 _utils.js 的 AGENTS）。
+ *                           省略時安裝全部 agent。
+ *   --project-path <path>  指定專案根目錄作為安裝基底（取代 $HOME）。
+ *                           省略時安裝至全域路徑。
+ */
 import { AGENTS, createInstaller } from './_utils.js';
 
+/**
+ * 從 process.argv 解析指定 flag 的值。
+ * 例如 parseArg('--ai-agent') 在 argv 含 ['--ai-agent', 'claude'] 時回傳 'claude'。
+ * @param {string} flag
+ * @returns {string | undefined}
+ */
+function parseArg(flag) {
+  const idx = process.argv.indexOf(flag);
+  if (idx === -1 || idx + 1 >= process.argv.length) return undefined;
+  return process.argv[idx + 1];
+}
+
+// 全域錯誤攔截，確保非預期錯誤不會靜默失敗
 process.on('uncaughtException', (err) => {
   console.error('💥 [Fatal Error]:', err);
   process.exit(1);
 });
-
 process.on('unhandledRejection', (reason) => {
   console.error('💥 [Unhandled Rejection]:', reason);
   process.exit(1);
 });
 
 async function main() {
+  // 先統一解析 CLI 參數，後續分支都使用同一份輸入來源，
+  // 避免在不同模式中重複讀取 process.argv。
+  const agentKey = parseArg('--ai-agent');
+  const projectPath = parseArg('--project-path');
+
+  // ── 模式一：指定單一 agent ──
+  if (agentKey) {
+    // 以 AGENTS 作為唯一白名單來源，避免使用者輸入未支援的 agent 名稱。
+    const config = AGENTS[agentKey];
+    if (!config) {
+      const valid = Object.keys(AGENTS).join(', ');
+      console.error(`❌ 未知的 agent: "${agentKey}"。可用選項: ${valid}`);
+      process.exit(1);
+    }
+
+    // createInstaller 會根據 agent 設定與 projectPath
+    // 回傳對應的安裝函式，這裡只需執行一次即可完成單一 agent 安裝。
+    const installFn = createInstaller(config, projectPath);
+    const result = await installFn();
+    if (!result.success) process.exit(1);
+    return;
+  }
+
+  // ── 模式二：安裝全部 agent ──
   console.log('╔══════════════════════════════════════════╗');
   console.log('║   🧠 Neo Skills — 統一安裝程式          ║');
   console.log('╚══════════════════════════════════════════╝');
@@ -19,10 +69,12 @@ async function main() {
 
   const results = [];
 
-  for (const [key, config] of Object.entries(AGENTS)) {
+  // 未指定 --ai-agent 時，逐一嘗試安裝所有已註冊 agent。
+  // 每個 agent 的錯誤都獨立處理，確保單一失敗不會中斷整體彙總流程。
+  for (const [, config] of Object.entries(AGENTS)) {
     console.log(`━━━ 正在安裝: ${config.name} ━━━`);
     try {
-      const installFn = createInstaller(config);
+      const installFn = createInstaller(config, projectPath);
       const result = await installFn();
       results.push({ name: config.name, ...result });
     } catch (error) {
@@ -37,6 +89,7 @@ async function main() {
   console.log('📊 安裝結果彙總:');
   const failed = results.filter(r => !r.success);
 
+  // 統一列出每個 agent 的最終結果，讓使用者能快速判斷成功與失敗原因。
   for (const r of results) {
     console.log(`  ${r.success ? '✅' : '❌'} ${r.name}: ${r.message}`);
   }
@@ -52,4 +105,5 @@ async function main() {
   console.log('🎉 全部安裝完成！');
 }
 
+// 以單一入口啟動 CLI，讓所有例外都集中經過上方的全域錯誤處理。
 main();

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "name": "neo-skills",
   "description": "A universal capability extension for Gemini CLI",
-  "version": "0.47.0",
+  "version": "0.47.3",
   "mcpServers": {
     "neo-skills": {
       "command": "node",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",
@@ -12,10 +12,7 @@
   ],
   "bin": {
     "neo-skills": "./bin/install-skills.js",
-    "install-skills": "./bin/install-skills.js",
-    "install-claude-skills": "./bin/install-claude-skills.js",
-    "install-copilot-skills": "./bin/install-copilot-skills.js",
-    "install-codex-skills": "./bin/install-codex-skills.js"
+    "install-skills": "./bin/install-skills.js"
   },
   "files": [
     "dist",
@@ -38,7 +35,7 @@
     "start": "node dist/server.js",
     "dev": "bun src/server.ts",
     "typecheck": "tsc --noEmit",
-    "test": "echo \"No tests specified\" && exit 0"
+    "test": "node --test"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/bin/install-claude-skills.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { createInstallerFromFile, runAsMain } from './_utils.js';
-
-export const install = createInstallerFromFile(import.meta.url);
-export { install as installClaudeSkills };
-
-runAsMain(install, import.meta.url);

package/bin/install-codex-skills.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { createInstallerFromFile, runAsMain } from './_utils.js';
-
-export const install = createInstallerFromFile(import.meta.url);
-export { install as installCodexSkills };
-
-runAsMain(install, import.meta.url);

package/bin/install-copilot-skills.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-import { createInstallerFromFile, runAsMain } from './_utils.js';
-
-export const install = createInstallerFromFile(import.meta.url);
-export { install as installCopilotSkills };
-
-runAsMain(install, import.meta.url);