@moon791017/neo-skills 1.0.42 → 1.0.43

package/AGENTS.md

@@ -3,14 +3,15 @@
 **Neo Skills** 是一個專為 **Antigravity CLI (AGY)** 設計的擴充外掛，旨在將 Agent 轉化為**全方位專家代理 (Universal Expert Agent)**。它利用 Model Context Protocol (MCP) 提供特定領域的專業知識 (Skills)。目前配備了專業的 **DevOps**（Azure Pipelines）與 **Frontend/Backend** 多語系（.NET, Python, Swift, TypeScript/JavaScript, Rust, Vue）等領域的模組，其架構設計可託管任何領域的技能。
 
 ## 回應風格
-使用「繁體中文 (台灣)」
+- 使用「繁體中文 (台灣)」
+- commit訊息必須是「繁體中文 (台灣)」
 
 ---
 
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-`src/` contains runtime TypeScript: [`src/server.ts`](file:///C:/Users/ben_kung/projects/neo-skills/src/server.ts) is the MCP entrypoint and `src/hooks/` holds CLI safety hooks such as `secret-guard.ts`. `bin/` contains the installer CLI and shared helpers. `skills/<skill-name>/` is the main content surface for contributors; each skill centers on a `SKILL.md` file and may also include `reference/` docs or reusable `templates/`. Tests live in `test/*.test.js`. `dist/` is generated output from Bun builds and should not be edited manually.
+`src/` contains runtime TypeScript: [`src/server.ts`](file:///Users/ben/Projects/neo-skills/src/server.ts) is the MCP entrypoint and `src/hooks/` holds CLI safety hooks such as `secret-guard.ts`. `bin/` contains the installer CLI and shared helpers. `skills/<skill-name>/` is the main content surface for contributors; each skill centers on a `SKILL.md` file and may also include `reference/` or `references/` docs, `assets/` templates, or reusable helper `scripts/`. Tests live in `test/*.test.js`. `dist/` is generated output from Bun builds and should not be edited manually.
 
 ## Build, Test, and Development Commands
 Use `npm install` for local setup; CI uses `npm ci`. Run `bun run dev` for quick local iteration against `src/server.ts`. Run `bun run build` to bundle the server and hooks into `dist/`, and `bun run typecheck` for strict TypeScript validation without emitting files. Use `npm test` to run the Node test suite (`node --test`). After a build, `npm start` smoke-tests the bundled server from `dist/server.js`.
@@ -18,6 +19,12 @@ Use `npm install` for local setup; CI uses `npm ci`. Run `bun run dev` for quick
 ## Coding Style & Naming Conventions
 Use ESM modules, 2-space indentation, and keep code ASCII unless a file already uses localized text. Follow the existing style of the file you touch instead of reformatting unrelated lines; current JS utilities mostly use single quotes, while some TS sources use double quotes. Prefer `camelCase` for functions and variables, `UPPER_SNAKE_CASE` for shared constants, and `kebab-case` for skill directories and hook filenames (for example, `neo-python`, `secret-guard.ts`). Keep comments brief and only where intent is not obvious.
 
+### AI Helper Script Specifications (scripts/)
+When writing scripts under `skills/<skill-name>/scripts/` or global helper scripts:
+1.  **STRICTLY Non-Interactive**: Accept inputs only via command-line arguments (using `argparse`), environment variables, or stdin. **Do NOT use interactive prompts (like `input()` or TTY confirmation dialogs), as they will hang the agent indefinitely.**
+2.  **Stdout & Stderr Separation**: Write diagnostic messages, progress logs, and errors to `stderr`. Write only clean, programmatically parseable data (such as JSON or CSV) to `stdout`.
+3.  **Inline Dependencies (PEP 723)**: Python scripts must include an inline PEP 723 dependency block (e.g., `# /// script ...`) to enable self-contained runs via `uv run`.
+
 ## Testing Guidelines
 Add or update tests whenever you change installer behavior, filesystem layout, or hook logic. Place tests in `test/` and name them `*.test.js`. Mirror existing patterns: use temp directories, assert on exit codes, and verify real files were created. There is no published coverage threshold, but PR CI must pass both `npm test` and `bun run build`.
 
@@ -40,9 +47,11 @@ Do not commit secrets, sample credentials, or unsafe prompts. If you change secr
 
 ### 2. 知識庫 (`skills/` & `.agents/skills`)
 每個子目錄代表一個包含專家知識的「技能模組」。
-*   **結構：**
-    *   `SKILL.md`：**大腦**。定義該領域的 **Perceive-Reason-Act** 迴圈。指引 Agent 如何分析環境並做出決策。
-    *   `templates/`：**雙手**。Agent 應優先使用的可重用資產庫。
+*   **結構與漸進式揭露 (Progressive Disclosure) 規範：**
+    *   `SKILL.md`：**大腦**。定義該領域的 **Perceive-Reason-Act** 迴圈。**其第一行必須是 YAML frontmatter 分界符 `---`**，並包含正確的 `name`（必須與其父目錄名稱完全一致以利 Discovery 自動偵測）與 trigger-focused 的 `description`。
+    *   `references/`：**深度知識**。將詳細的檢核表、分析框架或長文檔放於此處，僅在 Reason 階段依需求由 Agent 動態載入。
+    *   `assets/`：**輸出範本**。提供標準的 Markdown 結構範本，降低 Token 開銷。
+    *   `evals/`：**評估集**。必須包含 `evals.json` 與 `eval_queries.json` 用於檢測技能的觸發率與輸出品質。
 *   **載入邏輯：**
     *   **全域技能**: 載入自 `~/.gemini/antigravity-cli/plugins/`。
     *   **專案專屬技能**: 載入自專案根目錄下的 `.agents/skills/`（遷移自舊有的 `.gemini/skills/`）。

package/README.md

@@ -7,9 +7,9 @@
   <img src="images/banner.png" alt="leak-hunter repository secret scanner banner" width="100%">
 </p>
 
-**Neo Skills** 是專為現代 **AI Agent** 設計的**全方位能力擴充套件**。本專案透過標準化的通訊架構，為 AI 代理安裝可插拔的「技能模組 (Skills)」，使其不僅僅是一個聊天機器人，而是能轉化為具備「感知-推理-行動」能力的**多領域專家**。
+**Neo Skills** 是一個專為現代 **AI Agent** 設計的**企業級全方位能力擴充套件**。本專案基於 Model Context Protocol (MCP) 與標準化代理治理架構 (Agent Harness)，為 AI 代理安裝高可靠、可插拔的「專家技能模組 (Skills)」，使其不僅僅是個聊天機器人，而是能深度融入本地開發與運維環境，轉化為具備「感知-推理-行動 (Perceive-Reason-Act)」自主決策能力的**跨領域專家**。
 
-無論是 DevOps 自動化、軟體架構設計，或是未來的資料分析與專案管理，Neo Skills 都能透過掛載不同的知識庫與工具，讓 AI 成為您最強大的全能助手。
+無論是複雜的 DevOps 自動化（Azure Pipelines）、代碼品質安全審查、需求還原與分析釐清，或是多語系的現代化開發，Neo Skills 都能透過模組化的外部知識庫、AI 專用非互動式腳本與品質評估集 (Evals)，讓 AI 代理在安全、受控的 Harness 治理下，成為您最強大的全能數位助手。
 
 ## 🚀 核心願景
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.42",
+  "version": "1.0.43",
   "type": "module",
   "description": "Neo Skills: A Universal Expert Agent Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-azure-pipelines/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: neo-azure-pipeline-architect
+name: neo-azure-pipelines
 version: "1.0.0"
 category: "DevOps"
 description: "根據微軟官方文件與專案需求，設計並生成符合最新標準的 Azure Pipelines YAML 腳本。優先使用模組化範本 (Templates)。"

package/skills/neo-clarification/SKILL.md

@@ -1,72 +1,68 @@
-# Role
-- **Identity**: Senior System Analyst and Requirement Translation Expert.
-- **Expertise**: Requirement grooming, logical deduction, UI/UX screenshot analysis, User Story writing, system boundary definition.
-- **Traits**: Extremely objective and rational, highly empathetic but immune to emotional language, excels at extracting "system specifications" and "business logic" accurately from chaotic, fragmented text and images.
+---
+name: neo-clarification
+description: >
+  Reconstructs chaotic, emotional, or unstructured user requests and screenshots into structured, professional requirement clarification reports. Use this skill when the user provides vague feedback, fragmented descriptions, error screenshots, or raw complaints, and wants to translate them into actionable specifications or a list of clarifying questions.
+---
+
+# Requirement Clarification Specifications
+
+You are a Senior System Analyst and Requirement Translation Expert (Inversion & Generator Pattern). Follow this protocol strictly to translate raw, chaotic user complaints and screenshots into clean, structured system specifications.
 
-# Context
-- **Background**: When general users report system issues or propose new requirements, they often lack context, providing fragmented text, emotional complaints, or simply tossing out one/multiple screenshots without specific explanations.
-- **Objective**: To translate this raw information, which resembles a "disaster scene", into "structured requirement documents" that are clear at a glance for the development team (RD), product managers (PM), and quality assurance (QA) through logical induction and image analysis.
-- **Audience**: IT development and project management teams that require precise system specifications.
+---
 
-# Perceive
-1. **Receive Input**: Receive "raw, chaotic requirements" provided by users, including text descriptions, system screenshots, or any unstructured report information.
-2. **Information Deconstruction & Image Analysis**: Analyze the text and screenshots input by the user. Filter out emotions and noise, and precisely extract: "Objective facts (what is on the screen/what happened)" and "User expectations (what they originally wanted to do)".
+## 1. Perceive Phase
 
-# Reason
-1. **Context Restoration (5W1H)**: From the deconstructed objective facts, attempt to deduce Who (role), Where (in which module/screen), When (when it happened), What (specific event), and Why (the resulting problem).
-2. **Specification Translation Preparation**: Transform the groomed context into a standard User Story format, and think about the corresponding system behavior or functional requirements behind it (e.g., UI rendering logic, API status, permission settings, etc.).
-3. **Gap Analysis**: Keenly identify the missing key links in the original information (e.g., operating system not provided, unknown preliminary operating steps, screenshot not showing error code, etc.), and prepare to ask the user clarifying questions.
+1. **Information Extraction**:
+   - Carefully read the user's text and inspect any attached screenshots or logs.
+   - Filter out emotional noise, frustrations, and blame.
+   - Separate objective facts (what is currently happening or visible) from user expectations (what they wanted to accomplish).
 
-# Act
-Strictly follow the Markdown format structure below to output a structured "Requirement Translation and Clarification Report". **The output must be in Traditional Taiwanese Chinese.**
+2. **Identify System Boundaries**:
+   - Determine the scope, domain, and potential technical layers affected by the feedback (e.g., frontend rendering, network APIs, database states, permission groups).
 
-### 1. 🌟 現況還原 (Context)
-*(Bullet-point summary of the objective phenomena and issues extracted from text and images)*
+---
 
-### 2. 📝 使用者故事 (User Story)
-- **身為**：[User Role]
-- **我想要**：[Specific operation or function]
-- **以便於**：[Business value or pain point solved]
+## 2. Reason Phase
 
-### 3. ⚙️ 系統需求與推測 (System Requirements)
-*(List specific system behaviors, UI adjustments, or potential technical verification points that the development team needs to pay attention to)*
+1. **Load Analysis Framework**:
+   - **Always read** the external analysis guide before starting your deduction:
+     [5w1h-framework.md](file:///Users/ben/Projects/neo-skills/skills/neo-clarification/references/5w1h-framework.md)
+   
+2. **Context Reconstruction (5W1H)**:
+   - Map the extracted facts to the 5W1H framework (Who, Where, When, What, Why, How).
+   - Formulate logical hypotheses on the root causes of UI anomalies or system behaviors.
 
-### 4. ❓ 待釐清問題 (Open Questions)
-*(List 2-10 key questions that need to be asked back to the user to supplement information; the tone should be tactful and professional)*
+3. **Identify Gaps**:
+   - Pinpoint critical missing information (e.g., browser environment, specific action steps, parameters, error logs).
+   - Prepare a list of clarifying questions to ask the user.
 
 ---
 
-# Constraints
-- **Must Include**: Context restoration, User Story, system requirement speculation, and a list of open questions.
-- **Strictly Prohibited**:
-  - Do NOT invent "brand new features" not mentioned by the user.
-  - Do NOT bring the user's emotional words into the final requirement document.
-  - Do NOT directly judge it as a "System Bug" without confirmation (please describe it using objective phenomena).
-- **Language and Length**: Mandatory use of Traditional Taiwanese Chinese (繁體中文), professional and well-organized, avoiding overly academic or obscure vocabulary.
+## 3. Act Phase
 
----
+Generate a structured "Requirement Translation and Clarification Report" strictly in **Traditional Chinese (Taiwan)**. Follow these steps:
 
-# Few-Shot Examples
+1. **Load Output Template**:
+   - Read the standard markdown structure from:
+     [clarification-template.md](file:///Users/ben/Projects/neo-skills/skills/neo-clarification/assets/clarification-template.md)
 
-**[Input Example]**
-"The boss said this screen is weird. I clicked for a long time and there was no response. Why is that green button gone? How am I supposed to submit the report this afternoon? Is the system broken again? [Attached a screenshot with a table but empty top right corner]"
+2. **Compile the Report**:
+   - Fill in the template using Traditional Chinese.
+   - **Context Restoration**: Present objective facts concisely without emotional adjectives.
+   - **User Story**: Use the strict format: "身為... 我想要... 以便於..."
+   - **System Requirements & Hypotheses**: Highlight key rendering, API, and validation checkpoints for the development team.
+   - **Open Questions**: List between 2 and 10 polite, precise, and constructive clarifying questions.
 
-**[Output Example]**
-### 1. 🌟 現況還原 (Context)
-- **發生位置**：報表查詢/匯出畫面（根據截圖推斷）。
-- **發生問題**：原本應該存在的「綠色按鈕」（推測為匯出或下載功能）在畫面上消失，導致使用者無法取得實體報表。
-- **使用者影響**：無法完成下午的報表繳交作業，業務流程中斷。
+3. **Self-Validation**:
+   - Proactively validate your report using the non-interactive python script:
+     ```bash
+     uv run skills/neo-clarification/scripts/validate-requirements.py -i <path_to_saved_report>
+     ```
+     *(Or verify mentally that all sections exist and the number of questions is between 2 and 10 before final output).*
 
-### 2. 📝 使用者故事 (User Story)
-- **身為**：報表使用者
-- **我想要**：在報表查詢畫面上看到並點擊「匯出/下載」按鈕
-- **以便於**：我能順利產出報表檔案，完成下午的業務交辦事項。
+---
 
-### 3. ⚙️ 系統需求與推測 (System Requirements)
-- **UI/UX 檢查**：確認右上角（原綠色按鈕處）的元件渲染邏輯，是否因權限、資料狀態或版更導致隱藏 (Hidden) 或未載入。
-- **功能檢查**：確認報表匯出 API 狀態是否正常。
+## 4. Communication Guidelines
 
-### 4. ❓ 待釐清問題 (Open Questions)
-- 請問發生問題的具體系統名稱與功能路徑是什麼？
-- 請問您的使用者帳號是否有異動過權限？其他同事看得到該按鈕嗎？
-- 請問在按鈕消失前，您有進行過什麼特定的查詢條件設定嗎？
+- **Maintain Empathetic Neutrality**: Acknowledge the user's difficulty, but never agree that the system is "broken" or "a disaster" in the official report. Use neutral, objective descriptions.
+- **Strictly No Guesswork**: Do NOT invent features that the user did not hint at. Ask clarifying questions instead.

package/skills/neo-clarification/assets/clarification-template.md

@@ -0,0 +1,40 @@
+### 1. 🌟 現況還原 (Context)
+<!-- 
+請客觀、條理化地還原使用者所遭遇的具體現象與痛點。
+- 發生位置：[例如：報表查詢與匯出畫面]
+- 發生問題：[例如：右上角的「匯出綠色按鈕」未渲染或消失，點擊無回應]
+- 業務影響：[例如：無法取得實體報表，阻斷了下午的業務繳交程序]
+-->
+
+- **發生位置**：
+- **發生問題**：
+- **使用者影響**：
+
+---
+
+### 2. 📝 使用者故事 (User Story)
+<!-- 
+請遵循敏捷開發標準格式，以使用者視角定義核心需求。
+-->
+- **身為**：[使用者角色 / 例如：報表操作人員]
+- **我想要**：[具體操作或期待的功能 / 例如：在報表畫面上看見並順利點擊「匯出」按鈕]
+- **以便於**：[解決的痛點或業務價值 / 例如：能順利產出報表，準時交付任務]
+
+---
+
+### 3. ⚙️ 系統需求與推測 (System Requirements)
+<!-- 
+列出技術與開發團隊 (RD/PM/QA) 應關注的技術切入點、UI 調整或潛在驗證點。
+-->
+- **UI/UX 元件渲染邏輯**：
+- **API 與後端功能邏輯**：
+- **測試與驗證重點**：
+
+---
+
+### 4. ❓ 待釐清問題 (Open Questions)
+<!-- 
+列出 2 到 10 個核心釐清問題，語氣須委婉、專業且具備建設性。
+-->
+- [ ] 
+- [ ] 

package/skills/neo-clarification/evals/eval_queries.json

@@ -0,0 +1,26 @@
+{
+  "should_trigger": [
+    "使用者丟來一串抱怨說按鈕沒反應，幫我把需求梳理乾淨",
+    "老闆給了我一張系統錯誤的截圖，說要趕快修，我該怎麼釐清問題？",
+    "幫我把這段客戶跟客服的碎碎念對話整理成工程師看得懂的 spec",
+    "這是一封客戶發來的抱怨信，幫我還原成系統規格與提問單",
+    "我們收到了使用者對於新功能的反饋，請幫忙進行需求翻譯與釐清",
+    "這個 Bug report 太過簡略了，幫我還原現況並生成澄清問題清單",
+    "請根據這張網頁異常的截圖，幫我寫一份 PM 與 RD 可以討論的釐清報告",
+    "幫我分析一下這個 Fragmented 的功能提議，還原成標準的 User Story",
+    "使用者抱怨說匯出速度很慢，幫我釐清背後可能的系統需求",
+    "梳理一下這個混亂的產品需求回饋，幫我列出待釐清問題"
+  ],
+  "should_not_trigger": [
+    "幫我寫一個能夠在畫面上拖曳元件的 React 元件",
+    "請告訴我什麼是敏捷開發 (Agile) 的核心理念？",
+    "寫一個 Python 腳本來解析日誌檔案",
+    "請幫我對這段 Java 程式碼進行靜態安全審查",
+    "在 Docker 中如何配置 Nginx 負載均衡？",
+    "如何把 Excel 檔案轉換為 CSV？",
+    "請幫我翻譯這篇英文論文的摘要",
+    "在專案中安裝 Bun 的具體步驟是什麼？",
+    "請說明什麼是 SQL 注入與如何防範",
+    "幫我寫一個 Python 快速排序演算法"
+  ]
+}

package/skills/neo-clarification/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "skill_name": "neo-clarification",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "我想要一個新的後端上傳功能，因為使用者常說他們上傳很大檔案時會連線逾時中斷，這很煩人，我們到底要怎麼做？[附帶了一張空白的上傳失敗進度條截圖]",
+      "expected_output": "結構化的需求還原與澄清報告。必須還原為 5W1H，將痛苦點轉換為標準的 User Story 語法，提出可能的系統技術推測（如分片上傳、加大 timeout、後端 chunk 組合等），並列出至少 2 到 10 個核心澄清問題（例如：檔案平均與最大限制是多少、目前使用的上傳 API timeout 時間是多少）。報告全為繁體中文。",
+      "assertions": [
+        "輸出包含 '現況還原'",
+        "輸出包含 '使用者故事'",
+        "輸出包含 '系統需求'",
+        "輸出包含 '待釐清問題'",
+        "報告使用繁體中文 (台灣)",
+        "待釐清問題清單非空，且包含至少 2 個具體的澄清問題",
+        "報告中客觀描述上傳逾時現象，不夾雜使用者情緒性字眼"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "老闆丟了一張網頁截圖，說這個圓餅圖畫得很奇怪，好像比例都不對，下午開會就要用，這怎麼辦？[附帶了一張圓餅圖比例完全相同的截圖]",
+      "expected_output": "理智客觀的需求翻譯報告。能夠從圓餅圖截圖識別問題（如：所有扇區比例看似相同，可能是後端回傳 mock 資料或前端渲染計算邏輯出錯），並在 Open Questions 中提問確認資料來源與開會重點。全繁體中文輸出。",
+      "assertions": [
+        "輸出包含 '現況還原'",
+        "輸出包含 '待釐清問題'",
+        "報告列出關於圓餅圖資料來源 (Data Source) 或 API 渲染邏輯的推測",
+        "提出委婉且具體的澄清問題，例如詢問此圖表在其他時間點是否也呈現相同比例，或後端資料庫的具體數值是否為全等"
+      ]
+    }
+  ]
+}

package/skills/neo-clarification/references/5w1h-framework.md

@@ -0,0 +1,43 @@
+# 5W1H & Gap Analysis Framework
+
+This reference guide outlines the systematic methodology for translating chaotic, emotional, or unstructured user complaints and screenshots into clean, structured system specifications.
+
+---
+
+## 1. Context Restoration via 5W1H
+
+When a user submits a raw request (e.g., "The green button is gone! System is broken!"), the AI must reconstruct the context by mapping the input to the 5W1H dimensions:
+
+| Dimension | Description | How to Extract / Infer |
+| :--- | :--- | :--- |
+| **Who** | The user role or persona facing the issue. | Identify based on the target module, UI elements in screenshots, or context (e.g., financial reporting, general member, administrator). |
+| **Where** | The specific module, screen, or functional path. | Infer from URL paths, headers in screenshots, page titles, or context keywords. |
+| **When** | The occurrence timing or trigger event. | Identify when the action took place (e.g., during query, upon button click, right after software update). |
+| **What** | The objective phenomena or issue. | Separate facts from emotions. What actually happened? (e.g., a component failed to render, API timed out, validation error triggered). |
+| **Why** | The business impact or operational pain point. | Why is this critical? (e.g., blocks weekly report submission, prevents tax filing). |
+| **How** | The action or steps taken leading to the state. | How did they reach this screen? What specific parameters did they input? |
+
+---
+
+## 2. Gap Analysis (Identifying Missing Information)
+
+Unstructured complaints are often full of gaps. A skilled analyst must systematically detect what is missing before attempting to design a solution.
+
+### Core Checklist for Detecting Gaps:
+1.  **Environment Gaps**: Is the OS, browser, device type, or environment (production, staging, UAT) unknown?
+2.  **Reproduction Gaps**: Are the exact steps leading to the error vague or unspecified?
+3.  **Data Gaps**: Are there query inputs, parameters, or test accounts that were not disclosed?
+4.  **Error Details Gaps**: Is there an error code, stack trace, or console log hidden or unprovided?
+5.  **Scope Gaps**: Is it unclear if the issue affects a single user or all users? Has their permission group changed?
+
+---
+
+## 3. Formulating Tactful Open Questions
+
+Once gaps are identified, they must be converted into clear, professional, and empathetic clarifying questions.
+
+### Guidelines for Formulating Questions:
+*   **Be Polite and Constructive**: Avoid technical jargon that might intimidate the user.
+*   **Be Specific**: Instead of asking "What did you do?", ask "Could you please share the specific search filters or inputs you used right before the button disappeared?"
+*   **One Step at a Time**: Group questions logically and list them clearly in a bulleted format. Keep the total number of questions between 2 and 10.
+*   **Provide Context for the Question**: Explain *why* you are asking (e.g., "To help us check if this is related to account permission permissions, other than your account, are your colleagues able to see this button?").

package/skills/neo-clarification/scripts/validate-requirements.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+
+"""
+AI Agentic Requirement Report Validator (Non-interactive)
+專為 AI Agent 設計的非互動式需求釐清報告完整性驗證工具。
+
+設計要點：
+1. 嚴禁任何互動式提示詞 (input(), confirm())。
+2. 診斷日誌、錯誤訊息一律寫入 sys.stderr。
+3. 處理結果一律以乾淨的 JSON 結構輸出至 sys.stdout。
+"""
+
+import sys
+import argparse
+import re
+import os
+import json
+from typing import Dict, List, Any
+
+def log_diagnostic(message: str) -> None:
+    """將診斷日誌印至 stderr，避免污染 stdout 的 JSON。"""
+    print(f"[LOG] {message}", file=sys.stderr)
+
+def validate_markdown(file_content: str) -> List[str]:
+    """靜態驗證 Markdown 內容是否符合規格要求。"""
+    errors = []
+    
+    # 1. 驗證必要區段（不論是 H3 還是普通標題，檢查關鍵字）
+    required_sections = {
+        "現況還原": r"(現況還原|Context)",
+        "使用者故事": r"(使用者故事|User Story)",
+        "系統需求": r"(系統需求|System Requirements)",
+        "待釐清問題": r"(待釐清問題|Open Questions)"
+    }
+    
+    for section_name, pattern in required_sections.items():
+        if not re.search(pattern, file_content, re.IGNORECASE):
+            errors.append(f"缺少必要區段: {section_name}")
+            
+    # 2. 驗證「待釐清問題」的項目數量是否介於 2 ~ 10 個之間
+    # 我們抓取「待釐清問題」或「Open Questions」區段後方的清單項目
+    try:
+        # 尋找待釐清問題區段的起始位置
+        match = re.search(r"待釐清問題|Open Questions", file_content, re.IGNORECASE)
+        if match:
+            start_index = match.end()
+            # 取得該區段後的文字（直到下一個大標題或結尾）
+            remaining_content = file_content[start_index:]
+            next_section = re.search(r"\n#", remaining_content)
+            section_text = remaining_content[:next_section.start()] if next_section else remaining_content
+            
+            # 計算該區段內部的 bullet points/checkbox 數量 (- [ ], -, *, 1.)
+            items = re.findall(r"^\s*[-*+]\s+.*|^\s*\d+\.\s+.*", section_text, re.MULTILINE)
+            # 過濾掉空白項目或純註解項目
+            valid_items = [item for item in items if not re.match(r"^\s*[-*+]\s+\[\s*\]\s*$", item)]
+            
+            log_diagnostic(f"偵測到待釐清問題數量: {len(valid_items)}")
+            if len(valid_items) < 2:
+                errors.append(f"待釐清問題過少。當前數量: {len(valid_items)} 個（規範要求至少 2 個，最多 10 個）")
+            elif len(valid_items) > 10:
+                errors.append(f"待釐清問題過多。當前數量: {len(valid_items)} 個（規範要求至少 2 個，最多 10 個）")
+        else:
+            errors.append("無法驗證待釐清問題數量，因為找不到該區段。")
+    except Exception as e:
+        log_diagnostic(f"解析待釐清問題數量時出錯: {str(e)}")
+        errors.append(f"解析問題數量失敗: {str(e)}")
+
+    return errors
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="需求釐清報告靜態完整性驗證工具 (AI 專用非互動式)。",
+        epilog="使用範例: uv run validate-requirements.py -i report.md"
+    )
+    parser.add_argument(
+        "-i", "--input",
+        required=True,
+        help="待驗證的需求釐清報告 Markdown 檔案路徑。"
+    )
+    return parser.parse_args()
+
+def main() -> None:
+    try:
+        args = parse_args()
+        
+        if not os.path.exists(args.input):
+            log_diagnostic(f"[錯誤] 檔案不存在: {args.input}")
+            result = {
+                "status": "error",
+                "error_message": f"檔案不存在: {args.input}"
+            }
+            print(json.dumps(result, indent=2))
+            sys.exit(1)
+            
+        log_diagnostic(f"開始驗證檔案: {args.input}")
+        
+        with open(args.input, "r", encoding="utf-8", errors="ignore") as f:
+            content = f.read()
+            
+        errors = validate_markdown(content)
+        
+        result: Dict[str, Any] = {}
+        if not errors:
+            log_diagnostic("驗證成功！報告完全符合規格。")
+            result["status"] = "success"
+            result["errors"] = []
+            print(json.dumps(result, indent=2))
+            sys.exit(0)
+        else:
+            log_diagnostic(f"驗證失敗，發現 {len(errors)} 個問題。")
+            result["status"] = "fail"
+            result["errors"] = errors
+            print(json.dumps(result, indent=2))
+            sys.exit(1)
+            
+    except Exception as e:
+        log_diagnostic(f"[致命錯誤] 執行失敗: {str(e)}")
+        error_result = {
+            "status": "error",
+            "error_message": str(e)
+        }
+        print(json.dumps(error_result, indent=2))
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/skills/neo-code-review/SKILL.md

@@ -1,78 +1,78 @@
 ---
-name: neo-code-review-architect
-description: 分析程式碼變更，從安全性、效能與風格等多個面向找出問題、潛在 Bug 與改善空間。
+name: neo-code-review
+description: >
+  Systematically reviews source code for quality, performance, security, and style issues. Use this skill when the user submits code for review, asks for feedback or a code audit, wants to identify bugs/vulnerabilities, or requests a review of recent changes (such as git diff, staged changes, or a specific commit).
 ---
 
 # Code Review Specifications
 
-## Perceive (Analysis Phase)
-1. **Input Handling**:
-   - If no specific files or code content is provided, execute `git diff HEAD` to retrieve all staged and unstaged changes.
-   - If `git diff` returns empty, inform the user: "No changes detected." and stop.
-   - If specific file paths are provided, read those files.
-   - If raw code content is provided, use it directly.
-
-2. **Scope Identification**:
-   - Analyze the provided code diffs or file contents.
-   - Identify the languages and frameworks involved (e.g., TypeScript, C#, Python, React).
-   - Determine the nature of the change (e.g., Feature, Bugfix, Refactor, Config).
-
-3. **Context Gathering**:
-   - Look for surrounding code to understand the impact of changes.
-   - Check for relevant configuration files (e.g., `tsconfig.json`, `.eslintrc`, security policies) if available in the provided context.
-
-## Reason (Evaluation Phase)
-Evaluate the code against the following dimensions:
-
-1.  **Correctness & Logic**:
-    - Does the code do what it's supposed to do?
-    - Are there any edge cases missing?
-    - Are there potential concurrency issues (race conditions, deadlocks)?
-
-2.  **Security (Critical)**:
-    - **Injection Flaws**: SQLi, XSS, Command Injection.
-    - **Data Exposure**: Hardcoded secrets, sensitive data logging.
-    - **Auth**: Improper authentication or authorization checks.
-    - **Dependencies**: Use of known insecure functions or patterns.
-
-3.  **Performance**:
-    - **Efficiency**: Algorithmic complexity (Big O).
-    - **Resources**: Memory leaks, unclosed file handles/connections.
-    - **Database**: N+1 queries, missing indexes.
-
-4.  **Maintainability & Readability**:
-    - **Clarity**: Variable/function naming, comment quality.
-    - **Complexity**: Cyclomatic complexity, function length.
-    - **Modularity**: DRY (Don't Repeat Yourself), SOLID principles.
-    - **Testing**: Is the code testable? Are tests included?
-
-5.  **Style & Standards**:
-    - Adherence to language-specific conventions (e.g., PEP8 for Python, Airbnb for JS).
-    - Consistency with the existing project style.
-
-## Act (Reporting Phase)
-Generate a structured Code Review Report in **Traditional Chinese (Taiwan)** with the following sections:
-
-1.  **🔍 審查摘要 (Summary)**:
-    - Brief overview of the changes.
-    - Overall assessment (e.g., "Ready to merge", "Needs changes", "Major rework needed").
-
-2.  **🔴 嚴重問題 (Critical Issues)**:
-    - **Must-fix** items (Security vulnerabilities, Logic bugs, Breaking changes).
-    - Clear explanation of *why* it is critical.
-
-3.  **🟡 改進建議 (Suggestions)**:
-    - Performance improvements.
-    - Refactoring opportunities (Clean Code).
-    - Edge case handling.
-
-4.  **🟢 優秀之處 (Praise)** (Optional):
-    - Highlight well-written code or clever solutions.
-
-5.  **❓ 疑問 (Questions)** (Optional):
-    - Clarification needed on business logic or intent.
-
-**Style Guidelines for the Report**:
-- Be constructive and respectful.
-- Use code snippets to illustrate the problem or suggested fix.
-- Focus on the *code*, not the *coder*.
+You are a senior code review expert (Reviewer Pattern). Follow this protocol strictly to systematically, objectively, and constructively review the user's code changes.
+
+---
+
+## 1. Perceive Phase
+
+1. **Identify the Input Source**:
+   - **Scenario A: Specific files are provided**
+     - If the user provides specific file paths or directly attaches code snippets in the conversation, use them as the primary targets for review.
+   - **Scenario B: No files are specified but inside a Git repository**
+     - If the user asks to "review changes", "review PR", or asks for a review without providing explicit code but the project is a Git repository, **proactively run the helper script** to fetch the changes:
+       ```bash
+       uv run skills/neo-code-review/scripts/git-diff-reviewer.py
+       ```
+     - To review only the staging area, append the `--staged` argument.
+     - To review a specific commit range, append the `--commit <range>` argument.
+   - **Scenario C: No changes detected and not a Git repository**
+     - If no code input is detected and the environment is not a Git repository, gracefully prompt the user: "No code changes detected. Please provide a specific code snippet or file path." and terminate the review.
+
+2. **Identify Programming Languages & Frameworks**:
+   - Identify the programming language (e.g., TypeScript, C#, Python) and relevant frameworks in the code changes to apply language-specific style standards in subsequent phases.
+
+---
+
+## 2. Reason Phase
+
+1. **Load the Review Checklist**:
+   - Before evaluating any code, **always read** the external review checklist reference:
+     [review-checklist.md](file:///Users/ben/Projects/neo-skills/skills/neo-code-review/references/review-checklist.md)
+   
+2. **Systematically Evaluate Code**:
+   - Analyze the code logic deeply and compare it against the 5 dimensions in the checklist (Correctness, Security, Performance, Maintainability, Style).
+   - Filter out **🔴 Critical Issues (Must-fix)**, especially security vulnerabilities (e.g., SQL injections, hardcoded keys, unclosed resource connections).
+   - For architectural recommendations, code duplication, or high cyclomatic complexity, classify them under **🟡 Suggestions**.
+
+---
+
+## 3. Act Phase
+
+Generate a highly structured and elegant Code Review Report in **Traditional Chinese (Taiwan)**. The report must strictly follow this format:
+
+### 🔍 審查摘要 (Summary)
+- **整體評估 (Overall Assessment)**: Provide a brief summary and a clear status rating (e.g., "🔴 需要重大修正後合併" (Needs major changes before merging), "🟡 建議修正後合併" (Recommended to fix before merging), "🟢 結構優良，隨時可合併" (Excellent structure, ready to merge)).
+- **變更概述 (Change Overview)**: Briefly describe the main purpose and scope of this change.
+
+### 🔴 嚴重問題 (Critical Issues)
+*This section must ONLY contain **Must-fix** items (security vulnerabilities, critical logic bugs, or severe flaws that may cause system failure). If none are found, write "無" (None).*
+- **[檔案路徑 / 程式碼區段]** (File Path / Code Snippet)
+  - **問題描述 (Problem Description)**: Clearly state what the problem is.
+  - **嚴重原因 (Severity Reason)**: Explain *why* this is a critical issue and its potential consequences.
+  - **修復方案 (Remediation)**: Provide a **concrete corrected code snippet (Code Snippet)** comparing it with the original or showing the fixed version.
+
+### 🟡 改進建議 (Suggestions)
+*Includes suggestions for performance optimization, clean code refactoring, edge-case handling, and comment improvements.*
+- **[檔案路徑 / 程式碼區段]** (File Path / Code Snippet)
+  - **建議事項 (Recommendation)**: How to optimize the code for performance, readability, or maintainability.
+  - **推薦做法 (Proposed Fix)**: Provide an optimized code example.
+
+### 🟢 優秀之處 (Praise) (Optional)
+- Highlight exceptionally well-written, elegant, highly readable, or well-tested code sections to encourage best practices.
+
+### ❓ 疑問與釐清 (Questions) (Optional)
+- Ask objective questions regarding business logic or unexpected implementations to seek clarification from the user.
+
+---
+
+## 4. Communication Guidelines
+
+- **Focus on the Code, not the Coder**: Be constructive, objective, respectful, and humble.
+- **Provide Code Snippets**: Always provide a "corrected code example" for identified issues where applicable. Avoid purely theoretical descriptions.

package/skills/neo-code-review/evals/eval_queries.json

@@ -0,0 +1,26 @@
+{
+  "should_trigger": [
+    "請幫我對這個拉取請求 (PR) 進行代碼審查",
+    "這段程式碼有沒有潛在的 Bug 或記憶體洩漏？",
+    "幫我看一下這個 JavaScript 檔案的安全性寫得怎麼樣",
+    "audit this python script for potential SQL injection or security flaws",
+    "我們今天的 git 變更寫得如何？執行 code review",
+    "review my latest git commit changes",
+    "幫我重構並審查這段 C# 程式碼，看有沒有違反 SOLID 原則",
+    "這段 TypeScript 程式碼寫得好嗎？有沒有改進空間？",
+    "檢查一下這段 SQL 查詢的效能，會不會有慢查詢或缺少索引的問題",
+    "進行靜態代碼分析，指出這個 Go 專案中的問題"
+  ],
+  "should_not_trigger": [
+    "如何安裝 git？",
+    "請幫我寫一個能夠上傳檔案的 FastAPI 後端介面",
+    "解釋一下什麼是 N+1 查詢問題與如何解決",
+    "幫我建立一個全新的 React 專案",
+    "請推薦好用的 Python Linter 工具",
+    "如何配置 tsconfig.json 來支援 ESM？",
+    "在 MacOS 上如何部署 Docker 容器？",
+    "幫我把這段 Python 代碼翻譯成 Rust",
+    "什麼是 SQL Injection 的原理？",
+    "幫我產生一份今天的開發進度週報"
+  ]
+}

package/skills/neo-code-review/evals/evals.json

@@ -0,0 +1,30 @@
+{
+  "skill_name": "neo-code-review",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "請幫我審查這段 Python 程式碼：\n```python\nimport sqlite3\n\ndef get_user_data(user_id):\n    conn = sqlite3.connect('users.db')\n    cursor = conn.cursor()\n    # 存在 SQL 注入風險與資源未關閉\n    query = f\"SELECT * FROM users WHERE id = '{user_id}'\"\n    cursor.execute(query)\n    return cursor.fetchall()\n```",
+      "expected_output": "結構化的代碼審查報告。必須明確指出 `user_id` 的 SQL 注入漏洞 (🔴 嚴重問題)，指出資料庫連接未釋放的效能/資源問題 (🟡 改進建議)，並提供參數化查詢與 `with` 語法糖的修正程式碼範例。報告應全為繁體中文，且包含標準的審查摘要與結構標題。",
+      "assertions": [
+        "輸出包含 '🔍 審查摘要'",
+        "輸出包含 '🔴 嚴重問題'",
+        "輸出包含 '🟡 改進建議'",
+        "報告使用繁體中文 (台灣)",
+        "報告中指出 SQL 注入 (SQL Injection) 漏洞",
+        "報告中指出資料庫連接或 cursor 未正確釋放/關閉的問題",
+        "提供使用參數化查詢 (parameterized query) 或 with 語法的修復代碼範例"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "審查這段沒有明顯問題的 TypeScript 程式碼，並給出建議：\n```typescript\nexport interface User {\n  id: string;\n  name: string;\n  email: string;\n}\n\nexport function formatUserGreeting(user: User): string {\n  return `Hello, ${user.name}! Welcome back.`;\n}\n```",
+      "expected_output": "給予正面評價的繁體中文審查報告，包含摘要、優秀之處 (🟢 優秀之處)，且無嚴重的 Must-fix 問題。可能包含一些關於型別定義或未來擴充性的輕微建議。",
+      "assertions": [
+        "輸出包含 '🔍 審查摘要'",
+        "報告中沒有將此代碼列為 '🔴 嚴重問題' (Must-fix)",
+        "輸出包含 '🟢 優秀之處'",
+        "報告中讚賞其簡單明瞭、型別定義清晰與具備良好的可讀性"
+      ]
+    }
+  ]
+}

package/skills/neo-code-review/references/review-checklist.md

@@ -0,0 +1,76 @@
+# Code Review Checklist
+
+This checklist serves as a systematic guideline for AI reviewers. During the review process, compare the code changes against these criteria and categorize findings by severity: Critical Issues (🔴 Must-fix), Suggestions (🟡 Clean Code/Performance), and Praise (🟢 High Quality).
+
+---
+
+## 1. Correctness & Logic
+
+- [ ] **Functional Completeness**: Does the code fully implement the intended requirements? Are there any missing business logic paths?
+- [ ] **Edge Cases**: Are extreme inputs handled properly (e.g., `null`, `undefined`, empty strings, empty arrays, maximum/minimum values, negative numbers, special characters)?
+- [ ] **Exception Handling**:
+  - Are error-prone operations (e.g., I/O, network requests, parsing) wrapped in appropriate `try-catch` blocks?
+  - Are caught exceptions handled gracefully (e.g., recovering state, user-friendly notifications, or safe logging) instead of being swallowed silently?
+- [ ] **Concurrency & Thread Safety**: In multi-threaded or asynchronous environments, are there potential race conditions, deadlocks, or unawaited async operations?
+- [ ] **State Management**: Are variable lifecycles correct? Are there any unintended side effects or global namespace pollution?
+
+---
+
+## 2. Security — 🔴 Critical
+
+- [ ] **Injection Defenses**:
+  - **SQL Injection**: Are parameterized queries or ORM used? Direct string concatenation for SQL queries is strictly prohibited.
+  - **XSS (Cross-Site Scripting)**: Is data rendered to the frontend properly escaped or sanitized?
+  - **Command Injection**: Are user inputs directly concatenated into system commands?
+- [ ] **Sensitive Data Protection**:
+  - Are there any hardcoded secrets, API tokens, passwords, database connection strings, or private keys?
+  - Does logging accidentally capture Personally Identifiable Information (PII, e.g., SSN, phone numbers, passwords, credit cards) or sensitive internal system structures?
+- [ ] **Authentication & Authorization**:
+  - Are appropriate authorization and authentication checks performed for sensitive operations and APIs?
+  - Does it follow the "Principle of Least Privilege"?
+- [ ] **Insecure Practices & Dependencies**:
+  - Are known insecure functions used (e.g., `eval()` in JavaScript, `exec()` in Python)?
+  - Do dependency libraries have known major vulnerabilities?
+
+---
+
+## 3. Performance & Resource Management
+
+- [ ] **Algorithms & Complexity**: Are time and space complexities reasonable? Are there unnecessary nested loops (e.g., $O(n^2)$ or worse)?
+- [ ] **Database Interaction Efficiency**:
+  - Are there N+1 query issues?
+  - Do database queries utilize indexes properly, or do they fetch unnecessary columns/rows?
+- [ ] **Resource Lifecycle Management**:
+  - Are file handles, database connections, network sockets, and streams explicitly closed/released after use?
+  - Are resources released in `finally` blocks or using structural patterns like `using` (.NET) or `with` (Python)?
+- [ ] **Memory Leaks**:
+  - Are there unregistered event listeners, infinitely growing global caches, or long-lived objects retaining references to short-lived objects?
+- [ ] **Caching & Lazy Loading**: Is an appropriate caching strategy used for high-frequency, low-variance expensive computations or I/O operations?
+
+---
+
+## 4. Maintainability & Readability
+
+- [ ] **Clear Naming**: Are variables, functions, and classes named intuitively and descriptively? Are single-character or meaningless names avoided?
+- [ ] **Complexity Control**:
+  - Is the length of a single function/method reasonable (ideally under 50 lines)?
+  - Is the cyclomatic complexity too high (e.g., excessive nesting, too many branch conditions)?
+- [ ] **Modularity & Architecture**:
+  - Does the code follow the **DRY (Don't Repeat Yourself)** principle?
+  - Does the code follow **SOLID principles** (especially the Single Responsibility Principle - SRP)?
+- [ ] **Testability**:
+  - Is the code easy to unit test?
+  - Is there appropriate dependency injection or decoupling to facilitate mocking external dependencies?
+  - Are there corresponding test cases for new features or bug fixes?
+
+---
+
+## 5. Style & Standards
+
+- [ ] **Idiomatic Best Practices**: Does the code leverage modern features of the language/framework (e.g., TypeScript utility types, Python type hints, pattern matching)?
+- [ ] **Formatting & Style Consistency**:
+  - Do indentation, spacing, and quotes match the existing patterns in the codebase?
+  - Does the code pass local Linter checks (e.g., ESLint, Ruff)?
+- [ ] **Comment Quality**:
+  - Do comments explain "Why" the code is written this way, rather than restating "What" the code does?
+  - Has obsolete or commented-out dead code been cleaned up?

package/skills/neo-code-review/scripts/git-diff-reviewer.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+
+"""
+AI Agentic Git Diff & Code Reader Tool (Non-interactive)
+專為 AI Agent 設計的非互動式程式碼變更與內容擷取腳本。
+
+設計要點：
+1. 嚴禁任何互動式提示詞 (input(), confirm())。
+2. 診斷日誌、錯誤訊息一律寫入 sys.stderr。
+3. 處理結果一律以乾淨的 JSON 結構輸出至 sys.stdout (或寫入指定 --output 檔案)。
+"""
+
+import sys
+import argparse
+import subprocess
+import json
+import os
+from typing import Dict, List, Any
+
+def log_diagnostic(message: str) -> None:
+    """將診斷日誌印至 stderr，避免污染 stdout 的 JSON。"""
+    print(f"[LOG] {message}", file=sys.stderr)
+
+def run_command(cmd: List[str]) -> str:
+    """執行 shell 命令並返回 stdout，出錯時拋出異常。"""
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        return result.stdout
+    except subprocess.CalledProcessError as e:
+        error_msg = f"命令執行失敗: {' '.join(cmd)}\nStderr: {e.stderr}"
+        raise RuntimeError(error_msg)
+
+def get_git_diff(staged_only: bool = False, commit_range: str = None) -> str:
+    """根據參數獲取 git diff 內容。"""
+    cmd = ["git", "diff"]
+    if commit_range:
+        cmd.append(commit_range)
+    elif staged_only:
+        cmd.append("--cached")
+    
+    log_diagnostic(f"執行 Git 命令: {' '.join(cmd)}")
+    return run_command(cmd)
+
+def read_files_content(paths: List[str]) -> List[Dict[str, str]]:
+    """讀取指定檔案的完整內容。"""
+    contents = []
+    for path in paths:
+        if not os.path.exists(path):
+            log_diagnostic(f"[警告] 檔案不存在，跳過: {path}")
+            continue
+        if os.path.isdir(path):
+            log_diagnostic(f"[警告] 路徑是目錄，跳過: {path}")
+            continue
+            
+        try:
+            log_diagnostic(f"讀取檔案內容: {path}")
+            with open(path, "r", encoding="utf-8", errors="ignore") as f:
+                contents.append({
+                    "path": path,
+                    "content": f.read()
+                })
+        except Exception as e:
+            log_diagnostic(f"[錯誤] 無法讀取檔案 {path}: {str(e)}")
+            
+    return contents
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="專為 AI Agent 設計的非互動式代碼變更與內容擷取工具。",
+        epilog="使用範例: uv run git-diff-reviewer.py --staged"
+    )
+    parser.add_argument(
+        "-i", "--input",
+        nargs="*",
+        help="選填。指定審查的檔案路徑列表。若未指定，將預設讀取 Git 變更。"
+    )
+    parser.add_argument(
+        "--staged",
+        action="store_true",
+        help="僅讀取已暫存 (Staged) 的 Git 變更。"
+    )
+    parser.add_argument(
+        "--commit",
+        help="選填。指定 Commit 雜湊值或範圍（例如 HEAD~1..HEAD 或 commit_sha），獲取該範圍內的變更。"
+    )
+    parser.add_argument(
+        "-o", "--output",
+        help="選填。將 JSON 結果寫入指定檔案，而非輸出至 stdout。"
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="模擬執行模式，僅在 stderr 輸出分析計畫，不輸出最終的代碼內容。"
+    )
+    return parser.parse_args()
+
+def main() -> None:
+    try:
+        args = parse_args()
+        
+        # 準備回傳的結構化資料
+        result: Dict[str, Any] = {
+            "mode": "git-diff",
+            "diff": "",
+            "files": [],
+            "status": "success"
+        }
+        
+        # 1. 如果指定了具體檔案
+        if args.input:
+            result["mode"] = "specific-files"
+            log_diagnostic(f"指定檔案審查模式。目標檔案數: {len(args.input)}")
+            if not args.dry_run:
+                result["files"] = read_files_content(args.input)
+        
+        # 2. 否則，預設使用 Git 變更模式
+        else:
+            result["mode"] = "git-diff"
+            log_diagnostic("未指定特定檔案，進入 Git 變更審查模式。")
+            
+            # 先檢查是否為 git 專案
+            try:
+                run_command(["git", "rev-parse", "--is-inside-work-tree"])
+            except Exception:
+                result["status"] = "error"
+                result["error_message"] = "當前目錄非 Git 專案，且未指定輸入檔案。"
+                print(json.dumps(result, indent=2))
+                log_diagnostic("[錯誤] 當前目錄非 Git 專案。")
+                sys.exit(1)
+                
+            if not args.dry_run:
+                diff_content = get_git_diff(staged_only=args.staged, commit_range=args.commit)
+                if not diff_content.strip():
+                    log_diagnostic("未偵測到任何 Git 變更（diff 為空）。")
+                    result["status"] = "empty"
+                else:
+                    result["diff"] = diff_content
+                    
+        # 3. 輸出結果
+        output_str = json.dumps(result, indent=2)
+        if args.output:
+            with open(args.output, "w", encoding="utf-8") as f:
+                f.write(output_str)
+            log_diagnostic(f"已成功將代碼變更 JSON 寫入至: {args.output}")
+        else:
+            # 乾淨地將結果印在 stdout
+            print(output_str)
+            
+        sys.exit(0)
+        
+    except Exception as e:
+        log_diagnostic(f"[致命錯誤] 執行失敗: {str(e)}")
+        # 確保即使出錯也輸出 JSON 錯誤，使調用端不易崩潰
+        error_result = {
+            "status": "error",
+            "error_message": str(e)
+        }
+        print(json.dumps(error_result, indent=2))
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

package/skills/neo-rust/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: neo-rust
-description: 用於開發、重構或審查 Rust 應用程式的專家技能。涵蓋 ownership、borrowing、Result/Option 與現代 Rust 設計模式。當使用者要求撰寫 Rust 程式碼、進行 Code Review 或討論 Rust 架構時使用。
+description: >
+  Develop, refactor, or audit Rust code, covering ownership, borrowing, lifetimes, Result/Option error handling, and modern Rust design patterns. Use this skill when the user needs to write Rust programs, perform Rust Code Reviews, optimize performance (e.g., avoiding unnecessary .clone()), or discuss Rust system architecture, even if they do not explicitly say "Rust" as long as .rs files or a Cargo project are involved.
+license: MIT
+compatibility: Requires environment with Rust toolchain (rustc, cargo) installed
 metadata:
   pattern: tool-wrapper, reviewer
   domain: rust
@@ -8,37 +11,94 @@ metadata:
 
 # Neo Rust Expert
 
-You are an expert Rust developer. Your goal is to write safe, maintainable, and idiomatic Rust code by strictly following the official design patterns and avoiding anti-patterns.
+You are an expert Rust developer. Your goal is to write safe, maintainable, and idiomatic Rust code by strictly following the official design patterns, leveraging Rust's powerful type system, and avoiding anti-patterns.
 
-## Core Directives
+## Gotchas
 
-Before writing or reviewing any Rust code, you MUST follow the "Perceive-Reason-Act" loop:
+* **Gotcha 1 (Async Mutex Deadlock / Send Error)**: 
+  In an `async` function, using the standard library's `std::sync::Mutex` and holding its `MutexGuard` across an `.await` boundary will cause a compiler error because `MutexGuard` does not implement `Send` and cannot be transferred across threads.
+  * *Solution*: Use a local block `{}` to limit the MutexGuard lifetime before the `.await`, or use `tokio::sync::Mutex` instead.
+* **Gotcha 2 (Excessive Cloning)**: 
+  To satisfy the Borrow Checker, beginners often call `.clone()` excessively, which introduces significant memory allocation and copy overhead.
+  * *Solution*: Prioritize passing borrowed references (e.g., `&str` instead of `String`, `&[T]` instead of `Vec<T>`), or refactor ownership structures and lifetimes.
+* **Gotcha 3 (Unsafe Unwrapping)**: 
+  Using `.unwrap()` or `panic!()` directly in library or production-grade code will cause the application to crash, violating Rust's safety-first principle.
+  * *Solution*: Always return `Result<T, E>` or `Option<T>` for graceful error propagation, and use the `?` operator or `match` expression to handle them.
 
-1. **Perceive**: Understand the user's intent. Is it a new feature, a refactor, or a code review?
-2. **Reason**: Load the appropriate reference files based on the task:
-   - For writing new code or architecture design, load `reference/patterns.md` and `reference/coding-style.md`.
-   - For code review or debugging, load `reference/anti-patterns.md` to spot common mistakes.
-3. **Act**: Execute the task adhering strictly to the loaded guidelines.
+## Workflow Checklist
 
-## When Writing Code
-- Prioritize Borrowing over Ownership where applicable (`&str` instead of `String`).
-- Handle errors gracefully using `Result<T, E>`. Never use `.unwrap()` or `panic!()` in library or production code.
-- Represent "no value" with `Option<T>`, never with magic values like empty strings or `-1`.
-- Use the Type System to prevent invalid states (e.g., Typestate, Newtype, Smart Constructors).
-- Ensure resource cleanup using RAII/Drop.
-- Prefer explicit composition over shared mutable state. Default to single ownership.
+Progress:
+- [ ] Step 1: Perceive & Inventory (Check if `Cargo.toml` and `.rs` files exist in the project, and clarify whether the task is "feature development", "refactoring", or "Code Review").
+- [ ] Step 2: Load Reference (Based on the task type, dynamically load corresponding reference files: load `reference/patterns.md` and `reference/coding-style.md` for writing new code, and load `reference/anti-patterns.md` for reviews and debugging).
+- [ ] Step 3: Implement & Validate (After writing or modifying code, compile and analyze it locally using `cargo check` and `cargo clippy`. Fix any warnings or errors until compilation passes cleanly without warnings).
+- [ ] Step 4: Format & Finalize (Run `cargo fmt` to format the code according to official guidelines, and present output using the Output Templates).
 
-## When Reviewing Code
-1. Load `reference/anti-patterns.md`.
-2. Check for unnecessary `.clone()`, excessive use of `String`, and improper error handling.
-3. Verify that `Arc<Mutex<T>>` is not overused where message passing or simple ownership would suffice.
-4. Check naming conventions against `reference/coding-style.md`.
-5. Provide actionable feedback with code examples demonstrating the "Good" approach.
+## Detailed Guidelines
 
-## Tools & Formatting
-Always recommend standard Rust tooling: `cargo fmt`, `cargo clippy`, and `cargo check`.
+### Step 1 — Parse & Inventory
+1. Inspect the current directory to verify if `Cargo.toml` exists.
+2. Analyze the task. For Code Review tasks, read existing changes; for feature development, determine the target modules to create or modify.
 
-## Official Resources
-- **Rust Official Website**: https://www.rust-lang.org/
-- **Rust Documentation**: https://doc.rust-lang.org/
-- **The Rust Programming Language (The Book)**: https://doc.rust-lang.org/book/
+### Step 2 — Dynamic Reference Loading
+To save context space, only this `SKILL.md` is loaded initially. Once executing the task, the Agent **must** load the following resources:
+* **Development & Architecture**: Load [patterns.md](file:///Users/ben/Projects/neo-skills/skills/neo-rust/reference/patterns.md) and [coding-style.md](file:///Users/ben/Projects/neo-skills/skills/neo-rust/reference/coding-style.md).
+* **Review, Refactoring & Debugging**: Load [anti-patterns.md](file:///Users/ben/Projects/neo-skills/skills/neo-rust/reference/anti-patterns.md).
+
+### Step 3 — Compile & Clippy Validation Loop
+Verify newly written or modified Rust code to ensure it is 100% compilable:
+1. Run `cargo check` to verify syntax and type checking.
+2. Run `cargo clippy --all-targets -- -D warnings` to perform strict static analysis and catch potential code smells.
+3. If validation fails:
+   - Carefully inspect the `stderr` compiler errors or Clippy suggestions.
+   - Modify the corresponding code.
+   - Re-run validation until it passes cleanly.
+
+## Output Templates
+
+Present your output using the following structured templates depending on the task type.
+
+### Template A: Code Review Report
+```markdown
+# Rust Code Review Report
+
+## 1. Executive Summary
+*   **Score**: [1-10 rating]
+*   **Summary**: [Overall feedback on code quality, ownership usage, and error handling]
+
+## 2. Findings
+> [!IMPORTANT]
+> Order findings by severity (Error > Warning > Info).
+
+*   **[Severity] Location: `src/main.rs:L12` - [Finding Title]**
+    *   **Description**: [Why is this an issue? Which Rust best practice is violated?]
+    *   **Recommendation**:
+        ```rust
+        // Idiomatic Rust example demonstrating the fix
+        ```
+
+## 3. Top 3 Recommendations
+1.  [First actionable improvement]
+2.  [Second actionable improvement]
+3.  [Third actionable improvement]
+```
+
+### Template B: Implementation & Refactoring Summary
+```markdown
+# Rust Implementation / Refactoring Summary
+
+## 1. Overview of Changes
+[Briefly summarize what Rust modules, structs, or traits were added or refactored]
+
+## 2. Applied Design Patterns & Best Practices
+*   [e.g., Applied the Typestate Pattern to ensure state safety]
+*   [e.g., Replaced `.clone()` with `&str` for performance gains]
+
+## 3. Local Verification Results
+- [x] `cargo check` passed
+- [x] `cargo clippy` passed with zero warnings
+- [x] `cargo fmt` completed successfully
+
+## 4. Next Steps
+1.  [Recommended next action, e.g., run cargo test]
+2.  [Other relevant suggestions]
+```

package/skills/neo-rust/evals/eval_queries.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "Please review this Rust code for any unnecessary clones or security issues.",
+    "should_trigger": true
+  },
+  {
+    "query": "I want to implement a safe state machine in Rust using the Typestate Pattern, can you give me an example?",
+    "should_trigger": true
+  },
+  {
+    "query": "How do I resolve a compile error in Rust where a `MutexGuard` crossing an `await` causes an issue?",
+    "should_trigger": true
+  },
+  {
+    "query": "Write a highly efficient serialization module for my .rs project.",
+    "should_trigger": true
+  },
+  {
+    "query": "I am getting compile errors in my Cargo build, here is the log. Please help me debug it.",
+    "should_trigger": true
+  },
+  {
+    "query": "Please help me write a user database Repository with exception handling in C#.",
+    "should_trigger": false
+  },
+  {
+    "query": "What is the Borrow Checker? What role does it play in memory management?",
+    "should_trigger": false
+  },
+  {
+    "query": "Please help me write a Python script to automate deploying compiled Rust binaries to AWS S3.",
+    "should_trigger": false
+  },
+  {
+    "query": "How do I install rustc and cargo?",
+    "should_trigger": false
+  },
+  {
+    "query": "Please write a technical research report comparing the performance between Rust and Go.",
+    "should_trigger": false
+  }
+]

package/skills/neo-rust/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "neo-rust",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Please help me refactor this code to avoid excessive cloning:\n```rust\nfn process(name: String) {\n    println!(\"{}\", name);\n}\nfn main() {\n    let name = String::from(\"Alice\");\n    process(name.clone());\n    process(name.clone());\n}\n```",
+      "expected_output": "Refactored code with the `process` function parameter changed to a borrowed reference `&str` (or `&String`) and passing `&name` at call sites, completely removing `.clone()`.",
+      "assertions": [
+        "The output code completely removes the `.clone()` calls",
+        "The signature of the `process` function is modified to accept a reference (e.g., `&str`)",
+        "The call sites `process(&name)` use borrowed reference syntax",
+        "Accompanied by a brief explanation of Borrow Checker and ownership best practices"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Please perform a Code Review on this code:\n```rust\nfn get_user_role(id: i32) -> String {\n    let users = vec![\"admin\", \"user\"];\n    users[id as usize].to_string()\n}\n```",
+      "expected_output": "Points out array out-of-bounds access risks (no boundary checks) and suggests returning `Option` or adding safety checks; formatting follows the Code Review report template.",
+      "assertions": [
+        "The review report clearly identifies array out-of-bounds access and panic risks",
+        "Suggests refactoring the return type to `Option<String>` or `Result<String, E>`",
+        "Provides a corrected, idiomatic Rust example",
+        "The Markdown output format strictly follows the structure of Template A: Code Review Report"
+      ]
+    }
+  ]
+}