スキルの追加

スキルには 2 種類あります。組み込みスキルは、このリポジトリで書いてバイナリにコンパイルする SKILL.md パッケージです。外部スキルは、コマンドやプロンプトでインストールするサードパーティのパッケージで、コード変更は不要です。このページでは両方を扱います。

組み込みスキルを追加する

組み込みスキルは apps/agent/src/skills/builtin/<id>/ 配下の SKILL.md パッケージです。ローダー（loadBuiltinPackageSkills）が自動的に検出し、requires_env でゲーティングして、ターンごとに agent へ渡します。index.ts を編集する必要はありません。検出は builtin/ の直下のサブディレクトリだけを走査するため、パッケージは 1 階層下に置く必要があります（さらに深くネストしたパッケージは黙って無視されます）。

最小の例

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/ （プロンプト中心）
• analysis/ （方法論レンズを references/ に分割）

インライン TS の例外

1 つの組み込みは SKILL.md パッケージではなくインライン TypeScript として提供されます。automation で、そのプロンプトは実行時にライブの Custom Agents カタログをレンダリングします。apps/agent/src/skills/builtin/index.ts の BUILTIN_SKILLS で登録します。内容が本当に実行時に動的である場合だけインライン TS を使い、プロンプトが短いからという理由では使いません。

外部スキルを追加する

外部スキルは 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 を構築するため、外部スキルは組み込みと同じレジストリとティアゲートを通ります。

チャット内でのプロンプトによるインストールを含む、ユーザー向けの完全な流れはスキルのインストールを参照してください。

上流が保守するサードパーティのパッケージ（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

スキルが公開ユーザーフローを追加する場合は、対応する機能または利用文書を四言語で更新します。