添加技能

技能分为两种。内置技能是你在本仓库中编写、并编译进二进制文件的 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

技能增加公共用户流程时，需要同步更新四种语言的相关功能或使用文档。