ComeOnOliver/skillshub

Skill DOCX

Cuándo usarlo

• Leer o revisar contenido DOCX donde la maquetación importa (tablas, diagramas, paginación).
• Crear o editar archivos DOCX con formato profesional.
• Validar la maquetación visual antes de la entrega.

Flujo de trabajo

1. Preferir revisión visual (maquetación, tablas, diagramas).
   • Si soffice y pdftoppm están disponibles, convertir DOCX -> PDF -> PNGs.
   • O usar scripts/render_docx.py (requiere pdf2image y Poppler).
   • Si faltan estas herramientas, instalarlas o pedir al usuario que revise las páginas renderizadas localmente.
2. Usar python-docx para ediciones y creación estructurada (encabezados, estilos, tablas, listas).
3. Después de cada cambio significativo, volver a renderizar e inspeccionar las páginas.
4. Si no es posible la revisión visual, extraer texto con python-docx como alternativa y señalar el riesgo de maquetación.
5. Mantener los resultados intermedios organizados y limpiar después de la aprobación final.

Convenciones de archivos temporales y de salida

• Usar tmp/docs/ para archivos intermedios; eliminarlos al terminar.
• Escribir los artefactos finales en output/doc/ cuando se trabaje en este repositorio.
• Mantener los nombres de archivo estables y descriptivos.

Dependencias (instalar si faltan)

Preferir uv para la gestión de dependencias.

Paquetes Python:

uv pip install python-docx pdf2image

Si uv no está disponible:

python3 -m pip install python-docx pdf2image

Herramientas del sistema (para renderizado):

# macOS (Homebrew)
brew install libreoffice poppler

# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils

Si no es posible instalar en este entorno, indicar al usuario qué dependencia falta y cómo instalarla localmente.

Entorno

No se requieren variables de entorno.

Comandos de renderizado

DOCX -> PDF:

soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX

PDF -> PNGs:

pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME

Script auxiliar empaquetado:

python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages

Expectativas de calidad

• Entregar un documento listo para el cliente: tipografía consistente, espaciado, márgenes y jerarquía clara.
• Evitar defectos de formato: texto recortado/superpuesto, tablas rotas, caracteres ilegibles o estilos de plantilla predeterminados.
• Gráficos, tablas y elementos visuales deben ser legibles en las páginas renderizadas con la alineación correcta.
• Usar solo guiones ASCII. Evitar U+2011 (guion de no separación) y otros guiones Unicode.
• Las citas y referencias deben ser legibles para humanos; nunca dejar tokens de herramientas o marcadores de posición.

Verificaciones finales

• Volver a renderizar e inspeccionar cada página al 100% de zoom antes de la entrega final.
• Corregir cualquier problema de espaciado, alineación o paginación y repetir el ciclo de renderizado.
• Confirmar que no queden residuos (archivos temporales, renderizados duplicados) a menos que el usuario solicite conservarlos.