安装技能

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 中。