grahama1970/plugin-creator

Creador de Plugins

Inicio Rápido

1. Ejecuta el script de andamiaje:

# Los nombres de plugins se normalizan a minúsculas con guiones y deben tener <= 64 caracteres.
# La carpeta generada y el nombre en plugin.json son siempre idénticos.
# Ejecutar desde la raíz de la habilidad (el directorio que contiene este `SKILL.md`).
# Por defecto se crea en `~/plugins/<nombre-del-plugin>`.
python3 scripts/create_basic_plugin.py <nombre-del-plugin>

2. Edita <ruta-del-plugin>/.codex-plugin/plugin.json cuando la solicitud proporcione metadatos específicos. El andamiaje comienza con valores predeterminados válidos y no debe contener marcadores de posición [TODO: ...].

3. Genera o actualiza la entrada del marketplace personal cuando el plugin deba aparecer en el orden de la interfaz de Codex:

# Las entradas del marketplace personal por defecto están en `~/.agents/plugins/marketplace.json`.
python3 scripts/create_basic_plugin.py mi-plugin --with-marketplace

Solo especifica --marketplace-name <nombre> cuando el nombre de marketplace personal por defecto ya esté ocupado o instalado y necesites inicializar un archivo de marketplace nuevo y diferente:

python3 scripts/create_basic_plugin.py mi-plugin \
  --with-marketplace \
  --marketplace-name equipo-local

Solo utiliza un marketplace de repositorio/equipo cuando el usuario lo solicite explícitamente:

python3 scripts/create_basic_plugin.py mi-plugin \
  --path <raíz-del-repo>/plugins \
  --marketplace-path <raíz-del-repo>/.agents/plugins/marketplace.json \
  --with-marketplace

Cuando el usuario especifique una ruta de marketplace, asegúrate de que ese marketplace esté realmente instalado antes de indicarle que lo reinstale. El archivo de marketplace personal por defecto en ~/.agents/plugins/marketplace.json se descubre implícitamente, pero otras rutas de marketplace no. En Windows, usa la ruta equivalente dentro del perfil de usuario.

4. Genera/ajusta las carpetas complementarias opcionales según sea necesario:

python3 scripts/create_basic_plugin.py mi-plugin \
  --path <directorio-padre-del-plugin> \
  --marketplace-path <ruta-del-json-del-marketplace> \
  --with-skills --with-hooks --with-scripts --with-assets --with-mcp --with-apps --with-marketplace

<directorio-padre-del-plugin> es el directorio donde se creará la carpeta del plugin <nombre-del-plugin> (por ejemplo ~/plugins).

5. Antes de entregar un plugin generado, ejecuta:

python3 scripts/validate_plugin.py <ruta-del-plugin>

Para actualizaciones de un plugin local existente durante el desarrollo, mantén el flujo de andamiaje tal cual y usa la referencia en lugar de editar manualmente los archivos de marketplace:

python3 scripts/update_plugin_cachebuster.py <ruta-del-plugin>

Prefiere el cachebuster predeterminado de la ayuda a menos que el usuario solicite explícitamente una anulación específica. Consulta references/installing-and-updating.md para conocer el flujo esperado de cachebuster y reinstalación mientras se itera sobre un plugin local existente.

Qué crea esta habilidad

• Los andamios predeterminados respaldados por marketplace utilizan el archivo de marketplace personal en ~/.agents/plugins/marketplace.json, con los plugins almacenados generalmente en ~/plugins/<nombre-del-plugin>/.
• Crea la raíz del plugin en /<directorio-padre-del-plugin>/<nombre-del-plugin>/.
• Siempre crea /<directorio-padre-del-plugin>/<nombre-del-plugin>/.codex-plugin/plugin.json.
• Rellena el manifiesto con la forma del esquema validado que acepta la ruta de ingesta.
• Crea o actualiza ~/.agents/plugins/marketplace.json cuando se establece --with-marketplace.
  • Si el archivo de marketplace aún no existe, inicializa una raíz de marketplace personal antes de añadir la primera entrada de plugin.
• <nombre-del-plugin> se normaliza utilizando las reglas de nomenclatura del creador de habilidades:
  • Mi Plugin → mi-plugin
  • Mi--Plugin → mi-plugin
  • los guiones bajos, espacios y signos de puntuación se convierten en -
  • el resultado está en minúsculas, separado por guiones con guiones consecutivos colapsados
• Soporta la creación opcional de:
  • skills/
  • hooks/
  • scripts/
  • assets/
  • .mcp.json
  • .app.json

Flujo de trabajo del marketplace

• La creación del marketplace personal por defecto apunta a ~/.agents/plugins/marketplace.json. Aquí, "marketplace personal" significa el marketplace cuyo archivo está en esa ruta.
• La creación del marketplace de repositorio/equipo es opcional mediante --path y --marketplace-path, solo cuando el usuario lo solicita específicamente.
• --marketplace-name es una ruta excepcional. Úsalo solo cuando el nombre de marketplace personal por defecto ya esté ocupado y necesites inicializar un archivo de marketplace nuevo y diferente.
• No uses --marketplace-name para renombrar un archivo de marketplace existente. Si el archivo ya existe, su name de nivel superior debe coincidir.
• Si el usuario especifica una ruta de marketplace diferente, trata ese marketplace como si necesitara instalación explícita mediante codex plugin marketplace add.
• Prefiere scripts/read_marketplace_name.py cuando necesites el nombre del marketplace desde cualquier archivo marketplace.json. Sin argumentos, lee el marketplace personal por defecto; con una ruta explícita también funciona para marketplaces de repositorio/equipo.
• En cualquier ubicación, la ruta de origen generada permanece como ./plugins/<nombre-del-plugin>.
• Los metadatos raíz del marketplace admiten name de nivel superior más interface.displayName opcional.
• Trata el orden de los plugins en plugins[] como orden de renderizado en Codex. Añade nuevas entradas al final a menos que un usuario solicite explícitamente reordenar la lista.
• displayName pertenece dentro del objeto interface del marketplace, no en entradas individuales de plugins[].
• Cada entrada de marketplace generada debe incluir todos los siguientes:
  • policy.installation
  • policy.authentication
  • category
