添加技能

技能分為兩種。內置技能是你在本倉庫中編寫、並編譯進二進制文件的 SKILL.md 包。外部技能是通過命令或 prompt 安裝的第三方引入包，無需改動代碼。本頁兩者都會介紹。

添加內置技能

內置技能是位於 apps/agent/src/skills/builtin/<id>/ 下的 SKILL.md 包。加載器（loadBuiltinPackageSkills）會自動發現它們，按 requires_env 做門控，並在每輪對話時提供給 agent。無需編輯 index.ts：發現過程只掃描 builtin/ 的直接子目錄，因此包必須放在下一層（嵌套更深的包會被靜默跳過）。

最小示例

創建 apps/agent/src/skills/builtin/my-new-skill/SKILL.md：

---
name: my-new-skill
description: "Pull research data from My Provider. Use when the user asks about X, Y, or Z."
metadata:
  minara:
    id: research.my_provider
    priority: 50
    tool_names: [my_provider_search, my_provider_detail]
    requires_env: [MY_PROVIDER_API_KEY]
    routing:
      keywords: ["my provider", X, Y]
---

You are the My Provider research skill. When the user asks about X, Y, or Z,
call `my_provider_search` and summarize the results.

Prefer fresh data over cached. Cite source URLs.

加載器在啟動時會把這段 frontmatter 解析為 DomainSkill。頂層的 name + description 遵循 skill-creator 標準；所有 Minara 專有字段都放在 metadata.minara.* 下。較深的內容拆分到 references/<area>.md（模型按需讀取），frontmatter 無法清晰表達的結構化字段放進 SKILL.config.json 旁掛文件。

約定

正文：軟上限約 5000 字符。把較長的指引拆到 references/<area>.md，不要撐大包正文。
description：內置技能上限 200 字符。寫一句忠實描述"做什麼 + 何時使用"的話，並帶上強且不衝突的關鍵詞，讓路由能把它浮現出來。
tool_names：必須能在工具註冊表中解析。它們構成激活白名單，因此保持列表精簡。
requires_env：只要列出的某個變量缺失，註冊表就會隱藏該技能。這讓運維無需設置每個密鑰也能運行 agent。
風險：技能本身不帶風險等級。每個工具聲明自己的 PermissionTier，由等級門在工具調用層執行確認。
目錄守衛：在同一次提交中，把新的 id 加入 builtin-catalog-guard.test.ts 的 EXPECTED_IDS。

參考示例

minara-perps/ （工具密集型）
deep-research/ （prompt 密集型）
analysis/ （方法論視角拆分到 references/）

內聯 TS 例外

有一個內置技能以內聯 TypeScript 而非 SKILL.md 包的形式提供：automation，它的 prompt 在運行時渲染實時的 Custom Agents 目錄。它通過 apps/agent/src/skills/builtin/index.ts 裡的 BUILTIN_SKILLS 註冊。只有當內容確實需要運行時動態生成時才用內聯 TS，絕不因為 prompt 短就用它。

添加外部技能

外部技能位於 apps/agent/src/skills/external/*，是帶 .minara-skill.json 清單的引入 SKILL.md 包。你安裝它們，而不是編寫它們：

minara skills add <git-url> [--subpath <dir>] [--id <id>]

安裝會克隆該包、檢測其許可證、記錄到 .minara-skill.json，並拒絕專有許可證下的內容。隨後 buildExternalDomainSkills() 在啟動時從 SKILL.md frontmatter 構建出 DomainSkill，因此外部技能與內置技能走同一套註冊表和等級門。

完整的面向用戶的流程（包括在對話中通過 prompt 安裝），見安裝技能。

當你想要由上游維護的第三方包（如 coingecko、hyperliquid）、非 TypeScript 的參考實現（shell、Python），或獨立於 agent 二進制更新的內容時，就用外部技能。當一種能力兩種形式都有時，優先選擇內置技能。

驗證貢獻

請測試包加載、聲明的 ID、路由措辭和每個被引用的工具名。以提示詞為主的技能還應增加聚焦行為測試或 Eval，用來證明它何時激活、需要哪些證據。

pnpm --filter @minara/agent exec vitest run tests/unit/skills/builtin-catalog-guard.test.ts
pnpm --filter @minara/agent typecheck
pnpm --filter @minara/agent build

技能增加公共用戶流程時，需要同步更新四種語言的相關功能或使用文檔。