QGIS Plugin Generator

Generador de plugins de QGIS 4: de una descripción en lenguaje natural a un .zip instalable y validado.

No es un programa con interfaz gráfica ni una herramienta de línea de comandos de uso suelto. Es una base de conocimiento + plantillas + validador pensada para instalarse como skill en un agente de IA (Claude Code, Codex u otro): le describes el plugin que quieres y el agente lo genera, valida y empaqueta él solo.

El problema que resuelve

QGIS 4 usa PyQt6. Casi todo el PyQGIS publicado en internet —y casi todo lo que un modelo de lenguaje genera de memoria— está escrito para QGIS 3 + PyQt5 y falla en QGIS 4:

El fallo típico no es un error de sintaxis: es código que parece correcto y revienta al ejecutarse. Este repositorio existe para evitarlo.

Requisitos

• QGIS 4.x instalado (probado contra 4.0.2 en Windows)
• Python 3.9+ para el validador — vale el del sistema, no hace falta instalar ningún paquete
• Un agente de IA con acceso a tus archivos (Claude Code, Codex…). No está pensado como herramienta suelta para validar código escrito a mano: el validador es una pieza interna que el agente ejecuta en cada iteración.

Instalación

1. Clonar el repositorio

git clone https://github.com/BernabeHL/qgis-plugin-generator.git

Colócalo donde quieras. Todas las rutas internas del repositorio son relativas, así que no hay nada que ajustar dentro.

2. Saber dónde está tu QGIS

En la documentación, <QGIS> significa la carpeta de instalación de QGIS. Sustitúyela mentalmente por la tuya cuando copies un comando:

Tu carpeta de perfil, donde se instalan los plugins:

Para confirmar tu versión y que efectivamente usa PyQt6:

<QGIS>/bin/python-qgis.bat -c "from qgis.core import Qgis; print(Qgis.QGIS_VERSION)"

3. Conectar tu agente de IA

El repositorio no hace nada por sí solo. Es conocimiento en Markdown; hace falta un agente que lo lea y escriba el código. Elige tu caso:

Claude Code

Un skill es justo esto: una carpeta con un SKILL.md que Claude Code carga automáticamente cuando detecta que encaja con lo que le pides. No vive dentro del repo — vive en tu perfil de usuario, así que funciona desde cualquier carpeta en la que estés trabajando.

1. Crea la carpeta y el archivo:

   copy

   mkdir -p ~/.claude/skills/qgis-plugin-generator
   

2. Dentro, ~/.claude/skills/qgis-plugin-generator/SKILL.md con este contenido — cambia solo la ruta de la última línea por la carpeta donde clonaste el repo en el paso 1:

   copy

   ---
   name: qgis-plugin-generator
   description: Genera plugins de QGIS 4 (PyQGIS/PyQt6) completos e instalables. Úsalo siempre que el usuario pida crear, modificar, depurar o empaquetar un plugin de QGIS, un algoritmo de Processing, una herramienta de mapa o cualquier automatización PyQGIS.
   ---
   
   Lee `<ruta-donde-lo-clonaste>/skill/GUIA.md` y sigue esa guía.
   

3. Guarda. No hay que reiniciar nada ni registrar el skill en ningún sitio: la próxima vez que le pidas a Claude Code un plugin de QGIS, lo detecta solo y sigue la guía.

Esa ruta absoluta del paso 2 es el único sitio de todo el sistema donde escribes algo específico de tu máquina — y queda fuera del repositorio, así que nunca acaba subida a git ni le llega a nadie que lo clone.

Para comprobar que quedó bien activado, pídele directamente: "crea un plugin de QGIS que cuente las entidades de cada capa vectorial y las exporte a CSV". Si te empieza a hacer 2-3 preguntas concretas (nombre, si el resultado es una capa nueva…) en vez de escribir código PyQt5 a ciegas, el skill está enganchado.

Codex

Más simple todavía porque Codex ya lee AGENTS.md de la raíz del proyecto sin configuración extra:

1. Abre el proyecto (esta carpeta clonada) con Codex.
2. Pídele el plugin, igual que arriba.
3. Codex lee AGENTS.md → ese archivo le manda leer skill/GUIA.md → sigue el mismo flujo que Claude Code, paso a paso.

No hay paso 2 de verdad: si Codex tiene el repo abierto, ya está conectado.

Sin agente

Abre skill/GUIA.md y léelo tú. Está escrito para que lo entienda una persona, no solo un modelo — es la misma guía, palabra por palabra.

Cómo se usa

Paso 1 — Describir el plugin

Le dices al agente lo que quieres, en lenguaje normal:

Quiero un plugin que recorra todas las capas vectoriales del proyecto, cuente cuántas entidades tiene cada una y lo exporte a un CSV.

Paso 2 — Responder 2 o 3 preguntas

El agente pregunta solo lo que no puede deducir: nombre del plugin, si el resultado es una capa nueva o edita la existente, si un parámetro es fijo o lo elige el usuario. No debería interrogarte más allá de eso.

Paso 3 — El agente genera y valida

Escribe el plugin en output/<nombre>/ y lo pasa por el validador. Si algo falla, lo corrige y repite, hasta un máximo de 3 intentos. Si al tercero sigue fallando, para y te explica el bloqueo en vez de seguir adivinando.

Paso 4 — Instalar el ZIP en QGIS

Obtienes output/<nombre>.zip. Para instalarlo:

1. Abre QGIS
2. Complementos → Administrar e instalar complementos
3. Pestaña Instalar a partir de ZIP
4. Selecciona el archivo y pulsa Instalar complemento

Dónde aparece después, según el patrón:

