安裝技能

Minara 內置了大量技能目錄，同時支持從任意 Git 倉庫安裝外部技能。外部技能由一個 SKILL.md 文件加少量清單組成，會被 vendored 到本地安裝目錄，Agent 可像調用內置技能一樣激活它們。

最簡方式：直接告訴 Minara

推薦在對話中直接告訴 Minara 要安裝哪個技能。Agent 能理解安裝意圖，會自動運行正確的命令，顯示許可證檢查結果，完成註冊，無需離開 REPL。

示例提示詞：

install this skill: https://github.com/acme/minara-skill-tax-reports

add the coinglass skill from github

vendor https://github.com/some-org/skills-monorepo, the one under
skills/invoice-parser

I want the polymarket trading skill — find and install it

upgrade my coingecko skill to latest

remove the tax_reports skill, I don't need it anymore

Minara 會在運行安裝前確認（安裝外部代碼屬於三級操作），顯示檢測到的許可證，並報告技能已註冊。下次啟動會話時，新技能即可激活。

推薦使用此流程，原因如下：

Agent 會替你處理 URL 解析、子路徑檢測和許可證判斷
許可證警告（UNKNOWN、⚠️ NONE、⚠️ PROPRIETARY）會在對話上下文中解釋，而不是作為難以理解的前綴字符
後續操作（"現在用 ETH 試試"）可在同一對話中自然銜接

CLI 方式（適合偏好命令行的場景）

如需腳本化或非交互式場景，可使用 minara skills 命令族：

minara skills list                          # 显示已安装的外部技能
minara skills add <git-url> [options]       # 安装新技能
minara skills upgrade [<id>]                # 拉取最新版本
minara skills remove <id>                   # 卸载

上述操作均作用於用戶級技能目錄（~/.minara/skills/）。不會修改倉庫源碼；已安裝的技能在 npm install 後依然保留，且不會提交到主代碼庫。

添加技能（CLI）

最簡形式只需提供 Git URL：

minara skills add https://github.com/acme/minara-skill-tax-reports

Minara 會克隆倉庫、檢測 SKILL.md 清單、檢查許可證、註冊技能，並打印摘要：

✓ Installed: acme.tax_reports
  License: MIT (OK)
  Tools:   0
  Prompt:  ~420 tokens

下次運行 minara chat 時技能即可使用。無需重啟 REPL，但當前已運行的會話不會感知到新技能。

多技能倉庫

單個 Git 倉庫可在不同子目錄下存放多個技能。使用 --subpath 指定其中一個：

minara skills add https://github.com/acme/skills-monorepo \
  --subpath skills/tax-reports

minara skills add https://github.com/acme/skills-monorepo \
  --subpath skills/invoice-parser \
  --id acme.invoices

覆蓋 id

已安裝技能的默認 id 由倉庫路徑派生。使用 --id 覆蓋：

minara skills add https://github.com/acme/foo --id acme.custom_name

當兩個已安裝技能 id 衝突，或希望使用更短的激活名稱時，可使用此選項。

固定版本

minara skills add https://github.com/acme/foo --ref v1.2.0
minara skills add https://github.com/acme/foo --ref main
minara skills add https://github.com/acme/foo --ref 3f1e2d4

Tag、分支或 commit SHA 均可，凡是 git checkout 支持的格式都行。

許可證檢測（重要）

每個技能都會掃描 LICENSE 文件。安裝程序會輸出以下結果之一：

結果	含義
`MIT` / `Apache-2.0` / 其他 SPDX	寬鬆開源許可，可安全使用
`UNKNOWN`	LICENSE 文件存在，但無法匹配已知 SPDX 標識符
`⚠️ NONE`	無 LICENSE 文件，請謹慎使用
`⚠️ PROPRIETARY`	檢測到禁止再分發的條款，安裝被阻止

經驗原則：看到 UNKNOWN 或 ⚠️ NONE 時，請先打開倉庫閱讀 LICENSE，再將技能用於生產環境。許可證缺失或模糊，意味著沒有使用該代碼的授權。

歷史案例：Anthropic 官方的 docx/pdf/pptx 技能附帶的許可證禁止"在服務以外保留副本"，此類技能不能被 vendored。Minara 改用 MIT 許可的替代方案（docx / pdf-lib / pptxgenjs）。

查看已安裝技能

minara skills list

acme.tax_reports           v0.3.1  MIT           ~420 tok
community.chart_generator  main    Apache-2.0    ~680 tok
local.my_workflow          —       UNKNOWN       ~210 tok

列含義：id · 固定版本 · 檢測到的許可證 · 提示詞大小。

超過 1500 token 的技能會被標記。若 activation: "always"，這類技能會在每輪對話中撐大系統提示詞，安裝前請審查其清單。

升級

minara skills upgrade                          # 升级所有技能
minara skills upgrade acme.tax_reports         # 升级单个技能

Minara 會拉取固定版本（或未指定版本時的 HEAD）的最新內容，重新驗證許可證，並報告提示詞大小或工具接口的變化：

↑ acme.tax_reports: v0.3.1 → v0.3.2
  Prompt: 420 → 445 tokens (+5.9%)
  Tools:  unchanged

若升級會導致許可證變更（如 MIT 變為專有許可），升級將被拒絕，保留舊版本，直到手動重新安裝。

卸載

minara skills remove acme.tax_reports

從 ~/.minara/skills/ 刪除克隆並註銷該技能。下次啟動 REPL 會話時不再可見。

技能來源

Minara 註冊表：由 Minara 團隊維護的精選技能
GitHub 上的 Cocoon-AI：持續增長的公共技能庫（Cocoon-AI organization）
自有 Git 服務：團隊內部技能可託管在任意自建 Git 服務器上，只要 Minara 進程能訪問該 URL 即可

外部技能與內置技能使用相同的 DomainSkill 接口。若想編寫技能而非僅安裝，請參閱貢獻指南 → 新增技能。

故障排查

"License: ⚠️ NONE"，需要擔心嗎？ 視倉庫情況而定。個人實驗項目通常問題不大；若要部署給用戶使用，請聯繫作者補充 LICENSE 文件。

"Skill failed to register" 通常是 SKILL.md frontmatter 格式有誤。運行 minara skills list，失敗的技能會顯示解析錯誤，可據此向上遊倉庫提 issue。

"Tool collision: name already registered" 兩個已安裝技能聲明瞭相同的工具名稱。使用 --id 重命名其中一個，或移除重複的技能。

"Not visible after adding" 含有 requires_env 的外部技能，在對應環境變量設置之前不會出現。檢查技能清單中列出的必填環境變量，並將其添加到 .env 中。