# パッケージを作成する — AI Game DevアプリとCLI · AI Game Developer Wiki

独自の AI Game Dev パッケージを作成しましょう。aigd-package.json マニフェスト、コマンド、スラッシュコマンド、MCP ツール、gamedev pkg dev によるローカル開発、共有方法を説明します。

このページは英語から機械翻訳されています。[英語の原文を読む](https://ai-game.dev/docs/wiki/app/creating-packages)。

パッケージはファーストパーティ機能のためだけのものではありません。チームで繰り返し行うタスクを共有したり、エージェントにツールを追加したり、独自のファイル形式をプレビューしたりするために、自分でパッケージを書くことができます。このページでは、パッケージのレイアウト、動作する最小構成のパッケージ、マニフェストの主なフィールド、MCP ツールの追加方法、実行中のアプリを相手にパッケージを開発する方法、そして共有方法を説明します。

## 必要なもの

- AI Game Dev デスクトップアプリ、または `gamedev` CLI（バージョン 0.18.0 以降）。
- テキストエディタ。JavaScript は任意です。パッケージはマニフェストのみでも構いません。

パッケージは VS Code 拡張機能のモデルに従います。マニフェスト `aigd-package.json` を含むフォルダと、`activate(ctx)` と `deactivate()` をエクスポートする任意のコードです。コードがアプリに到達できるのは `ctx.aigd` 経由のみです。コードは開いているプロジェクトごとに 1 つずつ用意される別の拡張機能ホストプロセスで実行され、何かが必要としたときに遅延して起動します。

## パッケージのレイアウト

```text
my-first-package/
  aigd-package.json     the manifest (required)
  extension.js          the code named by "main" (optional)
  media/                icons and images (optional)
  LICENSE
```

パッケージは自己完結している必要があります。アプリがそのパッケージのために `npm install` を実行することはありません。コードがライブラリを使う場合は、`main` が指すファイルにバンドルしてください。

## 最小構成のパッケージ

このパッケージは、`/my-first` スラッシュコマンド、コマンドパレットの項目、コンポーザーのツールバーボタン、ステータスバーの項目、そして 1 つの設定を追加します。

```json
{
  "publisher": "you",
  "name": "my-first-package",
  "version": "0.1.0",
  "displayName": "My First Package",
  "description": "A /my-first slash command, a palette command, a toolbar button and a status bar item.",
  "license": "MIT",
  "main": "extension.js",
  "engines": { "aigd": ">=0.18.0" },
  "activationEvents": ["onSlashCommand:/my-first", "onCommand:you.my-first-package.hello"],
  "contributes": {
    "commands": [
      { "command": "you.my-first-package.hello", "title": "Say hello", "category": "My First Package", "icon": "$(smile)" }
    ],
    "slashCommands": [
      { "name": "/my-first", "description": "Say hello from my first package", "argumentHint": "[name]" }
    ],
    "menus": {
      "composer/toolbar": [{ "command": "you.my-first-package.hello", "group": "navigation" }]
    },
    "statusBar": [
      { "id": "you.my-first-package.status", "text": "My package", "command": "you.my-first-package.hello", "alignment": "left" }
    ],
    "settings": {
      "name": { "type": "string", "default": "game dev", "description": "Who /my-first greets", "scope": "project" }
    }
  }
}
```

そしてコード、`extension.js`（CommonJS）は次のとおりです:

```text
const ID = "you.my-first-package";

exports.activate = function activate(ctx) {
  const { aigd } = ctx;
  let count = 0;

  ctx.subscriptions.push(
    aigd.commands.registerCommand(`${ID}.hello`, async () => {
      count++;
      await aigd.window.showInformationMessage(`Hello #${count} from my first package!`);
      return count;
    }),
    // Works in the desktop chat and in the CLI.
    aigd.commands.registerSlashCommand("/my-first", (inv) => {
      const who = inv.args.trim() || aigd.settings.get("name") || "game dev";
      inv.say(`Hi ${who}!`);
    }),
  );

  ctx.log.info("activated");
};