• processing-algorithm → Caja de herramientas de Processing, bajo el nombre del plugin
• layer-processor, map-tool → botón en la barra de herramientas y entrada de menú
• dock-widget → panel lateral (Ver → Paneles)

Instalación manual (para desarrollo)

Copia la carpeta del plugin directamente al perfil:

%APPDATA%\QGIS\QGIS4\profiles\default\python\plugins\

Mejor aún, crea un enlace simbólico para editar sin copiar cada vez (PowerShell como administrador):

New-Item -ItemType SymbolicLink -Path "$env:APPDATA\QGIS\QGIS4\profiles\default\python\plugins\mi_plugin" -Target "<ruta-del-repo>\output\mi_plugin"

Con el plugin Plugin Reloader (del repositorio oficial de QGIS) recargas en caliente sin reiniciar. La diferencia es iterar en 3 segundos en vez de en 40.

Cómo valida y empaqueta el agente

Son dos comandos internos que el propio agente ejecuta en cada iteración del flujo de generación — no un CLI pensado para apuntarlo a código escrito a mano:

python validator/run_all.py output/<plugin>

python validator/build_zip.py output/<plugin>

run_all.py devuelve código de salida 0 si no hay errores y 1 si los hay, así que el agente sabe si debe corregir y repetir. Con --strict los avisos también cuentan como fallo.

build_zip.py valida antes de empaquetar y genera el ZIP con la estructura que QGIS exige: una única carpeta raíz con el nombre del plugin. El error más común al empaquetar a mano es comprimir el contenido de la carpeta en vez de la carpeta, y QGIS lo rechaza sin explicar por qué.

Qué detecta

• Enums sin cualificar y API de PyQt5 que ya no existe
• initGui() que añade cosas y unload() que no las quita
• Señales conectadas a objetos de vida larga y nunca desconectadas
• Acceso a la interfaz gráfica desde QgsTask.run() (hilo secundario)
• Bucles en processAlgorithm() que nunca comprueban feedback.isCanceled()
• QgsProcessingAlgorithm sin createInstance()
• metadata.txt incompleto o incoherente con el código
• Marcadores {{...}} de plantilla sin sustituir
• Sintaxis, nombres no definidos e imports muertos

Salida en formato ARCHIVO:LÍNEA: NIVEL: REGLA: mensaje, pensada para que un agente la lea y se autocorrija.

Calibrado contra código real

Se validaron los cuatro plugins que QGIS incluye de serie (MetaSearch, Processing, DB Manager, GRASS) para medir falsos positivos. Eso obligó a corregir seis reglas demasiado agresivas y a eliminar una entera que resultó ser sencillamente falsa: afirmaba que QAction solo se importa desde QtWidgets, y bastó comprobarlo en el intérprete para ver que el shim de QGIS lo expone también en QtGui.

Un validador con falsos positivos es peor que no tener validador: enseña a ignorar su salida.

Estructura del repositorio

skill/GUIA.md         Guía operativa: reglas, flujo, selección de patrón
skill/reference/      9 documentos de API PyQGIS verificados contra QGIS 4.0.2
skill/templates/      5 patrones de plugin listos para rellenar
skill/checklist.md    Revisión final de lo que un linter no ve
validator/            Validación estática (solo biblioteca estándar)
examples/INDEX.md     Plugins de referencia clasificados por patrón
output/               Plugins generados
AGENTS.md             Instrucciones para Codex u otros agentes
CLAUDE.md             Instrucciones para Claude Code
ARQUITECTURA.md       Diseño del sistema y fases pendientes

Los 5 patrones

Preferir processing-algorithm siempre que encaje: salen gratis el historial, la ejecución por lotes, el uso en el Modelador gráfico y la llamada desde qgis_process en línea de comandos.

Independencia de herramienta

El conocimiento es Markdown plano y vive en un único sitio, skill/. Encima hay punteros finos por herramienta: el SKILL.md de Claude Code y el AGENTS.md de la raíz solo dicen "lee GUIA.md".

Al corregir algo se edita skill/, nunca los punteros: si se duplica contenido, las copias divergen y se pierde la ventaja.

Personalizarlo

El sistema mejora con el uso. Dos sitios donde merece la pena escribir:

• skill/reference/common-errors.md — cada error nuevo que encuentres, con su causa y su arreglo. Es lo que evita repetir el mismo fallo.
• examples/ — tus propios plugins ya escritos, clasificados por patrón. Es lo que más sube la calidad de lo generado: el agente copia tus convenciones en vez de las de un manual genérico.

Probar sin abrir QGIS

Un algoritmo de Processing se puede instanciar y ejecutar en un script independiente, sin interfaz gráfica:

/ruta/a/QGIS/bin/python-qgis.bat script.py

Con QgsApplication + Processing.initialize() y añadiendo <QGIS>/apps/qgis/python/plugins al sys.path. Es la forma más rápida de comprobar que algo funciona de verdad y no solo que "parece correcto".

También:

/ruta/a/QGIS/bin/qgis_process-qgis.bat list

Estado

Funciona el circuito completo: generar → validar → ejecutar en QGIS → empaquetar.

Lo que todavía no está automatizado es probar la interfaz gráfica de un plugin: abrir QGIS, pulsar el botón y leer el panel de registro. La lógica de los algoritmos sí se puede verificar de verdad; la interfaz, no.

Hasta que eso exista, la regla del proyecto es decir explícitamente cuándo un plugin no se ha probado dentro de QGIS, en lugar de dar por bueno lo que solo se ha leído.

Autor

Bernabé Hinojosa — Experto en Inteligencia Artificial, hidráulica y GIS.

LinkedIn

Licencia

MIT. Los plugins que generes son tuyos; si los publicas en el repositorio oficial de QGIS, necesitarán licencia GPL-2.0-or-later, que es lo que ese repositorio exige.