# 패키지 만들기 — 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`를 통해서만 앱에 접근합니다. 코드는 열린 프로젝트마다 하나씩 생성되는 별도의 확장 호스트 프로세스에서 실행되며, 필요할 때 지연 시작됩니다.

## 패키지 구조

```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` 슬래시 명령, 명령 팔레트 항목, 컴포저 툴바 버튼, 상태 표시줄 항목, 설정 하나를 추가합니다.

```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`(측면 패널의 트리 또는 웹뷰 뷰), `menus`와 `submenus`, `keybindings`, `customEditors`, `statusBar`, `tutorials`가 있습니다. 메뉴는 `commandPalette`, `composer/toolbar`, `explorer/context`, `editor/title`, `view/item/context` 같은 고정 id를 사용하며, 각각 선택적 `when` 절을 가집니다. CLI는 슬래시 명령, Tools 행, 메시지, 빠른 선택, 입력 상자, 폼을 표시하고, 메뉴와 패널은 데스크톱 전용입니다.

## MCP 서버로 에이전트에 도구 제공하기

패키지를 작성하는 가장 흔한 이유는 에이전트에 새 도구를 제공하는 것입니다. MCP 서버와, 세션별로 이를 켜는 capability를 선언하세요:

```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"`를, 한 컴퓨터의 경로에는 `scope: "machine"`을 사용하세요.
- 패키지는 샌드박스 없이 사용자의 권한으로 실행됩니다. 패키지에 비밀 정보를 포함하지 말고, 패키지가 하는 일을 사용자에게 알리세요.

## 더 알아보기

- [Packages](https://ai-game.dev/ko/docs/wiki/app/packages)에서 레벨, 업데이트, 설정을 알아보세요.
- [Packages catalog](https://ai-game.dev/ko/docs/wiki/app/packages-catalog)에서 퍼스트파티 패키지가 하는 일을 확인하세요.
- [packages, Claude plugins and MCP servers](https://ai-game.dev/ko/blog/ai-game-dev-packages-plugins-mcp) 글에서 라이브 채팅에 추가된 MCP 서버를 다룹니다.

---

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

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