• Valores predeterminados para nuevas entradas:
  • policy.installation: "AVAILABLE"
  • policy.authentication: "ON_INSTALL"
• Anula los valores predeterminados solo cuando el usuario especifique explícitamente otro valor permitido.
• Valores permitidos para policy.installation:
  • NOT_AVAILABLE
  • AVAILABLE
  • INSTALLED_BY_DEFAULT
• Valores permitidos para policy.authentication:
  • ON_INSTALL
  • ON_USE
• Trata policy.products como una anulación. Omítelo a menos que el usuario solicite explícitamente la restricción por producto.
• La forma de la entrada de plugin generada es:

{
  "name": "nombre-del-plugin",
  "source": {
    "source": "local",
    "path": "./plugins/nombre-del-plugin"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productividad"
}

• Usa --force solo cuando se pretenda reemplazar intencionalmente una entrada existente del marketplace para el mismo nombre de plugin.

• Si el archivo de marketplace de destino aún no existe, créalo con "name" de nivel superior, un objeto "interface" que contenga "displayName" y un array plugins, luego añade la nueva entrada.

• Para un archivo de marketplace completamente nuevo, el objeto raíz debe verse así:

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "nombre-del-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/nombre-del-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productividad"
    }
  ]
}

Comportamiento requerido

• El nombre de la carpeta exterior y el "name" en plugin.json son siempre el mismo nombre de plugin normalizado.
• No elimines la estructura requerida; mantén .codex-plugin/plugin.json presente.
• No dejes marcadores de posición [TODO: ...] en los manifiestos de plugins.
• Mantén apps y mcpServers fuera de plugin.json a menos que sus archivos complementarios se hayan creado realmente.
• Omite los campos de manifiesto de plugin no compatibles que la validación rechaza, incluyendo hooks.
• Si creas archivos dentro de una ruta de plugin existente, usa --force solo cuando la sobrescritura sea intencional.
• Conserva cualquier interface.displayName existente del marketplace.
• Al generar entradas de marketplace, escribe siempre policy.installation, policy.authentication y category incluso si sus valores son los predeterminados.
• Añade policy.products solo cuando el usuario lo solicite explícitamente para esa anulación.
• Mantén source.path del marketplace relativo a la raíz del marketplace seleccionado como ./plugins/<nombre-del-plugin>.
• Solo usa --marketplace-name cuando crees un nuevo archivo de marketplace cuyo nombre no deba ser personal porque ese nombre ya está ocupado o instalado en otro lugar.
• Si Codex necesitara aprobación para escribir el archivo de marketplace, solicita esa aprobación antes de continuar. Si el usuario prefiere ejecutar la escritura él mismo, proporciona el comando de andamiaje exacto y luego continúa desde la validación o las ediciones posteriores del plugin en lugar de dejar el flujo de trabajo vago.
• Para actualizaciones de un plugin local existente durante el desarrollo, no edites manualmente la configuración del marketplace ni marketplace.json. Usa el flujo de actualización documentado en references/installing-and-updating.md y scripts/update_plugin_cachebuster.py.
• No le digas al usuario que ejecute codex plugin marketplace add para el flujo predeterminado del marketplace personal. Ese comando es para la configuración explícita de un marketplace no predeterminado, no para la ruta estándar ~/.agents/plugins/marketplace.json.
• Si el usuario proporcionó un --marketplace-path no predeterminado, asegúrate de que ese marketplace esté instalado antes de dar instrucciones de reinstalación. Usa codex plugin marketplace add <ruta-a-la-raíz-del-marketplace> cuando ese marketplace explícito aún no se haya configurado.
• Cuando el flujo de trabajo haya creado o actualizado un plugin respaldado por marketplace, finaliza la respuesta final para el usuario con una breve transferencia a la aplicación Codex. Di Para ver esto en la aplicación Codex: y escribe Ver <nombre del plugin normalizado> y Compartir <nombre del plugin normalizado> como enlaces Markdown, no como URL sin formato o tramos de código.
• El enlace profundo "Ver" usa codex://plugins/<nombre del plugin normalizado>?marketplacePath=<ruta absoluta de marketplace.json>. El enlace profundo "Compartir" usa la misma URL con &mode=share.
• Reemplaza los marcadores de posición con el nombre real del plugin normalizado y la ruta absoluta de marketplace.json del plugin andamiado. Codifica la URL del segmento de ruta y el valor de la consulta cuando sea necesario.
• No añadas parámetros de consulta pluginName o hostId a estos enlaces profundos. Codex los deriva después de que el usuario haga clic en el enlace.
• No emitas los enlaces Ver <nombre del plugin normalizado> o Compartir <nombre del plugin normalizado> cuando no se haya creado ni actualizado ninguna entrada de marketplace.

Referencia a la muestra exacta de la especificación

Para la muestra JSON canónica exacta tanto para los manifiestos de plugin como para las entradas de marketplace, usa:

• references/plugin-json-spec.md
• references/installing-and-updating.md para obtener orientación sobre actualización/reinstalación mientras se itera sobre un plugin local existente, además del comportamiento de reanudación en un nuevo hilo después de la reinstalación

Validación

Después de editar SKILL.md, ejecuta:

python3 ../skill-creator/scripts/quick_validate.py .

Antes de entregar un plugin generado, ejecuta:

python3 scripts/validate_plugin.py <ruta-del-plugin>