管理 Tracecat 技能
Tracecat MCP 提供六個技能工具：list_skills、get_skill、prepare_skill_download、prepare_skill_upload、complete_skill_upload 和 publish_skill。
寫入操作是暫存（staged）而非內嵌（inlined）的。檔案位元組絕不會以工具參數的形式傳遞：prepare_skill_upload 只接收 metadata——路徑、SHA-256、大小、內容類型——並為每個檔案回傳一個短暫有效的 PUT URL；位元組經由純 HTTP 傳送到那些 URL；之後 complete_skill_upload 會附加這些暫存的 blob 並取代草稿。請不要尋找 content_base64 參數，也不要為了傳送而將檔案位元組讀入上下文。
內建的輔助腳本消除了容易出錯的手動部分：安全目錄走訪、拒絕符號連結、強制根目錄為 SKILL.md，以及 SHA-256 摘要。
上傳技能
以下四個步驟可用於建立新技能或取代現有技能。唯一的差別在於 prepare_skill_upload 接收的識別參數。
-
使用
list_workspaces解析目標工作區，然後呼叫list_skills。對於新技能，確認名稱未被使用——省略skill_id總是會建立新資料列，因此第二次建立會產生兩個同名但 slug 不同的技能。對於現有技能，取得其skill_id。 -
建立 metadata 陣列：
python3 <this-skill-dir>/scripts/upload_skill_files.py metadata <local-skill-dir>它會逐字輸出
files陣列：每個檔案一個條目，包含path、sha256、size_bytes和content_type。不包含檔案內容。 -
使用
workspace_id和該files陣列呼叫prepare_skill_upload，再加上下列其中一項：name（以及可選的description）且不包含skill_id，以建立技能；或skill_id且不包含name/description，以取代現有技能的草稿。
對於建立操作，請傳遞與本機 frontmatter 中宣告的相同
name——伺服器在驗證之前會將name和description合併到儲存的根目錄SKILL.mdfrontmatter 中，因此參數不符會靜默地改寫儲存的內容。回應中包含
skill_id、base_revision、created，以及每個檔案的upload_id、upload_url、method、headers和expires_at。 -
對於每個檔案，使用回傳的 method 和 headers，將原始位元組直接從磁碟
PUT到其upload_url。這些 URL 是短暫有效的；請檢查expires_at，如果過期則重新準備，不要重試已過期的 URL。 -
使用
workspace_id、skill_id、步驟 3 中的base_revision，以及一個包含每個檔案{"path": ..., "upload_id": ...}的files陣列來呼叫complete_skill_upload。這會取代草稿，但不會發佈。 -
當技能應該可以被附加到預設集時，使用該
skill_id呼叫publish_skill。未發佈的草稿無法被綁定。
base_revision 是並發保護。如果收到 draft_revision_conflict，表示自步驟 3 以來有人編輯了草稿——請呼叫 get_skill 查看目前的 draft_revision，以及完整樹狀取代會刪除哪些內容，然後重新準備。
更新生效中的技能
如果修復在 complete_skill_upload 之後停止，則不會改變任何 agent 執行的內容。需要依序執行三個步驟：
- 使用
skill_id呼叫prepare_skill_upload→PUT位元組 →complete_skill_upload。這會取代草稿，但不會發佈。 - 使用相同的
skill_id呼叫publish_skill。技能是有版本的；這會建立一個新的不可變版本，並移動技能的current_version_id。 - 使用使用中預設集的
skills列表（與之前相同的{"skill_id": ...}條目）呼叫update_agent_preset。每個綁定在寫入時都會重新固定到該技能的目前已發佈版本，因此在步驟 2 之前綁定的預設集會繼續執行舊版本，直到此呼叫改寫它。
省略步驟 3 是典型的失敗情境：新版本已存在，但預設集從未看到它。
透過重新擷取來驗證。不帶 path 參數的 get_skill 會回傳草稿清單——路徑、摘要、大小、draft_revision、is_publishable、validation_errors——並且絕不回傳檔案內容；帶有 path 的 get_skill 會讀取一個檔案，如果檔案是小的 UTF-8 文字則內嵌回傳。list_skills 顯示技能的 current_version_id；get_agent_preset 顯示 skills[].skill_version_id 和 skills[].skill_version。確認兩者都已更新。
這是常規的、可逆的工作。每個已發佈的版本都是不可變的且仍然可以綁定，因此錯誤的推送可以透過發佈修正後的樹狀結構並重新綁定來撤銷。與其描述風險，不如直接執行它；將謹慎保留給那些實際上無法撤銷的操作。
宣告技能的工具
技能本身帶有其工具。在根目錄 SKILL.md 的 frontmatter 中，透過 metadata.tools 宣告它們，可以是 registry action 名稱或 mcp.<slug> / mcp.<slug>.<tool> 條目，每個技能最多 64 個：
---
name: slack-triage
description: 在 Slack 中發佈和回覆討論串的處理更新。
metadata:
tools:
- tools.slack.post_message
- tools.slack.list_replies
---
技能所附加的每個預設集，除了自身的 actions 允許清單之外，還會收到這些工具。一旦預設集解析完成，這些工具就會被授予，無論模型是否開啟該技能；只有技能的指令會按需載入。
當工具自然地形成群組並且多個 agent 重複使用它們時，比起將相同的工具列在每個預設集的 actions 中，更偏好此做法——一次編輯和重新發佈就能更新所有使用中的預設集。當工具僅特定於某個 agent 時，將其保留在該預設集的 actions 中。
一個注意事項：預設集的 namespaces 過濾器會套用於聯集中的 registry 工具，並靜默地阻擋在其外的工具。將技能附加到有命名空間限制的預設集後，請檢查 get_agent_preset 上的 tool_policy.blocked_tools。技能宣告的 MCP 工具（mcp.<slug> / mcp.<slug>.<tool>）不會被 namespaces 過濾，也不會出現在那裡。
變更 metadata.tools 會改變 agent 可以執行的內容，因此它遵循與任何其他修復相同的三個步驟：取代草稿、publish_skill，然後 update_agent_preset 以重新固定綁定。讀取結果預設集時，授予的工具會以一個平面列表的形式顯示在 tool_policy.actions 中，沒有每個技能的來源資訊——您可以驗證的是這個聯集。
大小
位元組不再通過模型上下文，但每個檔案仍有伺服器端的大小限制，而且整個樹狀結構在檔案小而僅含文字時更容易審查。
- 偏好使用 Markdown、YAML 和腳本。將大型二進位資源託管在其他地方並透過引用方式使用。
- 將詳細的說明移到
references/檔案中，讓 agent 按需讀取，而不是放在SKILL.md中。 - 如果樹狀結構過大難以理解，請將技能本身拆分為兩個技能。請不要將一個樹狀結構分散到多個
complete_skill_upload呼叫中——每次呼叫都會取代整個草稿，因此部分呼叫會刪除所有遺漏的內容。
硬性規則
- 省略
skill_id會建立；傳遞skill_id則會取代。絕對不要對已存在的名稱進行建立——slug 重試會讓重複的建立成功而不是失敗。 - 每次寫入都會取代整個草稿。本機目錄中不存在的檔案會從技能中刪除。始終傳送完整的樹狀結構。
- 在呼叫
complete_skill_upload之前上傳所有已準備的檔案，並將所有路徑連同其upload_id一起傳入。 - 絕不要將檔案位元組或 base64 內嵌到工具參數中，也絕不要將上傳或下載 URL 的位元組讀入上下文。從磁碟串流傳輸。
- 發佈不會移動現有的預設集綁定。重新寫入預設集的
skills列表以選取新版本。 - 拒絕符號連結檔案和目錄，並且絕不要發送所選技能根目錄之外的內容。輔助腳本會強制執行此規則；請不要繞過它。
- 根檔案必須是
SKILL.md，位於最上層，並且是有效的 UTF-8。伺服器會拒絕不包含此檔案的檔案集。 - 如果用戶端無法執行本機腳本，請說明情況並提供使用者要執行的輔助命令。不要取代由模型生成的摘要。
參考資料
- 閱讀 references/upload-contract.md 以了解實際的請求和回應格式，以及此途徑的保護範圍。
- 當上傳、發佈或預設集重新綁定未成功時，閱讀 references/troubleshooting.md。