Communitygithub.com

V4TIME/V4SKILL

Crear, leer, editar, usar plantillas y revisar archivos .docx de Word.

¿Qué es V4SKILL?

Esta habilidad proporciona un conjunto completo de herramientas de línea de comandos (CLI) para trabajar con documentos de Microsoft Word (.docx) utilizando python-docx. Permite crear documentos desde una especificación JSON, leer su contenido (texto, estructura, estilos, imágenes), editar párrafos, tablas y estilos, aplicar plantillas con tokens `{{}}`, y gestionar cambios controlados (revisiones) y comentarios. Es útil para desarrolladores y agentes de IA que necesitan automatizar la generación y manipulación de informes, cartas, contratos y otros documentos de Word sin necesidad de la interfaz gráfica de Word. La habilidad es compatible con cualquier entorno que tenga Python y la biblioteca python-docx instalada, y se ejecuta mediante scripts independientes que imprimen JSON en la salida estándar. No convierte a PDF ni maneja formatos heredados como .doc.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/V4TIME/V4SKILL/tree/HEAD/productivity/docx

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Habilidad Docx

Crear, leer, editar y usar plantillas de archivos .docx de Microsoft Word con python-docx a través de pequeñas CLI. Maneja texto, estilos, listas, tablas, imágenes, encabezados/pies de página, plantillas {{token}}, cambios controlados (listar/aceptar/rechazar), comentarios (listar/añadir/eliminar), campos de TDC e índice de páginas, y comprobaciones de integridad del paquete. No renderiza documentos por sí mismo (PDF necesita LibreOffice — ver Conversión a PDF) ni edita .doc heredados.

Cuándo Usarlo

  • El usuario pide generar un documento de Word (informe, carta, contrato).
  • Necesitas el texto, esquema, estilos o imágenes incrustadas de un .docx.
  • Debes modificar un .docx existente: reemplazar texto, editar celdas de tabla, insertar/eliminar párrafos, aplicar estilos, fusionar fragmentos de ejecución.
  • Tienes una plantilla .docx con {{placeholders}} para completar con datos.
  • El documento tiene cambios controlados para revisar, aceptar o rechazar.
  • Necesitas leer los comentarios de los revisores, o añadir/eliminar comentarios.
  • Un .docx no se abre o se comporta de forma extraña y necesitas un diagnóstico.
  • El documento necesita una tabla de contenido o pies de página "Página X de Y".
  • No para: .doc (heredado), .odt o trabajo de maquetación WYSIWYG.

Prerrequisitos

  • Python 3.10+ con python-docx instalado: pip install python-docx (el nombre de importación es docx; lxml viene con él).
  • comments add usa la API nativa en python-docx >= 1.2 y un fallback XML en versiones anteriores — ambos son automáticos.
  • Para bloques de imagen: los archivos de imagen deben existir localmente (PNG/JPEG).

Cómo Ejecutar

Todos los ayudantes viven en scripts/ junto a este archivo. Ejecútalos con la herramienta terminal; cada uno soporta --help e imprime JSON en stdout.

python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx

Referencia Rápida

