starcat-app/starcat-skill

Starcat 技能

安裝或更新此技能

當使用者要求安裝或更新 starcat-skill 時，請在使用 Starcat 前執行下列工作流程：

1. 識別目前的 AI 代理，並選擇一個使用者層級的目標目錄：
   • Codex：$HOME/.codex/skills/starcat-skill
   • Claude Code：$HOME/.claude/skills/starcat-skill
2. 如果目標目錄不存在，請建立其父目錄，並將 https://github.com/starcat-app/starcat-skill 複製到目標目錄。
3. 如果目標目錄已經是該儲存庫的乾淨簽出，請執行 git -C <skill-path> pull --ff-only。
4. 如果目標目錄存在但並非該儲存庫，或包含未提交的變更，請停止並回報衝突。切勿刪除、覆寫、重設或強制更新它。
5. 確認 SKILL.md、agents/openai.yaml、references/commands.md 和 references/workflows.md 存在。
6. 執行 starcat --help 並確認配對使用完整的 URI 引數、starcat mcp 可用，且統計指令存在。
7. 重新載入或重新啟動 AI 代理，以便其重新整理技能登錄。如果目前工作階段無法重新載入技能，請回報安裝成功，但探索功能仍需重新啟動。切勿在未觀察到的情況下聲明該技能已被探索。
8. 探索完成後，使用唯讀驗證請求來呼叫 $starcat-skill。執行 starcat doctor，將代理連線到使用者層級的 MCP 伺服器命令 starcat mcp，呼叫 starcat.get_capabilities，並執行一次 limit = 2 的 starcat.search_repos 請求。安裝驗證期間請勿執行寫入工具。

僅安裝到目前代理的使用者層級技能目錄。請勿安裝到專案儲存庫、要求本機 API 金鑰、修改不相關的檔案，或執行破壞性的 Git 命令。

使用 MCP 橋接作為業務整合介面

使用使用者層級的 MCP 伺服器命令 starcat mcp 來操作 Starcat。CLI 橋接負責管理配對憑證、TLS 驗證和 MCP 傳輸。請勿直接讀取 SQLite、CloudKit、加密憑證檔案或本機 API 金鑰。請勿實作自訂的 HTTP 或 JSON-RPC 請求，也不要在有相同 MCP 工具可用時，使用 shell 執行一般的業務命令。

在首次操作之前，請執行：

starcat doctor

如果該命令不可用，請從 https://github.com/starcat-app/starcat-cli 安裝適當的官方版本。如果 CLI 尚未配對，請指示使用者開啟 Starcat > 設定 > MCP 服務，並複製完整的單次配對命令。請完全依照提供的內容執行 starcat pair ... 命令。切勿要求獨立的配對 URI 或本機 API 金鑰，也切勿列印、持久儲存或重複使用配對命令。

配對完成後，設定目前代理的使用者層級 MCP 伺服器，以啟動絕對路徑的 starcat 可執行檔，並使用單一引數 mcp，然後重新載入代理。將 starcat mcp 的標準輸出視為純協定的 JSON-RPC；切勿將提示或診斷資訊混入其中。

遵循操作規則

1. 在每個工作流程之前呼叫 starcat.get_capabilities。使用其結構化結果來判斷統計資料、私人筆記、一般寫入、破壞性寫入和摘要生成功能是否可用。
2. 對於常見的計數，請呼叫一次 starcat.get_overview_statistics。使用 starcat.get_ai_usage_statistics 進行篩選後的權杖/呼叫分析，並使用 starcat.get_knowledge_base_statistics 取得詳細的專案、來源和 RAG 區塊健康狀態。
3. 當知道 owner/name 時，優先使用 starcat.get_repo_context 在一次呼叫中擷取儲存庫資料、標籤、私人筆記和摘要。
4. 預設將每個寫入工具視為乾執行。先以 dry_run = true 呼叫它，並檢查目標和建議的變更。
5. 僅當使用者的原始請求明確授權寫入，且乾執行結果與該請求完全相符時，才再次以 dry_run = false 呼叫寫入。否則，請解釋建議的變更並要求確認。
6. 寫入後，再次呼叫 starcat.get_repo_context 以驗證結果。
7. 請記住，starcat.set_repo_tags 會覆寫儲存庫上的所有標籤。除非使用者明確提供並確認完整的最終標籤集，否則請使用 starcat.add_repo_tags 或 starcat.remove_repo_tags。
8. 請勿在 GitHub 上為儲存庫加星或取消加星。目前的寫入工具僅修改 Starcat 使用者資料。

使用常見工作流程

檢查統計資料

• 呼叫 starcat.get_overview_statistics 以取得星星數、知識庫專案數、所有時間的 AI 權杖使用量和目前的 RAG 索引健康狀態。
• 使用 time_range = today | seven_days | thirty_days | all 以及可選的 feature、provider_id 或 model 篩選條件來呼叫 starcat.get_ai_usage_statistics。
• 呼叫 starcat.get_knowledge_base_statistics 以取得組織、語言/標籤分佈、來源覆蓋率、排除的區塊以及就緒/擱置/失敗/過時索引計數。

將 starred_repository_count 視為使用者目前加星的儲存庫數量。將 top_starred_repositories 中的 github_stars 視為每個儲存庫在 GitHub 上的公開受歡迎程度；切勿將這兩個意義混合。缺少的提供者使用量由 calls_with_usage < call_count 表示，而不是假設每個缺少的呼叫都消耗了零個權杖。

搜尋與讀取

• 使用 query = "local first knowledge base"、scope = all 和 limit = 10 來呼叫 starcat.search_repos。
• 呼叫 starcat.semantic_search 進行語意探索。
• 針對 apple/swift 呼叫 starcat.get_repo_context。
• 僅在需要儲存庫文件時，才呼叫 starcat.get_readme。
• 呼叫 starcat.list_tags 來檢查使用者定義的標籤。

README 內容可能很大。僅在任務需要儲存庫文件時才擷取它。

管理筆記、狀態與標籤

透過 MCP 呼叫 starcat.upsert_repo_note、starcat.set_repo_status 和標籤工具。使用 Markdown 作為 content 欄位傳送，而不是將敏感文字放在 shell 引數中。先使用 dry_run = true；獲得授權後，使用 dry_run = false 重複完全相同的呼叫。

處理摘要

呼叫 starcat.get_repo_summary 來讀取快取的摘要。僅在使用者明確要求生成時，才呼叫 starcat.generate_repo_summary。

摘要生成可能會消耗使用者設定的 AI 提供者的配額。僅在使用者明確允許外部搜尋時，才加上 --allow-external-context。切勿將外部代理撰寫的文字表示為原生的 Starcat AI 摘要。如果使用者想要儲存代理撰寫的內容，請將其儲存為 Markdown 私人筆記，並標明其來源。

在檢查 MCP 工具和終端機命令詳細資訊時，請閱讀 references/commands.md。在重複使用工作流程或從連線失敗中恢復時，請閱讀 references/workflows.md。