Crear paquetes

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#

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.

{
  "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):

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#

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:

{
  "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.

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:

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.

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:

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 para niveles, actualizaciones y ajustes.
• Catálogo de paquetes para saber qué hacen los paquetes propios.
• La entrada paquetes, plugins de Claude y servidores MCP sobre un servidor MCP añadido a un chat en vivo.