TareaComando
Crear desde especificación JSONdocx_create.py spec.json out.docx
Texto completo (cuerpo+tablas+encabezados/pies)docx_read.py f.docx --text
Esquema de títulos + formas de tablasdocx_read.py f.docx --structure
Estilos realmente usadosdocx_read.py f.docx --styles
Extraer imágenes incrustadasdocx_read.py f.docx --images outdir/
Detectar cambios controlados/comentariosdocx_read.py f.docx --revisions
Buscar/reemplazar (formato conservado)docx_edit.py replace f.docx --find A --replace B -o out.docx
Establecer una celda de tabladocx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X
Insertar párrafo antes del índice Ndocx_edit.py insert f.docx --index N --text X --style Normal
Eliminar párrafo Ndocx_edit.py delete f.docx --index N
Aplicar estilo al párrafo Ndocx_edit.py style f.docx --index N --style "Heading 1"
Fusionar ejecuciones adyacentes de igual formatodocx_edit.py normalize f.docx -o out.docx
Insertar campo TDC antes del párrafo Ndocx_edit.py toc f.docx --index N -o out.docx
Campos de pie "Página X de Y"docx_edit.py page-numbers f.docx
Rellenar {{tokens}}docx_template.py tpl.docx values.json out.docx --strict
Listar revisiones (id/autor/fecha/texto)docx_revisions.py list f.docx
Aceptar / rechazar todas las revisionesdocx_revisions.py accept-all f.docx -o out.docx (o reject-all)
Aceptar / rechazar una revisióndocx_revisions.py accept f.docx --id 3 -o out.docx
Listar comentarios (+texto anclado)docx_comments.py list f.docx
Añadir comentario anclado a textodocx_comments.py add f.docx --target "frase" --text "nota" --author Tú
Eliminar comentario por iddocx_comments.py delete f.docx --id 0
Comprobar integridad del paquetedocx_validate.py f.docx (código de salida 1 en errores)

Procedimiento

  1. Crear. Escribe una especificación JSON con write_file, luego ejecuta scripts/docx_create.py. La especificación soporta: page (tamaño + márgenes en mm), cadenas header/footer, footer_page_numbers (añade un campo de pie "Página X de Y"), styles (estilos de párrafo personalizados con fuente, tamaño, negrita/cursiva, color hex), y blocks — heading (nivel 1-9), paragraph (o bien text o una lista runs donde cada ejecución puede establecer bold/italic/underline), bullet_list, numbered_list, table (fila header renderizada en negrita, rows, opcional style de tabla incorporado como Table Grid), image (path, opcional width_mm), toc (campo de Tabla de Contenido) y page_break. El formato completo de la especificación está documentado al principio de scripts/docx_create.py.
  2. Leer. Usa scripts/docx_read.py con exactamente una bandera de modo. --text devuelve párrafos del cuerpo, todo el texto de las celdas de la tabla y texto de encabezado/pie como JSON. --structure devuelve el esquema de títulos más recuentos de párrafos/tablas/secciones. --images DIR copia cada archivo bajo word/media/ fuera del paquete.
  3. Editar. Usa scripts/docx_edit.py. replace recorre el cuerpo, tablas (incluidas las anidadas), encabezados y pies de página, y conserva el formato de las ejecuciones; añade --body-only para omitir encabezados/pies. Pasa -o out.docx para mantener el original; omítelo para editar en el lugar. Los índices de párrafo para insert/delete/style/toc se refieren al orden del cuerpo de --structure/--text. Ejecuta normalize primero en documentos que han pasado por una edición intensa de Word: fusiona ejecuciones adyacentes con formato idéntico para que la búsqueda-reemplazo posterior coincida de forma fiable.
  4. Revisar revisiones. docx_revisions.py list informa cada w:ins y w:del (id, autor, fecha, texto afectado) en cualquier parte del cuerpo, tablas, encabezados o pies. accept-all / reject-all los resuelve en bloque; accept/reject --id N maneja una sola revisión. Aceptar conserva las inserciones y elimina el texto eliminado; rechazar hace lo contrario.
  5. Comentarios. docx_comments.py list devuelve el id, autor, fecha, texto del cuerpo y el texto del documento al que está anclado cada comentario. add --target "alguna frase" ancla un nuevo comentario a la primera aparición de esa frase (las ejecuciones se dividen según sea necesario; el formato se conserva). delete --id N elimina el comentario y sus marcadores sin tocar el texto del documento.
  6. Plantilla. Coloca tokens del estilo {{name}} en el documento. Ejecuta scripts/docx_template.py con un objeto JSON de valores. Usa --strict para fallar cuando queden tokens sin rellenar; la salida JSON lista recuentos filled y unfilled_tokens de cualquier manera.
  7. Verificar (siempre): vuelve a leer la salida con --text o --structure, y ejecuta docx_validate.py en todo lo que hayas producido mediante manipulación de revisiones/comentarios.

Conversión a PDF