exports.deactivate = function deactivate() {};
```

スラッシュコマンド、ツールバーボタン、ステータスバーの項目は、コードが実行される前からマニフェストに基づいて表示されます。`activate` はそれらのいずれかが最初に使われたときに呼び出されます。

## ID と命名規則

- パッケージ ID は `publisher.name` の小文字形式です。ここでは `you.my-first-package` になります。publisher は 2〜40 文字（英字、数字、単一のハイフン）です。自前の publisher 名を使用してください。`aigd` は AI Game Dev のものです。
- パッケージが提供するすべての ID（コマンド、ビュー、ステータスバー項目、チュートリアル）は、パッケージ ID で始まります: `you.my-first-package.hello`。
- `engines.aigd` は必須です。パッケージが必要とする最も古い AI Game Dev のバージョンを指定します（例: `">=0.18.0"`）。古いアプリはパッケージを拒否し、必要なバージョンを示します。
- `version` は semver です。インストールは ID とバージョンでキャッシュされるため、公開する変更ごとにバージョンを上げる必要があります。

## マニフェストの主なフィールド

| フィールド | 必須 | 用途 |
| --- | --- | --- |
| `publisher`、`name`、`version` | はい | ID とバージョン |
| `engines.aigd` | はい | アプリの最小バージョン |
| `displayName`、`description`、`icon`、`license`、`homepage`、`repository`、`keywords` | いいえ | Packages ウィンドウに表示される内容 |
| `main` | いいえ | コードのエントリポイント。省略するとパッケージはコントリビューションのみになります |
| `activationEvents` | いいえ | コードを起動する追加のイベント（例: `onStartupFinished`） |
| `hosts` | いいえ | `desktop`、`cli`、またはその両方 |
| `dependencies` | いいえ | 他のパッケージ、`{ "<id>": "<range>" }` |
| `claudePlugins` | いいえ | パッケージが必要とする Claude プラグイン、`{ "<plugin>@<marketplace>": "<range>" }` |
| `contributes` | いいえ | パッケージが追加するすべてのもの（下記） |

`contributes` のコントリビューションポイントには、`commands`、`slashCommands`、`capabilities`（セッションの Tools 行にあるスイッチ）、`mcpServers`、`settings`、`panels`、`viewsContainers` と `views`（サイドパネルのツリーまたは webview ビュー）、`menus` と `submenus`、`keybindings`、`customEditors`、`statusBar`、`tutorials` があります。メニューは `commandPalette`、`composer/toolbar`、`explorer/context`、`editor/title`、`view/item/context` といった固定 ID を使用し、それぞれに任意の `when` 句を指定できます。CLI ではスラッシュコマンド、Tools 行、メッセージ、クイックピック、入力ボックス、フォームが表示されます。メニューとパネルはデスクトップ専用です。

## MCP サーバーでエージェントにツールを提供する

パッケージを書く最も一般的な理由は、エージェントに新しいツールを提供することです。MCP サーバーと、セッションごとにそれを有効化するケイパビリティを宣言します:

```json
{
  "publisher": "you",
  "name": "level-tools",
  "version": "0.1.0",
  "engines": { "aigd": ">=0.18.0" },
  "contributes": {
    "capabilities": [
      {
        "id": "you.level-tools",
        "label": "Level tools",
        "description": "Counts collectibles in the level files.",
        "defaultEnabled": false,
        "mcpServer": "you--level-tools"
      }
    ],
    "mcpServers": {
      "you--level-tools": {
        "command": "${node}",
        "args": ["${packageDir}/server.js"]
      }
    }
  }
}
```

- サーバー名はパッケージ ID の `<publisher>--<name>`（または `<publisher>--<name>-<suffix>`）である必要があり、最大 96 文字です。これにより、異なる作者の名前が衝突することはありません。修飾されていない名前はエラーになります。
- stdio サーバーで使用できる変数: `${node}`、`${packageDir}`、`${projectDir}`、`${globalStorage}`。
- 同じ名前の MCP サーバーがセッションにすでに設定されている場合、パッケージのサーバーは追加されず、セッションに通知が表示されます。

## 実行中のアプリを相手に開発する

公開バージョンの代わりに、プロジェクトを自分のフォルダに向けます。フォルダはその場で使用され、同梱しているファイルが変更されると再読み込みされ、自動更新されることはありません。デフォルトのレベルは **Local** で、コミットされることはありません。

```bash
cd <your project>
gamedev pkg link <path-to-your-package>      # use the folder (default --local)
gamedev pkg list                             # shows "(local dev)" and which level it overrides
gamedev pkg unlink you.my-first-package      # back to the published version
```

パッケージにビルドステップがある場合（`src/` が `dist/` にビルドされる）、代わりに `gamedev pkg dev` を使ってください。これはパッケージの `dev` スクリプトを実行するか、ソースが変更されるたびに `build` を再実行し、最初のビルドが成功した時点でフォルダをリンクし、Ctrl+C を押すと起動したすべてのプロセスを停止します：

```bash
gamedev pkg dev <path-to-your-package>
```

デスクトップアプリでは同じことを Packages ウィンドウで行えます。パッケージを選択して **Use a local folder…** を選び、元に戻すには **Stop using local folder** を選びます。マニフェストに別の id が記載されているフォルダは拒否されます。

**ヒント**

パッケージからのログ（`ctx.log`、`console.*`）は `pkg:<your id>` というタグ付きでアプリのログに表示され、失敗したパッケージは Packages ウィンドウの **Errors** タブにエラーを一覧表示します。

## パッケージを共有する

AI Game Dev レジストリにはファーストパーティのパッケージが用意されています。自分のパッケージを共有するには GitHub または npm で公開してください。そうすれば誰でもリンクから追加できます：

```bash
gamedev pkg add github:you/my-first-package           # not pinned: receives updates
gamedev pkg add github:you/my-first-package@v0.1.0    # a tag (never auto-updated)
gamedev pkg add npm:my-first-package                  # an npm package
gamedev pkg add npm:my-first-package@^0.1.0           # with a version range
```

チームで使う場合は **Project** レベルで追加してください。そうすれば `.ai-game-dev/packages.json` にコミットされ、プロジェクトのロックファイルで固定された状態でチームメイト全員が利用できます。

新しいバージョンを公開する前に、`aigd-package.json` の `version` を上げてください。バージョンが変わらないまま変更されたファイルは、そのバージョンが既にインストールされている環境には決して届きません。

## ベストプラクティス

- ツールは焦点を絞ってください。エージェントが見るすべてのツールはコンテキストを消費します。小さく、よく説明されたツールのほうが正しく使われる頻度が高くなります。
- 可能な限りマニフェストで宣言してください。そうすればコードが起動する前に UI が表示されます。
- チームで共有すべき設定には `scope: "project"` を、1 台のコンピューター上のパスには `scope: "machine"` を使用してください。
- パッケージはユーザーの権限で、サンドボックスなしで実行されます。パッケージにシークレットを含めて配布しないでください。また、パッケージが何をするのかをユーザーに伝えてください。

## さらに詳しく

- レベル、更新、設定については [Packages](https://ai-game.dev/ja/docs/wiki/app/packages) をご覧ください。
- ファーストパーティパッケージの機能については [Packages catalog](https://ai-game.dev/ja/docs/wiki/app/packages-catalog) をご覧ください。
- 実行中のチャットに MCP サーバーを追加する方法については、ブログ記事 [packages, Claude plugins and MCP servers](https://ai-game.dev/ja/blog/ai-game-dev-packages-plugins-mcp) をご覧ください。

---

Source (HTML): https://ai-game.dev/ja/docs/wiki/app/creating-packages

Machine-translated (ja) from the English page: https://ai-game.dev/docs/wiki/app/creating-packages