メインコンテンツへ移動
AIチュートリアル

Skillboxをセルフホスト：AIエージェント向けバージョン管理スキルライブラリを構築

DockerでSkillboxをデプロイし、バージョン管理されたスキルとスコープ付きクライアント接続を作成する方法、CLIとMCPインターフェースの使用方法、オプションのJevレコメンデーションの設定方法、データの保護や移行方法を学びます。

約19分で読了
Skillboxをセルフホスト：AIエージェント向けスキルライブラリを構築

Skillboxとは？

Skillboxは、MITライセンスで提供される、AIエージェント向けのセルフホスト型スキルライブラリです。再利用可能なスキルパッケージの作成、インポート、バージョン管理、配布、監査を一元的に行えます。アプリケーションはReact、Bun、Hono、PostgreSQLで構築されています。

新規インストール時は意図的に空の状態になっています。個人スキル、ユーザーアカウント、クライアントキー、外部サービスのエンドポイント、有料AIプロバイダーの認証情報は含まれていません。Skillboxはスキルコンテンツを配布しますが、アップロードされたスキルコードを実行することは決してありません。

主な機能

  • バージョン管理された編集: Markdownと関連ファイルを、変更不能なリビジョン、競合検出、復元機能付きで編集できます。
  • 範囲指定アクセス: スキルまたはバンドルへの権限付与と、作成、更新、アーカイブ、提案の権限を個別に設定したプロファイルを作成できます。
  • 失効可能なクライアント: クライアントごとのキーを発行し、利用状況を確認し、必要に応じて今後のアクセスを失効させられます。
  • MCPとCLIアクセス: HTTP MCPを直接使用したり、NodeまたはBunのstdioブリッジ経由で接続したり、チェックサム検証付きでパッケージをダウンロードしたりできます。
  • MCPリソース: 基本MCPリソースの一覧表示と読み取りを通じて、認可済みで互換性のあるスキルを公開できます。
  • 任意のレコメンデーション: 独自のVercel AI GatewayまたはTypeSafe AIキーでJevを使用できます。
  • データの可搬性: ネイティブフォルダーのインポートとエクスポート、保護されたバックアップの作成、明示的なデータ復元が可能です。
  • セルフホスト型デプロイ: Docker Composeで実行し、必要に応じてCaddyを前段に置いてHTTPS化したり、Umbrelパッケージを準備したりできます。

Skillboxは、範囲を限定したクライアントを備えた、単一所有者向けのセルフホスト型アプリケーションとして設計されています。一般公開のマルチテナントSaaSプラットフォームではありません。

前提条件

推奨インストールには、Compose v2対応のDocker EngineまたはDocker Desktopと、Linux、macOS、またはWSL上のBashが必要です。Dockerベースのセットアップでは、ホストにBunやNode.jsをインストールする必要はありません。

Skillboxのインストールと起動

  1. リポジトリをクローンして、そのディレクトリに移動します。

    git clone https://github.com/kitze/skillbox.git
cd skillbox

  2. ローカル環境ファイルを生成します。

    bash scripts/skillbox.sh setup

    これにより、一意のランダムな認証情報を含む.envが作成され、モードが0600に設定されます。既存のファイルは上書きされません。

  3. Dockerサービスを起動します。

    bash scripts/skillbox.sh start

  4. ブラウザーでhttp://127.0.0.1:4791を開きます。

  5. ローカルの.envファイルからSKILLBOX_ADMIN_TOKENを読み取り、それを使ってサインインします。セットアップスクリプトは意図的にこのトークンを表示しません。

.envは非公開にしてください。所有者トークンは管理アクセスを制御し、保存された統合認証情報の保護にも使用されます。

リモートデプロイ

リモートインストールでは、SKILLBOX_ORIGINをデプロイ先のHTTPSオリジンに設定し、TLSリバースプロキシを構成します。本番環境のインスタンスを暗号化されていないHTTPで公開しないでください。サポートされているデプロイの詳細については、リポジトリのデプロイに関する注意事項を参照してください。

Docker専用のアプリケーションセットアップを使わないローカル開発

BunとPostgreSQL 16以降のデータベースがすでにある場合は、依存関係をインストールしてアプリケーションを直接起動できます。

bun install --frozen-lockfile
# Set DATABASE_URL
# Set SKILLBOX_ADMIN_TOKEN to at least 32 random characters
# Set SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

必要な3つの値はすべて、ソース管理にコミットせず、保護された環境に保存してください。

スキルと範囲指定クライアントの作成

サインイン後、エディターでスキルを作成するか、既存のスキルパッケージをインポートします。スキルのリビジョンは変更不能なため、クライアントは変化するコンテンツに依存せず、特定のリビジョンを読み込んだり取得したりできます。

次に、プロファイルを作成し、必要なスキルまたはバンドルへのアクセス権を付与します。クライアントの目的に応じて、作成、更新、アーカイブ、提案の権限を個別に割り当てます。最後に、そのプロファイルを使用してクライアント接続を作成します。