No se necesita script. Cuando LibreOffice está instalado, convierte sin interfaz:

soffice --headless --convert-to pdf --outdir outdir/ file.docx

Comprueba primero la disponibilidad (command -v soffice || command -v libreoffice). Si ninguno existe, informa al usuario de que la conversión a PDF no está disponible en este entorno en lugar de improvisar — python-docx no puede renderizar PDFs, y la fidelidad del diseño requiere un renderizador real.

Errores Comunes

  • Tokens divididos entre ejecuciones. Word a menudo fragmenta el texto en varias ejecuciones. Los ayudantes de reemplazo colapsan las ejecuciones coincidentes (el reemplazo hereda el formato de la primera ejecución); ejecutar docx_edit.py normalize primero reduce la fragmentación para todas las ediciones posteriores.
  • Cobertura de revisiones. docx_revisions.py resuelve inserciones y eliminaciones a nivel de ejecución (la gran mayoría). Las revisiones de marcas de párrafo y filas de tabla, los registros de cambio de formato y los movimientos son detectados por --revisions pero no resueltos automáticamente — consulta references/revisions-and-comments.md y pásalos a Word.
  • Hilo de comentarios. Las respuestas y el estado "resuelto" viven en commentsExtended.xml, que esta habilidad ignora; los comentarios que añade son comentarios simples de nivel superior.
  • Los resultados de campo son calculados por Word. toc, page-numbers y las opciones de especificación toc/footer_page_numbers escriben códigos de campo. Word/LibreOffice completa las entradas reales y los números cuando se abre el archivo (Word puede solicitar actualizar campos); python-docx nunca los calcula, por lo que se muestra texto de marcador de posición hasta entonces.
  • La validación es una comprobación de integridad, no una validación de esquema. docx_validate.py verifica el zip, las partes requeridas, los destinos de las relaciones, los bytes mágicos de la imagen y los estilos referenciados. NO es validación XSD — un archivo puede pasarla y aun así contener XML que Word no admite.
  • Los nombres de estilo deben existir. Aplicar un estilo que no está definido en el documento genera KeyError. Los estilos integrados como Heading 1, List Bullet, List Number, Table Grid existen en la plantilla predeterminada; los estilos personalizados deben declararse primero en la especificación de creación.
  • Las listas numeradas se reinician. List Number depende de la numeración predeterminada de Word; las listas separadas en un mismo documento pueden continuar la numeración en lugar de reiniciarse. Advierte a los usuarios que necesiten una numeración precisa de varias listas.
  • Las escrituras en celdas reemplazan el formato. set-cell usa cell.text = ..., lo que reinicia las ejecuciones en esa celda a formato simple.
  • Codificación. Todos los archivos de especificación/valores JSON se leen explícitamente como UTF-8; nunca confíes en los valores predeterminados de la configuración regional al escribir tu propio código de conexión.
  • No descomprimas y uses sed en el XML. Edita a través de los scripts (o python-docx); la sustitución de texto sin formato en document.xml corrompe archivos fácilmente. Usa patch/write_file solo para las entradas JSON, nunca en el propio .docx.

Verificación

  • Después de crear/editar/plantilla, ejecuta docx_read.py out.docx --text y comprueba que aparecen las cadenas esperadas (y que las cadenas antiguas han desaparecido).
  • Después de aceptar/rechazar, docx_revisions.py list debe devolver [] (o solo los ids que dejaste intencionadamente); después de la manipulación de comentarios, docx_comments.py list debe reflejar el cambio y la salida --text debe permanecer sin cambios.
  • docx_validate.py out.docx sale con 0 y "ok": true en un paquete saludable — ejecútalo después de cualquier manipulación de revisión/comentario/campo.
  • Para plantillas ejecutadas con --strict, o comprueba que unfilled_tokens == [].
  • Comprobaciones de estructura: --structure debe mostrar el esquema de títulos esperado y las formas de las tablas; --styles confirma que se aplicaron los estilos personalizados.

Individual skills in this repo

This repo contains 12 individual skills — each has its own dedicated page.

Skills relacionados