@moon791017/neo-skills 1.0.21 → 1.0.22

package/README.md

@@ -67,49 +67,126 @@
 
 ## 📦 安裝與使用
 
-本套件支援多種 AI Agent 環境。請依據您的 CLI 工具執行對應指令：
+### 支援的 AI Agent
 
-### Gemini CLI
+| Agent | CLI 工具 | 技能目錄 | 指導檔 |
+| :--- | :--- | :--- | :--- |
+| **Gemini** | [Gemini CLI](https://github.com/google-gemini/gemini-cli) | 透過擴充套件自動載入 | `GEMINI.md` |
+| **Claude** | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `.claude/skills/` | `CLAUDE.md` |
+| **Copilot** | [GitHub Copilot CLI](https://docs.github.com/en/copilot) | `.copilot/skills/`（全域）<br>`.github/skills/`（專案） | `.copilot/copilot-instructions.md`（全域）<br>`.github/copilot-instructions.md`（專案） |
+| **Codex** | [OpenAI Codex CLI](https://github.com/openai/codex) | `.codex/skills/` | `AGENTS.md` |
+
+Neo Skills 提供兩個 CLI 工具，分別用於安裝**技能模組**與**系統提示詞**：
+
+| 工具 | 用途 | 安裝目標 |
+| :--- | :--- | :--- |
+| `install-skills` | 將技能模組（`skills/`）複製到 Agent 的技能目錄 | 資料夾（如 `.claude/skills`） |
+| `install-system-instructions` | 將系統提示詞寫入 Agent 的指導檔 | 單一檔案（如 `CLAUDE.md`） |
+
+> 兩個工具皆支援 `--ai-agent` 與 `--project-path` 參數，邏輯一致。
+
+---
+
+### 一、Gemini CLI（擴充套件模式）
+
+Gemini CLI 透過擴充套件機制直接安裝，**不需要**以下的 npx 指令：
 
 ```bash
 gemini extension install https://github.com/Benknightdark/neo-skills --auto-update
 ```
 
-### 安裝指定 AI Agent 技能
+---
 
-使用 `--ai-agent` 指定要安裝的 agent（可用值：`claude`、`copilot`、`codex`）：
+### 二、安裝技能模組 (`install-skills`)
+
+將 `skills/` 目錄下的所有技能模組複製到目標 AI Agent 的技能資料夾。
+
+**語法：**
 
-```bash
-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
 ```
+install-skills [--ai-agent <name>] [--project-path <path>]
+```
+
+**參數：**
 
-### 安裝至指定專案
+| 參數 | 必填 | 說明 |
+| :--- | :---: | :--- |
+| `--ai-agent <name>` | 否 | 指定目標 Agent（`claude` / `copilot` / `codex`）。省略時安裝全部。 |
+| `--project-path <path>` | 否 | 指定專案根目錄。省略時安裝至 `$HOME` 全域路徑。 |
 
-搭配 `--project-path` 可將技能安裝至指定專案目錄（技能子目錄會自動附加）：
+**安裝路徑對照：**
+
+| Agent | 全域路徑 | 專案路徑 |
+| :--- | :--- | :--- |
+| Claude | `~/.claude/skills/` | `<project>/.claude/skills/` |
+| Copilot | `~/.copilot/skills/` | `<project>/.github/skills/` |
+| Codex | `~/.codex/skills/` | `<project>/.codex/skills/` |
+
+**範例：**
 
 ```bash
-# 安裝至 /my/project/.claude/skills
-npx -p @moon791017/neo-skills install-skills --ai-agent claude --project-path /my/project
+# 安裝指定 Agent 至全域
+npx -p @moon791017/neo-skills install-skills --ai-agent claude -y
 
-# 安裝至 /my/project/.github/skills
-npx -p @moon791017/neo-skills install-skills --ai-agent copilot --project-path /my/project
+# 安裝指定 Agent 至專案
+npx -p @moon791017/neo-skills install-skills --ai-agent copilot --project-path /my/project -y
 
-# 安裝至 /my/project/.codex/skills
-npx -p @moon791017/neo-skills install-skills --ai-agent codex --project-path /my/project
+# 一次安裝全部 Agent
+npx -p @moon791017/neo-skills install-skills -y
 ```
 
-若未指定 `--project-path`，則安裝至全域路徑（`~/.claude/skills`、`~/.copilot/skills`、`~/.codex/skills`）。
+---
+
+### 三、安裝系統提示詞 (`install-system-instructions`)
 
-### 安裝全部 AI Agent 技能
+將預定義的系統提示詞寫入 AI Agent 的指導檔。若指導檔已存在，會附加至最下方；若不存在，則自動建立。
 
-不帶 `--ai-agent` 即可一次安裝全部：
+**語法：**
+
+```
+install-system-instructions --ai-agent <name> --instructions <key> [--project-path <path>]
+```
+
+**參數：**
+
+| 參數 | 必填 | 說明 |
+| :--- | :---: | :--- |
+| `--ai-agent <name>` | ✅ | 指定目標 Agent（`claude` / `copilot` / `codex`）。 |
+| `--instructions <key>` | ✅ | 指定要安裝的系統提示詞（見下方種類表）。 |
+| `--project-path <path>` | 否 | 指定專案根目錄。省略時安裝至 `$HOME` 全域路徑。 |
+
+**指導檔路徑對照：**
+
+| Agent | 全域路徑 | 專案路徑 |
+| :--- | :--- | :--- |
+| Claude | `~/.claude/CLAUDE.md` | `<project>/CLAUDE.md` |
+| Copilot | `~/.copilot/copilot-instructions.md` | `<project>/.github/copilot-instructions.md` |
+| Codex | `~/.codex/AGENTS.md` | `<project>/AGENTS.md` |
+
+**可用的系統提示詞種類：**
+
+| Key | 名稱 | 說明 |
+| :--- | :--- | :--- |
+| `technical-co-founder` | Technical Co-Founder | 讓 AI 扮演技術共同創辦人，以 Discovery → Planning → Building → Polish → Handoff 五階段框架，協助您從零打造可上線的真實產品。 |
+
+**範例：**
 
 ```bash
-npx -p @moon791017/neo-skills install-skills
+# 安裝至專案的 CLAUDE.md
+npx -p @moon791017/neo-skills install-system-instructions \
+  --ai-agent claude --instructions technical-co-founder --project-path /my/project -y
+
+# 安裝至專案的 .github/copilot-instructions.md
+npx -p @moon791017/neo-skills install-system-instructions \
+  --ai-agent copilot --instructions technical-co-founder --project-path /my/project -y
+
+# 安裝至全域 (~/.claude/CLAUDE.md)
+npx -p @moon791017/neo-skills install-system-instructions \
+  --ai-agent claude --instructions technical-co-founder -y
 ```
 
+> **💡** 重複執行相同指令不會重複寫入，系統會自動偵測並跳過已安裝的提示詞。
+
 ## 💡 常用指令範例
 
 您可以直接對 AI 代理下達以下指令或在對話中描述需求：

package/bin/_system-instructions.js

@@ -0,0 +1,58 @@
+export const technicalCoFounderInstructions = `Role:
+You are now my Technical Co-Founder. Your job is to help me build a real product I can use, share, or launch. Handle all the building, but keep me in the loop and in control.
+My Idea:
+[Describe your product idea — what it does, who it's for, what problem it solves. Explain it like you'd tell a friend.]
+How serious I am:
+[Just exploring / I want to use this myself / I want to share it with others / I want to launch it publicly]
+Project Framework:
+1. Phase 1: Discovery
+• Ask questions to understand what I actually need (not just what I said)
+• Challenge my assumptions if something doesn't make sense
+• Help me separate "must have now" from "add later"
+• Tell me if my idea is too big and suggest a smarter starting point
+2. Phase 2: Planning
+• Propose exactly what we'll build in version 1
+• Explain the technical approach in plain language
+• Estimate complexity (simple, medium, ambitious)
+• Identify anything I'll need (accounts, services, decisions)
+• Show a rough outline of the finished product
+3. Phase 3: Building
+• Build in stages I can see and react to
+• Explain what you're doing as you go (I want to learn)
+• Test everything before moving on
+• Stop and check in at key decision points
+• If you hit a problem, tell me the options instead of just picking one
+4. Phase 4: Polish
+• Make it look professional, not like a hackathon project
+• Handle edge cases and errors gracefully
+• Make sure it's fast and works on different devices if relevant
+• Add small details that make it feel "finished"
+5. Phase 5: Handoff
+• Deploy it if I want it online
+• Give clear instructions for how to use it, maintain it, and make changes
+• Document everything so I'm not dependent on this conversation
+• Tell me what I could add or improve in version 2
+6. How to Work with Me
+• Treat me as the product owner. I make the decisions, you make them happen.
+• Don't overwhelm me with technical jargon. Translate everything.
+• Push back if I'm overcomplicating or going down a bad path.
+• Be honest about limitations. I'd rather adjust expectations than be disappointed.
+• Move fast, but not so fast that I can't follow what's happening.
+Rules:
+• I don't just want it to work—I want it to be something I'm proud to show people
+• This is real. Not a mockup. Not a prototype. A working product.
+• Keep me in control and in the loop at all times`;
+
+/**
+ * 系統提示詞 Registry — 以 kebab-case 作為 key，供 CLI 選擇安裝。
+ *
+ * 新增提示詞時：
+ *   1. 在上方新增 named export（內容字串）
+ *   2. 在此 registry 加入對應 entry
+ */
+export const INSTRUCTIONS = {
+  'technical-co-founder': {
+    name: 'Technical Co-Founder',
+    content: technicalCoFounderInstructions,
+  },
+};

package/bin/_utils.js

@@ -25,17 +25,29 @@ export const AGENTS = {
   claude: {
     name: 'Claude',
     homePath: '.claude/skills',
+    instructionFile: {
+      homePath: '.claude/CLAUDE.md',
+      projectPath: 'CLAUDE.md',
+    },
     hint: '請確保您的 Claude Desktop 或相關插件已指向此目錄。',
   },
   copilot: {
     name: 'Copilot',
     homePath: '.copilot/skills',
     projectPath: '.github/skills',
+    instructionFile: {
+      homePath: '.copilot/copilot-instructions.md',
+      projectPath: '.github/copilot-instructions.md',
+    },
     hint: '請確保您的 GitHub Copilot CLI 已指向此目錄。',
   },
   codex: {
     name: 'Codex',
     homePath: '.codex/skills',
+    instructionFile: {
+      homePath: '.codex/AGENTS.md',
+      projectPath: 'AGENTS.md',
+    },
     hint: '請確保您的 Codex CLI 已指向此目錄。',
   },
 };

package/bin/install-system-instructions.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Neo Skills — 系統提示詞安裝程式
+ *
+ * 用法：
+ *   install-system-instructions --ai-agent claude --instructions technical-co-founder
+ *   install-system-instructions --ai-agent copilot --instructions technical-co-founder --project-path .
+ *
+ * 參數：
+ *   --ai-agent <name>         指定目標 AI Agent（可用值見 _utils.js 的 AGENTS）。必填。
+ *   --instructions <key>      指定要安裝的系統提示詞（可用值見 _system-instructions.js 的 INSTRUCTIONS）。必填。
+ *   --project-path <path>     指定專案根目錄作為安裝基底（取代 $HOME）。省略時安裝至全域路徑。
+ */
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+import { AGENTS } from './_utils.js';
+import { INSTRUCTIONS } from './_system-instructions.js';
+
+/**
+ * 從 process.argv 解析指定 flag 的值。
+ * @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];
+}
+
+/**
+ * 產生提示詞的起始標記。
+ * @param {string} key
+ */
+function startMarker(key) {
+  return `<!-- neo-skills:system-instructions:${key} -->`;
+}
+
+/**
+ * 產生提示詞的結束標記。
+ * @param {string} key
+ */
+function endMarker(key) {
+  return `<!-- /neo-skills:system-instructions:${key} -->`;
+}
+
+/**
+ * 將提示詞包裹在起始/結束標記之間。
+ * @param {string} key
+ * @param {string} content
+ */
+function wrapContent(key, content) {
+  return `${startMarker(key)}\n${content}\n${endMarker(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);
+});
+
+async function main() {
+  const agentKey = parseArg('--ai-agent');
+  const projectPath = parseArg('--project-path');
+  const instructionsKey = parseArg('--instructions');
+
+  // ── 驗證 --ai-agent ──
+  if (!agentKey) {
+    const valid = Object.keys(AGENTS).join(', ');
+    console.error(`❌ 缺少必填參數 --ai-agent。可用選項: ${valid}`);
+    process.exit(1);
+  }
+
+  const agentConfig = AGENTS[agentKey];
+  if (!agentConfig) {
+    const valid = Object.keys(AGENTS).join(', ');
+    console.error(`❌ 未知的 agent: "${agentKey}"。可用選項: ${valid}`);
+    process.exit(1);
+  }
+
+  if (!agentConfig.instructionFile) {
+    console.error(`❌ agent "${agentKey}" 未設定 instructionFile。`);
+    process.exit(1);
+  }
+
+  // ── 驗證 --instructions ──
+  if (!instructionsKey) {
+    const valid = Object.keys(INSTRUCTIONS).join(', ');
+    console.error(`❌ 缺少必填參數 --instructions。可用選項: ${valid}`);
+    process.exit(1);
+  }
+
+  const instruction = INSTRUCTIONS[instructionsKey];
+  if (!instruction) {
+    const valid = Object.keys(INSTRUCTIONS).join(', ');
+    console.error(`❌ 未知的 instructions: "${instructionsKey}"。可用選項: ${valid}`);
+    process.exit(1);
+  }
+
+  // ── 決定指導檔路徑 ──
+  const { instructionFile } = agentConfig;
+  const baseDir = projectPath ? resolve(projectPath) : homedir();
+  const subPath = projectPath && instructionFile.projectPath
+    ? instructionFile.projectPath
+    : instructionFile.homePath;
+  const targetFile = join(baseDir, subPath);
+
+  console.log(`🚀 [${agentConfig.name}] 開始安裝系統提示詞: ${instruction.name}`);
+  console.log(`🎯 目標檔案: ${targetFile}`);
+
+  // ── 組裝標記包裹的提示詞內容 ──
+  const wrappedContent = wrapContent(instructionsKey, instruction.content);
+
+  // ── 檢查指導檔是否已存在 ──
+  let fileExists = false;
+  try {
+    await access(targetFile);
+    fileExists = true;
+  } catch {
+    // 檔案不存在，稍後建立
+  }
+
+  if (fileExists) {
+    // 讀取現有內容
+    const existing = await readFile(targetFile, 'utf8');
+
+    // 冪等性檢查：如果已包含相同提示詞的標記，則跳過
+    if (existing.includes(startMarker(instructionsKey))) {
+      console.log(`⏭️  指導檔中已包含 "${instruction.name}" 提示詞，跳過安裝。`);
+      return;
+    }
+
+    // 附加至最下方
+    const newContent = existing.trimEnd() + '\n\n' + wrappedContent + '\n';
+    await writeFile(targetFile, newContent, 'utf8');
+    console.log(`✅ [${agentConfig.name}] 已將 "${instruction.name}" 附加至既有指導檔。`);
+  } else {
+    // 建立目錄結構
+    await mkdir(dirname(targetFile), { recursive: true });
+
+    // 建立新檔案並寫入
+    await writeFile(targetFile, wrappedContent + '\n', 'utf8');
+    console.log(`✅ [${agentConfig.name}] 已建立指導檔並寫入 "${instruction.name}" 提示詞。`);
+  }
+}
+
+main();

package/gemini-extension.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",
@@ -8,11 +8,13 @@
     "gemini cli",
     "claude code",
     "copilot cli",
+    "openai codex cli",
     "ai agent skills"
   ],
   "bin": {
     "neo-skills": "./bin/install-skills.js",
-    "install-skills": "./bin/install-skills.js"
+    "install-skills": "./bin/install-skills.js",
+    "install-system-instructions": "./bin/install-system-instructions.js"
   },
   "files": [
     "dist",