クライアントキーは一度だけ表示され、Skillboxにはハッシュのみが保存されます。各キーはすぐに保護されたクライアント設定へ保存してください。所有者トークンを配布せず、クライアントごとに別のキーを使用します。

CLIの設定

CLIは、SkillboxのURLとクライアントキーを含むJSON設定を読み取ります。デフォルトのパスは~/.config/skillbox/config.jsonです。

{
  "url": "https://skills.example.com",
  "token": "YOUR_CLIENT_KEY"
}

ファイルモードを0600に設定してください。環境変数SKILLBOX_URLとSKILLBOX_TOKENを設定すると、設定ファイルの値が上書きされます。URLが設定されていない場合、CLIは他人のサービスではなくローカルホストを安全に対象にします。

cli/skillbox.mjsとcli/package.mjsは同じ場所に置いてください。その後、認可されたスキルを一覧表示して取得できます。

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs fetch my-skill@REVISION

fetch操作は、ファイルを書き込む前にパス、ファイルハッシュ、サイズ、実行フラグ、パッケージチェックサムを検証します。コードを実行したり、依存関係をインストールしたりすることはありません。

更新済みスキルの公開

更新対象として想定するスキルIDとリビジョンを指定して、ローカルフォルダーを公開します。

node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

想定される改訂では、競合検出がサポートされます。公開できるかどうかは、クライアントプロファイルに付与された権限にも左右されます。

監査の互換性

所有者は、変更を加えない互換性監査を実行できます。

node cli/skillbox.mjs audit

互換性のないパッケージが見つかると、コマンドはステータス1で終了します。既存のパッケージを書き換えずに、MCP Skillsとの互換性を評価する準備ができます。

MCP経由でAIエージェントを接続する

bootstrap/SKILL.mdをエージェントのskills-libraryブートストラップとしてインストールします。HTTP MCPをサポートするクライアントは、インスタンスの/mcpエンドポイントに接続し、ベアラートークンとしてクライアントキーを送信できます。

Authorization: Bearer YOUR_CLIENT_KEY

stdioを必要とするMCPクライアントでは、付属のブリッジを設定します。

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": [
        "/absolute/path/to/skillbox/cli/skillbox.mjs",
        "mcp"
      ],
      "env": {
        "SKILLBOX_URL": "https://skills.example.com",
        "SKILLBOX_CONFIG": "/absolute/path/to/protected-client-config.json"
      }
    }
  }
}

基本MCPツールには、search_skills、recommend_skills、load_skill、read_skill_file、report_skill_useが含まれます。書き込みツールと提案ツールは、クライアントのプロファイルに対応する権限が付与されている場合にのみ公開されます。

Skillboxは、基本MCPのresources/listおよびresources/readを通じて、認証済みの互換スキルも公開します。バイナリファイルや大容量ファイルにはリソースとしてアクセスできますが、リソースを読み取ってもスキルは有効化または実行されません。

io.modelcontextprotocol/skillsの完全なサポートは、まだ告知されていません。現在の実装では、基本MCPプロトコルを通じて準備機能を提供していますが、ネイティブな検出とネゴシエーションは、引き続きSDKとプロトコルのアップグレードに依存しています。

検索と推奨を正しく使用する

タスクの開始時には、エージェントは引き続きsearch_skillsを呼び出して、関連する認証済みスキルを一覧化する必要があります。推奨機能は検索を補完するものであり、この検索手順に置き換わるものではありません。選択したスキルを適用する前に、Skillboxから返された不変の改訂版を使って読み込みます。

外部の推奨プロバイダーを使わずに、CLIから検索できます。

node cli/skillbox.mjs search "database migration"

タスクに応じた推奨をリクエストするには、次を実行します。

node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"

対応するMCP操作はrecommend_skills({task, limit?, offset?})です。HTTPクライアントは、同じ認証済みJSON本文をPOST /api/skill-recommendationsに送信できます。

オプションのJev推奨機能を設定する

  1. Settings → Jev recommendationsを開きます。

  2. デフォルトのVercel AI Gateway、またはTypeSafe AIを選択します。

  3. 選択したプロバイダー用の独自のAPIキーを入力して保存します。

プロバイダーキーは個別に保存されます。TypeSafeを選択しても、保存済みのGatewayキーがTypeSafeに送信されることはありません。また、プロバイダーを切り替えても、以前保存したキーは保持されます。選択中のプロバイダーのキーを削除すると、そのプロバイダーでのモデル呼び出しが無効になります。

キーは、SKILLBOX_ADMIN_TOKENから導出した鍵素材を使用し、AES-256-GCMでPostgreSQL内に暗号化して保存されます。設定APIから返されることも、ブラウザーバンドルに含まれることもありません。文書化されたローテーション手順に従わずに所有者トークンを変更すると、保存済みの連携認証情報を読み取れなくなります。

キーを保存しても、プロバイダーへのアクセスや購入済みクレジットは検証されません。Jevはタスクのテキストと、認証済みで有効なスキルの説明を選択したプロバイダーに送信するため、そのプロバイダーの課金およびデータ取り扱い条件が適用されます。

