themominpro/universal-skill-creator

Universal Skill Creator

1. 核心重新框架與不可協商的不變量

• 心智模型：世界一流的技能是一個隨需的程序化作業系統，而不是非結構化的提示詞。它將專有的從業者智慧財產權與確定性程式碼閘門（三區混合架構）結合，嚴格遵循 references/agentskills_spec.md。
• 環境說明：Python 3 和標準的工作空間探索工具已預先安裝。除非明確的匯入失敗，否則請勿嘗試安裝套件執行器。
• 硬性不變量 1（零氣味閘門）：絕不交付未能通過 python3 scripts/audit_skill.py <path> 的技能。所有結構佈局氣味都必須被稽核並解決。
• 硬性不變量 2（腳本鍛造義務）：每當候選技能執行驗證、架構檢查或 AST 比較時，你必須在 scripts/validate.py 中撰寫配套的可執行工具（腳本程式碼佔用 0 上下文 token）。
• 硬性不變量 3（抗壓縮生存）：不變量、套件說明和工作路由表必須位於 SKILL.md 的前 1,000 個 token 內，以防止壓縮剪裁（請參閱 references/compaction_resilience.md）。
• 硬性不變量 4（生產標準）：每個技能都必須包含領域標準術語、反合理化表格以及可驗證的評估測試案例。
• 硬性不變量 5（行為閘門，不僅是結構）：通過稽核和安全檢查，但未能超越無技能基線、無法承受壓力、或在存根模式下無法正確路由的技能，不得發布。請參閱 references/baseline_grading.md、references/pressure_scenarios.md、references/stub_router_mode.md 和 references/render_qa.md。
• 硬性不變量 6（僅供結構參考）：發布的範例僅展示結構、觸發方式、工作流程、決策表、驗證腳本和評估。請勿將範例的領域規則複製到新技能中。每個新技能都必須根據使用者的 SOP、訪談記錄和領域研究來建構。

---

2. 工作路由決策表

使用者意圖 / 輸入類型	推薦的建立工作流程	隨需參考文件
商業 B2B 技能（用於銷售 / 客戶交付）	執行完整六階段流程（階段 0–5）	references/competitor_teardown_protocol.md
原始筆記 / SOP / 開發者訪談記錄	執行完整六階段建立流程	references/domain_knowledge_ingestion.md
需要外部 API 或 MCP 伺服器的技能	執行階段 1 工具探索 + MCP 接線	references/mcp_tool_patterns.md
稽核或修復現有技能	執行零 token 26 氣味稽核與修補	references/smell_taxonomy_26.md
多輪互動式精靈建立	應用 OMSC 模糊分類協議	references/question_triage_omsc.md
版本敏感的技能（CLI、API、變動中的指南）	使用存根 / 路由器模式，僅 40-60 行指標	references/stub_router_mode.md
任何技能，在每個決策階段	執行 QA 檢查點，每個檢查點最多 2 個問題，記錄每個檢查點	references/qa_checkpoints.md
輸入格式為 .docx、.pdf、.ppt 或類似格式	優先使用工具原生的讀取功能（Claude Code / Claude）；萃取器是選用後備方案，僅在純文字詞彙腳本需要時才使用	scripts/extract_text.py
證明某個技能確實有幫助	執行壓力 + 基線評分 + 渲染 QA	references/pressure_scenarios.md、references/baseline_grading.md、references/render_qa.md

---

3. 階段 0：深度市場情報與競爭者分析

在撰寫指示之前，請使用 agents/niche_researcher.md 執行競爭情報調查：

• 步驟 0.1（競爭者分析）：搜尋此領域中現有的公開技能、提示詞或自訂指示。
  • 對照 26 種氣味分類法稽核競爭者提供的產品（references/competitor_teardown_protocol.md）。
  • 識別其結構缺陷（例如，通用的 AI 內容、選項自助餐、缺少驗證腳本）。
  • 定義能夠修復競爭者結構缺陷的解毒劑。
