Guía para creadores
Crea un tema de color, un paquete de reglas o de Habits, un servidor MCP o una plantilla de Rex y publícalo en la tienda de Ingot con la herramienta de línea de comandos ingot, desde una carpeta vacía hasta una ficha en /marketplace/<publisher>.<name>.
@ingotide/cli todavía no esté en npm: si npm install no lo encuentra, compílalo desde el código fuente (paso 1).Lo que harás: instalar la CLI, crear tu perfil de publicador, generar una extensión, probarla en un proyecto real, empaquetarla como archivo .ingotx, crear un token de publicación y publicar. Al final verás cómo actualizar y retirar. Calcula unos 15 minutos para tu primera extensión.
1. Instala la CLI
Necesitas Node.js 22 o posterior.
npm install -g @ingotide/cli
ingot --version
También puedes ejecutar cualquier comando sin instalar nada: npx @ingotide/cli <comando>.
Si el paquete aún no está en npm, compílalo desde el repositorio del portal de Ingot:
git clone https://github.com/yaghobieh/ingot-portal.git
cd ingot-portal/packages/ingot-cli
npm ci && npm run build && npm link
ingot --version
ingot help lista todos los comandos e ingot <comando> --help muestra sus opciones. La lista completa está en la referencia de la CLI.
2. Crea tu perfil de publicador
Todo lo que publicas pertenece a un publicador. Su identificador es el campo publisher de cada ingot.json y la primera mitad del id de cada extensión (acme.react-rules).
- Inicia sesión en tu cuenta de Ingot.
- Abre Panel › Publicador (/dashboard/publisher).
- Elige un identificador (de 3 a 32 letras minúsculas, dígitos y guiones), un nombre visible y, si quieres, un sitio web.
- Haz clic en Crear publicador.
El identificador no se puede cambiar después. Los identificadores que parecen oficiales (ingot, zaprex, ingot-…, official, support y similares) están reservados.
3. Genera una extensión
ingot init crea una carpeta con un ingot.json válido, un README, un CHANGELOG, una LICENSE MIT, un .gitignore, archivos de inicio para el tipo que elijas y un flujo de GitHub Actions que publica cuando subes una etiqueta de versión.
ingot init my-theme --type theme --publisher acme
cd my-theme
Sin opciones, te pregunta el tipo, el nombre, el publicador y la descripción. Elige el tipo que corresponde a lo que vas a crear:
| Tipo | --type | Archivos de inicio | En Ingot se convierte en |
|---|---|---|---|
| Tema de color | theme | themes/<name>.json | un tema en Ajustes › Apariencia |
| Paquete de reglas | rules | rules/<name>.mdc | archivos en .ingot/rules/ del proyecto |
| Paquete de Habits | habits | habits/<id>.json | patrones que Habits vigila |
| Servidor MCP | mcp | server/index.mjs (un servidor stdio que funciona) | una entrada en .ingot/mcp.json |
| Plantilla de Rex | rex-template | templates/<name>.md | una plantilla que Rex ejecuta en Zaprex |
Un comando por tipo:
ingot init my-theme --type theme --publisher acme --yes
ingot init react-rules --type rules --publisher acme --yes
ingot init team-habits --type habits --publisher acme --yes
ingot init word-tools --type mcp --publisher acme --yes
ingot init nightly-fix --type rex-template --publisher acme --yes
--yes acepta los valores por defecto. Añade --ci gitlab para un pipeline de GitLab en lugar de GitHub Actions, o --ci none para no crear archivo de CI. Tipos de extensión explica cada tipo y sus archivos.
4. Añade reglas, habits, comandos y servidores MCP
Un paquete puede llevar más que su tipo principal: un paquete de reglas puede añadir comandos de barra, un tema puede incluir un archivo de reglas, etc. ingot add escribe el archivo y su entrada en ingot.json de una vez:
ingot add rule testing --description "Cómo escribimos los tests"
ingot add habit no-any --match ":\s*any\b" --rule "- No uses el tipo any."
ingot add command review --description "Revisa los archivos abiertos"
ingot add mcp acme-api --command npx --env ACME_API_KEY="Tu clave de la API de Acme" -- -y @acme/mcp-server
ingot add mcp docs --url https://mcp.acme.dev/sse
- Las reglas son archivos Markdown o
.mdccon frontmatter opcional (description,globs,alwaysApply), igual que en Reglas. - Los comandos se convierten en
/<nombre>en el chat del agente. - Los servidores MCP ejecutan un comando local o se conectan a una URL
https://remota. Lista las variables de entorno con una descripción de lo que hay que escribir; nunca pongas un secreto en el paquete.
Edita los archivos y comprueba tu trabajo cuando quieras:
ingot validate
validate ejecuta exactamente las comprobaciones que hace la tienda al subir, así que un paquete que valida en tu equipo no será rechazado por su contenido.
5. Pruébala en un proyecto real
ingot try instala la extensión en un proyecto igual que lo hará la tienda:
ingot try ~/code/my-app
- El paquete completo se copia en
~/code/my-app/.ingot/extensions/acme.my-theme/. - Las reglas van a
.ingot/rules/, los comandos a.ingot/commands/y los servidores MCP se añaden a.ingot/mcp.json(con${extensionDir}sustituido por la carpeta real).
Abre el proyecto en Ingot y usa la extensión: cambia al tema, pregúntale al agente algo que cubran tus reglas, ejecuta /review o llama a las herramientas de tu servidor MCP. Vuelve a ejecutar ingot try después de cada cambio. Para deshacerlo, borra los archivos copiados.
6. Empaquétala
ingot package
Valida otra vez y escribe acme.my-theme-0.1.0.ingotx: un archivo ZIP con ingot.json, tu README, CHANGELOG y LICENSE, y cada archivo al que apunta el manifiesto. Solo entran esos archivos y lo que pongas en files de ingot.json. Los paquetes son deterministas (las mismas fuentes dan los mismos bytes) y la CLI muestra el SHA-256.
Límites: 4 MB por paquete, 20 MB descomprimido, 2 MB por archivo, 200 archivos. Los detalles están en Manifiesto.
7. Crea un token de publicación
La CLI publica con un token de publicación, no con tu contraseña.
- Abre Panel › Publicador.
- En Tokens de publicación, escribe un nombre (por ejemplo
PortátiloGitHub Actions) y elige cuándo caduca: 30, 90, 180 o 365 días. - Haz clic en Crear token y cópialo. Empieza por
ingot_pub_y se muestra solo una vez.
Los tokens solo pueden publicar y retirar como tu publicador; no pueden leer ni cambiar nada más de tu cuenta. Ingot guarda solo un hash de cada token. Revoca un token desde la misma página y deja de funcionar al instante. Usa un token por equipo o sistema de CI para poder revocarlos por separado.
8. Inicia sesión y publica
ingot login
Pega el token cuando te lo pida (no se muestra al escribir). La CLI lo comprueba con la tienda y lo guarda en ~/.ingot/cli/credentials.json, legible solo por ti. ingot whoami muestra a qué publicador pertenece.
Después publica desde la carpeta de la extensión:
ingot publish
publish empaqueta la carpeta y la sube. Para subir un archivo que ya generaste, pásalo: ingot publish acme.my-theme-0.1.0.ingotx. La tienda vuelve a validar el paquete, guarda la versión y muestra su página:
Publishing acme.my-theme@0.1.0 to https://www.ingotide.com…
Published acme.my-theme@0.1.0.
Store page: https://www.ingotide.com/marketplace/acme.my-theme
Tu extensión aparece ahora en la tienda en De la comunidad, en su categoría y en la búsqueda, con la insignia Comunidad. Su página tiene el README, el historial de versiones y un botón Descargar .ingotx.
ingot://) requiere una versión más nueva de Ingot. Mientras tanto, la página del elemento explica cómo instalarla a mano: descarga el .ingotx, descomprímelo y ejecuta ingot try <proyecto> --cwd <carpeta>.9. Publica actualizaciones
Cada subida necesita una versión nueva y mayor. Súbela con ingot version, que además añade un encabezado a CHANGELOG.md:
ingot version patch # 0.1.0 → 0.1.1 (o minor, major, o una exacta como 1.2.0)
ingot publish
Las versiones siguen el versionado semántico: 1.2.3, o una versión previa como 1.3.0-beta.1. La tienda rechaza una versión que ya se subió o que no es mayor que la última, así que un número nunca se reutiliza, ni siquiera después de retirarla.
Para publicar desde CI, haz commit, etiqueta y sube; el flujo que creó ingot init hace el resto:
git commit -am "v0.1.1" && git tag v0.1.1 && git push --follow-tags
Configurarlo lleva cinco minutos: consulta Publicar desde CI/CD.
10. Retira una extensión
ingot unpublish acme.my-theme@0.1.1 # una versión
ingot unpublish acme.my-theme # todas las versiones
Ejecútalo dentro de la carpeta de la extensión sin id para usar ingot.json. La CLI te pide escribir el nombre de la extensión para confirmar; usa --yes en scripts. También puedes hacer clic en Retirar junto a la extensión en Panel › Publicador.
Retirar saca la versión (o la extensión entera) de la tienda, del sitemap y de la búsqueda. Las copias que la gente ya instaló siguen funcionando. El número de versión queda usado: publica la siguiente versión para volver.
Antes de publicar en serio, lee las normas de la tienda. Consulta cualquier campo en Manifiesto y cada opción en la referencia de la CLI.