Grasshopper MCP Workflow

# AI 代理技能識別機制說明 ## 🔍 技能識別流程 AI 代理（如 Claude、Cursor、Windsurf、Aider）通過以下機制識別和使用技能： ### 1. AGENTS.md 文件的作用 `AGENTS.md` 是技能系統的核心配置文件，包含： - **技能列表** (`<available_skills>`): 所有已安裝技能的元數據 - **使用說明** (`<usage>`): 告訴 AI 如何調用技能 - **技能描述**: 每個技能的觸發條件 ### 2. 技能識別的三級載入系統 根據 OpenSkills 的設計，技能使用**漸進式披露**（Progressive Disclosure）機制： ``` Level 1: 元數據（始終在上下文中） ↓ AI 讀取 AGENTS.md 中的技能描述 ↓ 判斷是否需要使用技能 ↓ Level 2: SKILL.md 主體（觸發時載入） ↓ 執行 Bash("openskills read grasshopper-workflow") ↓ 載入 SKILL.md 的完整內容 ↓ Level 3: 參考資源（按需載入） ↓ 根據 SKILL.md 中的引用 ↓ 載入 references/ 或 scripts/ 中的文件 ``` ## 📋 當前 grasshopper-workflow 技能的識別機制 ### 技能元數據（Level 1） 在 `AGENTS.md` 中，您的技能定義為： ```xml <skill> <name>grasshopper-workflow</name> <description>"Grasshopper 參數化建模工作流程工具。當需要通過 MCP 協議與 Grasshopper 交互、創建和管理組件、建立連接、設置參數、執行完整建模工作流程時使用。適用於：(1) 從 MMD 文件創建 Grasshopper 定義, (2) 執行 placement_info.json 工作流程, (3) 批量管理組件和連接, (4) 參數化建模的自動化流程, (5) 解析 component_info.mmd 和 part_info.mmd 文件"</description> <location>project</location> </skill> ``` ### 觸發條件 AI 代理會在以下情況識別並使用此技能： 1. **關鍵詞匹配**: - "Grasshopper" - "MMD 文件" / "component_info.mmd" / "part_info.mmd" - "placement_info.json" - "創建組件" / "連接組件" - "參數化建模" - "MCP 協議" 2. **任務類型匹配**: - 從 MMD 文件創建 Grasshopper 定義 - 執行 placement_info.json 工作流程 - 批量管理組件和連接 - 解析 component_info.mmd 或 part_info.mmd - 設置 Grasshopper 組件參數 3. **工作流程匹配**: - 需要執行完整的 Grasshopper 建模流程 - 需要自動化 Grasshopper 操作 ## 🚀 實際使用流程 ### 範例 1: 用戶請求解析 MMD 文件 **用戶請求:** ``` 請幫我解析 component_info.mmd 文件並生成 placement_info.json ``` **AI 代理的識別過程:** 1. **讀取 AGENTS.md** (自動載入) - 看到 `grasshopper-workflow` 技能 - 描述中包含 "解析 component_info.mmd" 和 "執行 placement_info.json 工作流程" - ✅ 匹配成功 2. **調用技能** (AI 自動執行) ```bash openskills read grasshopper-workflow ``` 3. **載入技能內容** - SKILL.md 主體內容被載入 - AI 看到工作流程步驟和快速開始範例 4. **按需載入參考文檔** - AI 看到 SKILL.md 中引用 `references/workflow_steps.md` - 如果需要，會讀取該文件獲取詳細步驟 5. **執行任務** - AI 使用技能中的 Python 腳本 - 調用 `scripts/parser_utils.py` 解析 MMD - 調用 `scripts/placement_executor.py` 執行流程 ### 範例 2: 用戶請求創建 Grasshopper 組件 **用戶請求:** ``` 幫我在 Grasshopper 中創建一個 Number Slider 組件 ``` **AI 代理的識別過程:** 1. **關鍵詞匹配** - "Grasshopper" → 匹配 - "創建組件" → 匹配技能描述中的 "創建和管理組件" - ✅ 觸發 `grasshopper-workflow` 技能 2. **載入技能** - AI 執行 `openskills read grasshopper-workflow` - 看到組件管理的說明和範例 3. **使用技能內容** - 參考 `references/api_reference.md` 中的 ComponentManager 說明 - 使用 `scripts/component_manager.py` 中的方法 - 執行組件創建操作 ## 📝 AGENTS.md 中的使用說明 根據 `AGENTS.md`，AI 代理會： ```markdown When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. How to use skills: - Invoke: Bash("openskills read <skill-name>") - The skill content will load with detailed instructions - Base directory provided in output for resolving bundled resources ``` 這意味著： 1. **自動檢查**: AI 會自動檢查所有可用技能 2. **智能匹配**: 根據技能描述匹配用戶請求 3. **按需載入**: 只在需要時載入技能內容 4. **資源訪問**: 可以訪問 scripts/ 和 references/ 中的資源 ## 🎯 技能描述的關鍵作用 **技能描述是唯一的觸發機制**，因為： - ✅ **始終在上下文中**: 技能描述在 AGENTS.md 中，AI 總是能看到 - ✅ **觸發判斷依據**: AI 根據描述判斷是否需要使用技能 - ✅ **不載入主體**: SKILL.md 主體只在觸發後才載入（節省 token） ### 您的技能描述分析 ```markdown "Grasshopper 參數化建模工作流程工具。當需要通過 MCP 協議與 Grasshopper 交互、 創建和管理組件、建立連接、設置參數、執行完整建模工作流程時使用。適用於： (1) 從 MMD 文件創建 Grasshopper 定義, (2) 執行 placement_info.json 工作流程, (3) 批量管理組件和連接, (4) 參數化建模的自動化流程, (5) 解析 component_info.mmd 和 part_info.mmd 文件" ``` **觸發關鍵詞:** - ✅ "Grasshopper" - 明確的領域標識 - ✅ "MCP 協議" - 技術棧標識 - ✅ "創建和管理組件" - 功能描述 - ✅ "MMD 文件" - 文件類型 - ✅ "placement_info.json" - 特定文件格式 - ✅ "component_info.mmd" / "part_info.mmd" - 具體文件名 ## 🔄 完整識別流程圖 ``` 用戶請求 ↓ AI 讀取 AGENTS.md（自動） ↓ 檢查 <available_skills> 列表 ↓ 匹配技能描述中的關鍵詞 ↓ 判斷是否需要使用技能 ↓ [是] → 執行 Bash("openskills read grasshopper-workflow") ↓ 載入 SKILL.md 主體內容 ↓ 根據 SKILL.md 中的引用 ↓ 按需載入 references/ 或 scripts/ ↓ 執行任務 ``` ## 💡 最佳實踐 ### 1. 技能描述要清晰 ✅ **好的描述**（您的技能）: - 明確說明功能領域（Grasshopper 參數化建模） - 列出具體使用場景（5 個適用情況） - 包含關鍵技術詞彙（MCP 協議、MMD 文件） ❌ **不好的描述**: - "一個有用的工具"（太模糊） - 只說功能不說場景（缺少觸發條件） ### 2. 使用具體的關鍵詞 您的技能描述包含： - **領域**: Grasshopper、參數化建模 - **技術**: MCP 協議 - **文件類型**: MMD、JSON - **具體文件名**: component_info.mmd、part_info.mmd、placement_info.json - **操作類型**: 創建、管理、連接、設置、解析 ### 3. 保持 SKILL.md 簡潔 - ✅ 主體內容簡潔（<500 行） - ✅ 詳細內容放在 references/ - ✅ 腳本放在 scripts/ - ✅ 使用漸進式載入 ## 🧪 測試技能識別 您可以通過以下方式測試 AI 是否會識別您的技能： ### 測試請求 1: 明確匹配 ``` 請幫我從 component_info.mmd 生成 placement_info.json ``` **預期**: ✅ AI 應該識別並使用 `grasshopper-workflow` 技能 ### 測試請求 2: 部分匹配 ``` 我需要創建一些 Grasshopper 組件 ``` **預期**: ✅ AI 應該識別（匹配 "創建和管理組件"） ### 測試請求 3: 間接匹配 ``` 幫我解析一個 MMD 文件 ``` **預期**: ✅ AI 應該識別（匹配 "解析 component_info.mmd"） ## 📊 當前狀態 您的 `grasshopper-workflow` 技能： - ✅ **已安裝**: `.claude/skills/grasshopper-workflow/` - ✅ **已同步**: 在 `AGENTS.md` 中可見 - ✅ **描述完整**: 包含所有關鍵觸發條件 - ✅ **結構完整**: SKILL.md + 11 個腳本 + 4 個參考文檔 - ✅ **可被識別**: AI 代理可以自動識別並使用 ## 🎯 總結 AI 代理識別技能的機制： 1. **自動讀取 AGENTS.md** - 技能列表始終在上下文中 2. **智能匹配描述** - 根據技能描述中的關鍵詞匹配用戶請求 3. **按需載入內容** - 只在需要時載入 SKILL.md 和資源文件 4. **執行任務** - 使用技能中的腳本和文檔完成任務 您的技能已經完全配置好，AI 代理可以自動識別並使用它！ --- ## 🖥️ Cursor IDE 中的使用 ### Cursor 與 OpenSkills Cursor 是一個 AI 代碼編輯器，也支持 OpenSkills 技能系統。在 Cursor 中使用技能的機制與 Claude Desktop 基本相同，但有一些 Cursor 特定的注意事項。 ### Cursor 中的技能識別 Cursor 中的 AI 代理（通常是 Claude）會： 1. **自動讀取 AGENTS.md** - Cursor 會自動掃描項目根目錄的 `AGENTS.md` 文件 - 讀取所有可用技能的描述 2. **智能匹配用戶請求** - 當您在 Cursor 的聊天界面中提出請求時 - AI 會檢查 `AGENTS.md` 中的技能列表 - 根據技能描述匹配您的請求 3. **自動調用技能** - 如果匹配成功，AI 會執行 `openskills read <skill-name>` - 載入技能內容到對話上下文中 ### Cursor 中的配置 #### 1. 確保 AGENTS.md 在項目根目錄 ``` your-project/ ├── AGENTS.md ← Cursor 會自動讀取 ├── .claude/ │ └── skills/ │ └── grasshopper-workflow/ └── ... ``` #### 2. 使用 Universal 模式（可選） 如果您同時使用 Cursor 和其他 AI 代理，可以使用 universal 模式： ```powershell # 安裝到 .agent/skills/（適用於所有代理） openskills install anthropics/skills --universal # 同步到 AGENTS.md openskills sync --universal ``` 這樣可以： - ✅ 避免與 Cursor 的內建功能衝突 - ✅ 在多個 AI 代理間共享技能 - ✅ 保持 `.claude/` 目錄專用於 Claude Code #### 3. 驗證 Cursor 可以訪問技能 在 Cursor 的終端中測試： ```powershell # 檢查技能是否安裝 openskills list # 測試讀取技能 openskills read grasshopper-workflow ``` ### Cursor 中的使用範例 #### 範例 1: 在 Cursor 聊天中請求 **您在 Cursor 聊天中輸入:** ``` 請幫我從 component_info.mmd 生成 placement_info.json ``` **Cursor AI 的處理:** 1. 讀取 `AGENTS.md`（自動） 2. 看到 `grasshopper-workflow` 技能描述 3. 匹配成功（包含 "MMD" 和 "placement_info.json"） 4. 執行 `openskills read grasshopper-workflow` 5. 使用技能中的腳本完成任務 #### 範例 2: 在 Cursor 中編寫代碼 **您在 Cursor 中請求:** ``` 幫我寫一個腳本來解析 component_info.mmd ``` **Cursor AI 的處理:** 1. 識別需要使用 `grasshopper-workflow` 技能 2. 載入技能內容 3. 參考 `references/api_reference.md` 中的 MMDParser 說明 4. 使用 `scripts/parser_utils.py` 作為參考 5. 生成或修改代碼 ### Cursor 與 Claude Code 的區別 | 特性 | Claude Code | Cursor | |------|-------------|--------| | AGENTS.md 位置 | 項目根目錄 | 項目根目錄 | | 技能目錄 | `.claude/skills/` | `.claude/skills/` 或 `.agent/skills/` | | 自動識別 | ✅ 是 | ✅ 是 | | 技能調用方式 | `Bash("openskills read ...")` | `Bash("openskills read ...")` | | 內建插件 | 可能有衝突 | 無衝突（使用 universal 模式） | ### Cursor 最佳實踐 #### 1. 使用項目級安裝（推薦） ```powershell # 在項目根目錄 openskills install anthropics/skills openskills sync ``` 這樣每個項目都有獨立的技能配置。 #### 2. 使用 Universal 模式（多代理環境） 如果您同時使用 Cursor、Windsurf、Aider： ```powershell # 安裝到 .agent/skills/ openskills install anthropics/skills --universal openskills sync --universal ``` #### 3. 驗證 Cursor 可以訪問 在 Cursor 的終端中： ```powershell # 檢查 AGENTS.md 是否存在 Test-Path AGENTS.md # 檢查技能是否安裝 openskills list # 測試讀取 openskills read grasshopper-workflow ``` ### Cursor 中的調試 如果 Cursor 無法識別技能： 1. **檢查 AGENTS.md 位置** ```powershell # 確保在項目根目錄 Get-Location Test-Path AGENTS.md ``` 2. **檢查技能安裝** ```powershell openskills list ``` 3. **重新同步** ```powershell openskills sync -y ``` 4. **檢查 Cursor 設置** - 確保 Cursor 可以訪問項目文件 - 檢查是否有文件權限問題 ### Cursor 特定提示 1. **終端集成**: Cursor 的終端可以直接執行 `openskills` 命令 2. **文件監控**: Cursor 會監控 `AGENTS.md` 的變化 3. **上下文管理**: Cursor 會自動管理技能載入的上下文 4. **多項目支持**: 每個項目可以有獨立的技能配置 ### 總結：Cursor 中的使用 在 Cursor 中使用 OpenSkills 技能： - ✅ **機制相同**: 與 Claude Desktop 使用相同的識別機制 - ✅ **自動識別**: Cursor AI 會自動讀取 `AGENTS.md` 並匹配技能 - ✅ **無需額外配置**: 只要 `AGENTS.md` 在項目根目錄即可 - ✅ **支持 Universal 模式**: 可以與其他 AI 代理共享技能 您的 `grasshopper-workflow` 技能在 Cursor 中也可以正常使用！