• 步驟 0.2（領域文獻與術語攝取）：
  • 攝取相關書籍、白皮書、播客文字稿和企業 SOP，支援以下格式：.txt、.md、.docx、.pdf、筆記和文字稿。
  • 格式規則，優先使用工具原生功能，非強制規則：Claude Code 和 Claude 原生支援讀取 .md、.pdf、.docx、.ppt 等格式，因此請優先使用工具本身的讀取功能。當工具已讀取檔案時，請勿強制進行萃取。
  • scripts/extract_text.py 中的套件萃取器是選用後備方案，僅供需要純文字的腳本使用。其唯一強制用途是詞彙腳本，該腳本只能讀取文字，因此如果你對 .docx 或 .pdf 執行詞彙腳本，請先萃取為 .txt：

  python3 scripts/extract_text.py path/to/source.docx --output evals/source.txt
  python3 scripts/extract_text.py path/to/source.pdf --output evals/source.txt
  

  • 掃描的純圖片 PDF 沒有文字層：萃取器會發出警告並回傳空文字。請勿為這類 PDF 虛構文字；請在此套件外部使用 OCR，並記錄該步驟，或者如果 Claude 能原生讀取該檔案，就讓 Claude 處理。
  • 遵循 references/domain_knowledge_ingestion.md 來萃取：
    1. 權威性的業界縮寫、指標和標準術語（例如 MEDDPICC、CAC 回收期、掛鉤停留時間）。
    2. 透過 python3 scripts/build_domain_lexicon.py <sources> --output evals/lexicon.json 建立候選詞彙條目。
    3. 演算法閾值和可量化的公式。
    4. 高密度的非顯著失敗模式（「隱藏地雷」）清單。

---

4. 階段 1：環境與工具探索（區域 1 閘門）

在撰寫任何文件之前，請複製並執行此探索步驟：

• 步驟 1.1（探查環境與工具）：執行隨附的探索腳本：

  python3 scripts/discover_env.py
  

  （在 Windows PowerShell 上，請使用 python3 scripts/discover_env.py）
  • 檢查輸出以了解檢測到的作業系統、可用的 CLI 二進位檔（git、docker、python 等）以及活躍的 MCP 伺服器。
  • 如果候選技能涉及外部服務（例如 Figma、GitHub、Postgres），請檢查環境中是否存在相符的 MCP 工具或 CLI。

---

5. 階段 2：靜態工作空間探索與 OMSC 分類

• 步驟 2.1（靜態上下文讀取）：檢查活躍的儲存庫設定檔（package.json、pyproject.toml、Cargo.toml、.env.example、git 歷史記錄）。
  • 硬性規則：對於任何可以透過讀取工作空間中的檔案來發現的語言、框架或工具資訊，絕不向使用者提問。
• 步驟 2.2（QA 檢查點，每個階段強制執行）： 遵循 references/qa_checkpoints.md。僅有階段 2 的分類是不夠的。在每個檢查點，呈現一個 5 行的決策摘要，最多問 2 個問題並提供（推薦）的預設值，然後記錄它：

  python3 scripts/record_qa.py evals/qa-checkpoints.json --checkpoint teardown-domain --summary "niche, antidote, top footguns" --question "Is the niche boundary right? (Recommended: yes)" --confirmed
  

  • 檢查點 1，在階段 0 之後：teardown-domain，利基市場、競爭者、漏洞、優勢、解毒劑、主要地雷。
  • 檢查點 2，在架構設計之後、起草之前：架構、六層結構、路由表、腳本清單、參考文件清單、它不會做的事。
  • 檢查點 3，在草擬工作流程之後、閘門之前：draft-workflow，依序步驟、決策表、反合理化條目、輸入/輸出範例。
  • 檢查點 4，在閘門之後、打包之前：gates，稽核等級、安全性、壓力藉口已關閉、基線差異、渲染 QA。
  • 檢查點 5，在發布之前、觸發器與套件之後：ship，觸發結果、套件內容、守門員狀態、存根/路由器狀態（如適用）。
  • 對於高影響範圍、商業用途或互斥架構：等待使用者在該檢查點的回覆後再繼續。對於低影響範圍：允許呈現摘要並按照推薦的預設值繼續，但摘要和預設答案仍必須被記錄。沒有記錄的檢查點等於沒有發生。
• 步驟 2.3（OMSC 模糊過濾器）：
  • 檢查目標、指標、範圍或約束條件是否包含阻斷性未知數（references/decision_matrices_and_escalation.md）。
  • 如果是低影響範圍 / 標準工作流程：立即使用領域預設值繼續。問 0 個問題。
  • 如果是高影響範圍 / 互斥 UX 分支：暫停並最多問 1 到 3 個簡潔問題：
    1. 在最安全的預設選項上附加 (Recommended)。
    2. 提供 2–3 個帶有字母標籤的選項，並附上一行的權衡說明。

---

6. 階段 3：混合三區合成

撰寫完整的技能資料夾結構：<skill-name>/ 包含 SKILL.md、scripts/、references/ 和 assets/。

• 步驟 3.1（透過六層架構撰寫 SKILL.md）： 採用 agents/architect.md 角色，使用 assets/master_template.md 合成核心規範：
  • 位元組 0：立即以 --- 開頭。前文件中不得有角括號。
  • 層級 1（Token 1–500）：領域心智模型與不可協商的不變量。
  • 層級 2（Token 500–1,000）：工作路由決策表（消除 TOB/MDT 氣味）。
  • 層級 3（Token 1,000–1,500）：靜態探索與 OMSC 模糊分類。
  • 層級 4（Token 1,500–3,000）：帶有可複製 - [ ] 核取方塊的編號步驟。
  • 層級 5（Token 3,000–4,200）：高密度領域地雷與反合理化表。
  • 層級 6（Token 4,200–4,800）：此技能不做的事（消除 NG 氣味）。
  • 總體限制：控制在 450 行以內（<5,000 個 token）。
