@moon791017/neo-skills 1.0.41 → 1.0.43

package/AGENTS.md

@@ -1,19 +1,17 @@
 # Neo Skills Extension (agents.md)
 
-**Neo Skills** 是一個專為 **Antigravity CLI (AGY)** 設計的擴充外掛，旨在將 Agent 轉化為**全方位專家代理 (Universal Expert Agent)**。它利用 Model Context Protocol (MCP) 提供特定領域的專業知識 (Skills)。目前配備了專業的 **DevOps** 模組（Azure Pipelines），其架構設計可託管任何領域的技能。
-
-## 核心約束
-- 所有 MCP 指令必須由使用者手動執行，不可自動化！
+**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`.
@@ -21,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`.
 
@@ -43,13 +47,15 @@ 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/`）。
-*   **範例：** `skills/neo-azure-pipelines/` 包含設計 CI/CD 管線的邏輯。
+*   **範例：** `skills/neo-azure-pipelines/` 包含設計 CI/CD 管線的邏輯，`skills/neo-typescript/` 包含 TypeScript 強型別與互通性最佳實踐。
 
 ### 3. 安全層 (`src/hooks/`)
 確保操作安全與數據隱私的機制。

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 治理下，成為您最強大的全能數位助手。
 
 ## 🚀 核心願景
 
@@ -34,11 +34,11 @@
 
 * **智能審查**：針對程式碼變更進行多面向 (正確性、安全性、效能、可讀性) 的深度審查。
 
-### 4. 程式碼解釋助手
+### 3. 程式碼解釋助手
 
 * **技術解析**：深入分析原始碼或專案結構，提供高階用途摘要、邏輯流程分解以及核心元件說明。
 
-### 5. .NET / C# 開發專家
+### 4. .NET / C# 開發專家
 
 * **C# 現代語法專家 (`skills/neo-csharp`)**：跨版本 C# 專家 (10-14+)，專注於現代化語法、強型別與高效能開發模式。
 * **.NET 核心路由 (`skills/neo-dotnet`)**：環境偵測與統一入口，自動將任務委派給最合適的子領域專家。
@@ -49,20 +49,27 @@
 * **.NET Tag Helper 專家 (`skills/neo-dotnet-tag-helper`)**：開發 ASP.NET Core 自定義 Tag Helper 的專家指引，專注於純 C# 實作與異步渲染最佳實踐。
 * **Interface 生成器**：針對 C# Class 自動生成符合規範的 Interface，並支援智慧檔案覆蓋功能。
 
-### 6. Python 開發與環境管理專家
+### 5. Python 開發與環境管理專家
 
 * **Python 3.10+ 專家 (`skills/neo-python`)**：專注於 Python 3.10 至 3.14 的現代語法特性、型別安全與非同步開發。
 * **環境管理專家 (`skills/neo-python-manager`)**：智慧偵測與管理 Python 專案環境，支援 uv, Poetry, venv/pip 並提供自動化安裝建議。
 
-### 7. Swift 開發專家
+### 6. Swift 開發專家
 
 * **Swift 5.0+ 專家 (`skills/neo-swift`)**：支援從基礎語法到 Swift 6 的現代開發模式，涵蓋 SwiftUI、Structured Concurrency、記憶體安全以及高效能 App 開發指引。
 * **SwiftUI 專家 (`skills/neo-swift-ui`)**：支援 iOS 16.0+ 與 Swift 5.0+ 的現代開發模式，專注於 NavigationStack、Observation 框架、資料流架構及高效能視圖設計。
 
-### 8. JavaScript 開發專家
+### 7. JavaScript 開發專家
 
 * **JavaScript 現代語法專家 (`skills/neo-javascript`)**：跨版本 JavaScript 專家 (ES6 - ES2025+)，專注於現代化語法、模組系統與高效能開發模式。
 
+### 8. TypeScript 開發專家
+
+* **TypeScript 現代語法與型別安全 (`skills/neo-typescript`)**：專注於極致的型別安全、高可維護性與進階元程式設計（Meta-programming）。
+  * **型別系統防線**：涵蓋進階條件型別 (Conditional Types)、映射型別 (Mapped Types) 與樣板字面值型別。
+  * **互通性與配置最佳化**：深入調校 `tsconfig.json` 編譯選項，並徹底解決複雜的 ESM/CJS 互通性陷阱與執行期崩潰問題。
+  * **泛型約束設計**：引導設計高靈活度的泛型與變量 (Variance) 處理。
+
 ### 9. Vue 開發專家
 
 * **Vue 3 現代開發專家 (`skills/neo-vue`)**：專注於 Vue 3 Composition API (`<script setup>`)、Pinia 狀態管理與 Vue Router 4。嚴格遵循官方 Style Guide 與最佳實踐，並提供反模式 (Anti-Patterns) 的避坑指引。
@@ -237,6 +244,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | **需求釐清與規格化** | `我想做一個電商網站` |
 | **全方位程式碼審查** | `幫我 code review 剛才的修改` |
 | **生成 C# Interface** | `幫我針對這個 class 產生介面` |
+| **TypeScript 型別設計與互通性** | `解決 tsconfig 還有 ESM/CJS 互通性的問題`、`幫我寫一個強型別的泛型工具` |
 | **技術解析與架構洞察** | `分析這個專案的架構` |
 | **AI 開發流程健檢** | `幫我檢查這個專案怎麼讓 AI 助手開發得更穩、更安全` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.0.41",
+  "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()