推奨結果とフォールバックを理解する

Jevは、認証済みかつ有効で、アーカイブされていないリーフカタログ全体を評価します。対象は最大200個のリーフ、またはシリアライズ後の文字数120,000文字です。カタログがこれを超える場合、非公開のサブセットを順位付けせず、明示的にフォールバックします。

  • 関連性は0から4までの未較正スコアであり、確率ではありません。
  • スコアが3以上の結果は、スコアの降順、続いてID順で返されます。
  • noMatch=trueは、評価対象の候補にしきい値へ達したものがないことを示します。
  • キーの欠落、プロバイダーエラー、不正なレスポンス、レート制限、容量制限、または8秒の期限超過が発生すると、PostgreSQL検索にフォールバックします。
  • フォールバック結果では、method=search、relevance=null、およびfallbackReasonが使用されます。

プロセスローカルキャッシュには、5分間で最大128件のエントリが保持されます。Skillboxでは、同時評価は2件、スコープごとのキャッシュされていないリクエストは1分あたり10件まで許可され、自動再試行は行われません。権限付与、ライフサイクル状態、改訂版は、キャッシュヒットを含め、モデル呼び出しの前後で確認されます。

データをインポート、エクスポート、バックアップする

Bunが利用できる場合は、次のコマンドでスキルのフォルダーをインポートします。

bun scripts/import.ts /path/to/skills

インポートではファイルのバイト列と未知のフロントマターが保持され、シンボリックリンクとランタイムアーティファクトはスキップされ、認識可能なシークレットパターンは隔離されます。この検出はヒューリスティックであるため、完全なシークレット監査の代わりにはなりません。スキルパッケージにパスワードやトークンを決して置かないでください。

空の保存先にスキルコンテンツをエクスポートします。

SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts

PostgreSQLデータベースが引き続き信頼できる唯一の情報源です。エクスポートしたフォルダーを編集しても、コンテンツを再度公開するまでデータベースは変更されません。

保護されたバックアップを作成します。

bash scripts/backup.sh

エクスポートやバックアップには、非公開のスキル内容が含まれる場合があります。これらは公開アプリケーションのソースとは分離して管理してください。オプションのGitHubエクスポートスクリプトを使用するには、専用の非公開エクスポート用チェックアウトを明示的に設定する必要があり、自動的には有効になりません。

高度な運用のヒント

連携ごとに1つのクライアントキーを使用する

キーを分けると、失効や利用状況のレポートがより有用になります。キーを失効させると今後のリクエストはブロックできますが、クライアントがすでにダウンロードしたファイルを取り消すことはできません。

範囲を絞ったプロファイルを優先する

各エージェントには、必要なスキルとアクションだけを付与してください。バンドルは現在のリーフスキルに展開され、重複が除去されます。一方、参照だけではアクセス権は付与されません。

オーナートークンとバックアップを保護する

オーナートークンは管理者アクセスを提供し、保存された連携認証情報の暗号化素材を導出します。データベースや設定のバックアップとともに保護し、トークンを置き換える前に、文書化されたローテーション手順に従ってください。

スキルは信頼済みプログラムではなくコンテンツとして扱う

Skillboxはパッケージファイルを検証して配布しますが、実行はしません。エージェントのワークフローで使用する前に、ダウンロードした指示やコードを引き続き確認してください。

推奨結果は慎重に評価する

開発者は、自分のプロバイダーキーを使って、オプションの有料ベンチマークを実行できます。

bun scripts/benchmark-recommendations.ts --live --provider vercel
bun scripts/benchmark-recommendations.ts --live --provider typesafe

VercelにはAI_GATEWAY_API_KEYを、TypeSafeにはTYPESAFE_API_KEYまたはJEV_KEYを使用してください。このスクリプトがアプリケーションを設定したり、認証情報を保存したりすることはありません。合成サンプルは、本番環境のレイテンシーを保証するものでも、確率の較正を保証するものでもありません。

デプロイまたはコントリビューションを検証する

変更をデプロイする前に、型チェックと分離テストスイートを実行してください。

bun run typecheck
bash scripts/test-isolated.sh

分離テストスイートは、データベースポートを公開せずに、専用のDocker Compose PostgreSQLインスタンスを作成して削除します。認可、リビジョン、APIとMCPの動作、CLI、暗号化された設定、推奨機能を対象としています。データベーステストを本番環境に向けることは絶対に避けてください。

まとめ

Skillboxは、再利用可能なAIエージェントスキルを管理するための、制御可能なセルフホスト型ワークフローを提供します。まずDockerセットアップから始め、バージョン管理されたスキルを作成し、範囲を絞ったプロファイルを割り当て、各エージェントを専用のクライアントキーで接続してください。その後、カタログと認証情報の所有権を維持しながら、MCPアクセス、オプションのJev推奨機能、ポータビリティワークフロー、バックアップを追加できます。