• 步驟 3.2（合成配套的確定性腳本與秘密模板）： 採用 agents/script_smith.md 角色：
  • 對於驗證：使用 assets/script_templates/validator_template.py 撰寫 scripts/validate.py。
  • 對於批次/破壞性變更：撰寫 scripts/validate_plan.py。
  • 如果 SKILL.md 中宣告了 requires_secrets:：在技能根目錄中撰寫 .env.example，其中包含儀表板 URL 和佔位值。
  • 確保腳本向標準輸出發射緊湊的 JSON，並在通過時以 exit 0 結束，失敗時以 exit 1 結束。
• 步驟 3.3（將深度文件委派給扁平參考文件）： 如果領域手冊、架構或次要指南超過 50 行，請將它們放在 references/<topic>.md 中。
  • 不變量：參考文件必須是扁平的（與 SKILL.md 恰好相隔一層）。

---

7. 階段 4：零 token 結構性 26 氣味稽核與評估

• 步驟 4.1（執行自動化靜態 lint 檢查）： 對新產生的技能目錄執行結構性 lint 檢查：

  python3 scripts/audit_skill.py path/to/generated-skill
  

• 步驟 4.2（執行確定性安全掃描）： 執行 AST 安全掃描器，以驗證沒有遠端程式碼執行、shell 注入或憑證洩漏：

  python3 scripts/security_scan.py path/to/generated-skill
  

• 步驟 4.3（修補所有違規與氣味）： 如果稽核報告任何違規，請採用 agents/smell_auditor.md 角色：
  • 合理化漏洞（RL）：新增一個明確的反合理化表，以反駁模型的藉口。
  • 選項自助餐（TOB）：將工具清單替換為每個情境的單一預設工具。
  • 篇幅過長（LSB）：將較長的程式碼片段移至 references/ 或 assets/。
  • 重新執行 audit_skill.py，直到狀態為 PASS 且等級為 A 或 A+。
• 步驟 4.4（執行經驗基準評估）： 執行測試案例以建立可驗證的任務通過率：

  python3 scripts/run_evals.py path/to/generated-skill
  

  • 對於修訂，採用 agents/comparator.md 角色，對基線進行雙盲比較。
• 步驟 4.5（壓力情境，強制執行）： 產生組合壓力情境，然後分別在「不使用技能」和「使用技能」的情況下執行，並記錄逐字藉口（references/pressure_scenarios.md）：

  python3 scripts/generate_pressure_scenarios.py path/to/generated-skill evals/pressure-scenarios.json
  

  • 產生的技能必須包含一個「思考 | 現實」表格，其中至少列出 3 個最常見的基線藉口。基線執行與使用技能執行結果相同，表示技能沒有改變任何東西：請勿發布。
• 步驟 4.6（使用技能與基線評分，強制執行）： 在同一輪中啟動使用技能和基線的執行，使用 agents/grader.md 進行評分，然後驗證評分者合約和發布閘門（references/baseline_grading.md）：

  python3 scripts/grade_baseline.py --with evals/grading-with.json --baseline evals/grading-baseline.json
  

  • 僅當使用技能的 pass_rate >= 80%、delta > 0 且無迴歸時才發布，除非 feedback.json 中記錄了人類豁免並附有理由。
• 步驟 4.7（渲染 QA，對於輸出強制執行）： 對技能產生的任何內容執行內容和檔案閘門檢查，對於視覺輸出則需要由人類進行視覺檢查（references/render_qa.md）：

  python3 scripts/render_qa.py path/to/generated-skill
  

  • 此腳本永遠不會聲明視覺檢查通過。視覺檢查必須由人類執行並記錄。

---

8. 階段 5：觸發器驗證與打包

• 步驟 5.1（測試觸發器的精確度與召回率）： 使用代表性正負面提示測試 YAML 描述：

  python3 scripts/test_skill_trigger.py path/to/generated-skill
  

• 步驟 5.2（描述最佳化，訓練/測試分割）： 將觸發查詢以 60% 訓練 / 40% 測試的比例分割，分別對每個分割執行觸發測試，並根據測試分數（而非訓練分數）選擇最佳描述。僅使用接近失誤的負面查詢；對於一個 PDF 技能，「寫一個費氏數列函數」是不好的負面查詢，而一個關於相鄰任務的長而雜亂的請求則是好的負面查詢：

  python3 scripts/eval_description_split.py path/to/generated-skill