# Crear paquetes — App y CLI de AI Game Dev · AI Game Developer Wiki

Crea tu propio paquete de AI Game Dev: manifiesto aigd-package.json, comandos, herramientas MCP, desarrollo local con gamedev pkg dev y publicación.

Esta página se tradujo automáticamente del inglés. [Lee el original en inglés](https://ai-game.dev/docs/wiki/app/creating-packages).

Los paquetes no son solo para funciones propias: puedes escribir los tuyos para compartir una tarea repetida con tu equipo, añadir una herramienta para el agente o previsualizar un formato de archivo personalizado. Esta página muestra la estructura de un paquete, un paquete mínimo funcional, los campos principales del manifiesto, cómo añadir una herramienta MCP, cómo desarrollar un paquete contra una app en ejecución y cómo compartirlo.

## Qué necesitas

- La app de escritorio AI Game Dev o la CLI `gamedev`, versión 0.18.0 o posterior.
- Un editor de texto. JavaScript es opcional: un paquete puede ser solo manifiesto.

Los paquetes siguen el modelo de las extensiones de VS Code: una carpeta con un manifiesto, `aigd-package.json`, y código opcional que exporta `activate(ctx)` y `deactivate()`. Tu código llega a la app solo a través de `ctx.aigd`. Se ejecuta en un proceso host de extensiones aparte, uno por cada proyecto abierto, y se inicia de forma diferida cuando algo lo necesita.

## Estructura del paquete

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

Un paquete debe ser autocontenido: la app nunca ejecuta `npm install` para él. Si tu código usa librerías, empaquétalas en el archivo al que apunta `main`.

## Un paquete mínimo

Este paquete añade un comando slash `/my-first`, una entrada en la paleta de comandos, un botón en la barra de herramientas del compositor, un elemento en la barra de estado y un ajuste.

```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" }
    }
  }
}
```

Y el código, `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() {};
```

El comando slash, el botón de la barra de herramientas y el elemento de la barra de estado aparecen desde el manifiesto antes de que se ejecute ningún código; se llama a `activate` la primera vez que se usa uno de ellos.

## Ids y reglas de nomenclatura

- El id del paquete es `publisher.name`, en minúsculas: aquí `you.my-first-package`. El publisher tiene de 2 a 40 caracteres (letras, dígitos, guiones simples). Usa tu propio nombre de publisher; `aigd` es el de AI Game Dev.
- Cada id que aporta un paquete (comandos, vistas, elementos de la barra de estado, tutoriales) empieza por el id del paquete: `you.my-first-package.hello`.
- `engines.aigd` es obligatorio: la versión más antigua de AI Game Dev que necesita el paquete, por ejemplo `">=0.18.0"`. Una app más antigua rechaza el paquete e indica qué versión necesita.
- `version` es semver. Las instalaciones se cachean por id y versión, así que cada cambio que publiques necesita una versión superior.

## Campos principales del manifiesto

| Campo | Obligatorio | Propósito |
| --- | --- | --- |
| `publisher`, `name`, `version` | Sí | El id y la versión |
| `engines.aigd` | Sí | Versión mínima de la app |
| `displayName`, `description`, `icon`, `license`, `homepage`, `repository`, `keywords` | No | Lo que muestra la ventana Paquetes |
| `main` | No | La entrada de código; sin él el paquete es solo de contribuciones |
| `activationEvents` | No | Eventos adicionales que inician el código, como `onStartupFinished` |
| `hosts` | No | `desktop`, `cli` o ambos |
| `dependencies` | No | Otros paquetes, `{ "<id>": "<range>" }` |
| `claudePlugins` | No | Plugins de Claude que necesita el paquete, `{ "<plugin>@<marketplace>": "<range>" }` |
| `contributes` | No | Todo lo que añade el paquete (más abajo) |

Los puntos de contribución de `contributes` incluyen `commands`, `slashCommands`, `capabilities` (interruptores en la fila Tools de la sesión), `mcpServers`, `settings`, `panels`, `viewsContainers` y `views` (vistas de árbol o webview en los paneles laterales), `menus` y `submenus`, `keybindings`, `customEditors`, `statusBar` y `tutorials`. Los menús usan ids fijos como `commandPalette`, `composer/toolbar`, `explorer/context`, `editor/title` y `view/item/context`, cada uno con una cláusula `when` opcional. La CLI muestra comandos slash, filas de Tools, mensajes, quick picks, cuadros de entrada y formularios; los menús y los paneles son solo para la versión de escritorio.

## Da al agente una herramienta con un servidor MCP

El motivo más habitual para escribir un paquete es dar al agente nuevas herramientas. Declara un servidor MCP y una capacidad que lo active por sesión:

```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"]
      }
    }
  }
}
```

- El nombre del servidor debe ser `<publisher>--<name>` (o `<publisher>--<name>-<suffix>`) del id del paquete, como máximo 96 caracteres, para que los nombres de distintos autores nunca colisionen. Un nombre sin cualificar es un error.
- Variables que puedes usar en un servidor stdio: `${node}`, `${packageDir}`, `${projectDir}` y `${globalStorage}`.
- Si ya hay un servidor MCP con el mismo nombre configurado en una sesión, el servidor del paquete no se añade y la sesión muestra un aviso.

## Desarrolla contra la app en ejecución

Apunta un proyecto a tu carpeta en lugar de a una versión publicada. La carpeta se usa tal cual, se recarga cuando cambia algún archivo que incluye y nunca se actualiza automáticamente. El nivel predeterminado es **Local**, que nunca se confirma en el repositorio.

```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
```

Si tu paquete tiene un paso de compilación (`src/` compilado en `dist/`), usa `gamedev pkg dev` en su lugar. Ejecuta el script `dev` del paquete, o vuelve a ejecutar `build` tras cada cambio en el código fuente, enlaza la carpeta tras la primera compilación correcta y detiene todos los procesos que inició cuando pulsas Ctrl+C:

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

En la app de escritorio lo mismo está en la ventana Paquetes: selecciona el paquete y elige **Use a local folder…**, y luego **Stop using local folder** para volver atrás. Se rechaza una carpeta cuyo manifiesto indique otro id.

**Consejo**

Los logs de tu paquete (`ctx.log`, `console.*`) aparecen en el log de la app etiquetados como `pkg:<your id>`, y un paquete que falla lista sus errores en la pestaña **Errors** de la ventana Paquetes.

## Comparte tu paquete

El registro de AI Game Dev contiene los paquetes propios. Para compartir el tuyo, publícalo en GitHub o en npm; cualquiera puede añadirlo mediante un enlace:

```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
```

Para un equipo, añádelo en el nivel **Project** para que se confirme en `.ai-game-dev/packages.json` y todos los compañeros lo reciban, fijado por el archivo de bloqueo del proyecto.

Antes de publicar una versión nueva, sube `version` en `aigd-package.json`. Un archivo modificado con una versión sin cambios nunca llega a una instalación que ya tiene esa versión.

## Buenas prácticas

- Mantén las herramientas enfocadas. Cada herramienta que ve el agente consume contexto; una herramienta pequeña y bien descrita se usa correctamente más a menudo.
- Declara en el manifiesto todo lo que puedas, para que la interfaz sea visible antes de que se inicie tu código.
- Usa `scope: "project"` para los ajustes que el equipo debe compartir y `scope: "machine"` para rutas de un solo ordenador.
- Los paquetes se ejecutan con los permisos de tu usuario y sin sandbox. No incluyas secretos en un paquete y explica a los usuarios qué hace el tuyo.

## Más información

- [Paquetes](https://ai-game.dev/es/docs/wiki/app/packages) para niveles, actualizaciones y ajustes.
- [Catálogo de paquetes](https://ai-game.dev/es/docs/wiki/app/packages-catalog) para saber qué hacen los paquetes propios.
- La entrada [paquetes, plugins de Claude y servidores MCP](https://ai-game.dev/es/blog/ai-game-dev-packages-plugins-mcp) sobre un servidor MCP añadido a un chat en vivo.

---

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

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