Análisis de la habilidad del agente docx de Anthropic: características, estructura del código, uso y advertencias

Sat, 04 Apr 2026 11:00:00 +0800

skills/docx de Anthropic es esencialmente una especificación de flujo de trabajo más un conjunto de herramientas de script para manejar documentos de Word de manera más confiable con IA.
No solo le dice a un modelo que “genere un .docx”. En cambio, divide el trabajo del documento en rutas explícitas: crear, leer, editar archivos existentes, manejar cambios rastreados, agregar comentarios, convertir formatos y validar la estructura OOXML.

Si lo reducimos a una línea:

Trata .docx como restricciones de compatibilidad ZIP + XML + Office, no como un cuadro negro.

Qué resuelve esta habilidad

Cuando los modelos de uso general manejan archivos de Word, a menudo vemos los mismos patrones de falla:

Generan texto, pero no un .docx estructuralmente válido.
Rompen OOXML al editar documentos existentes.
No saben qué partes XML actualizar para comentarios o seguimiento de cambios.
La salida se abre en una aplicación pero se comporta de manera inconsistente en Word, LibreOffice y Google Docs.
Carecen de una ruta clara sobre cuándo usar pandoc versus desempaquetar/editar/reempaquetar.

El valor de esta habilidad es que adelanta esas decisiones:

Utilice pandoc o desempaquetado para lectura y análisis.
Utilice docx-js para crear nuevos archivos .docx.
Utilice “desempaquetar -> editar XML -> recomprimir -> validar” para los documentos existentes.
Utilice scripts dedicados para realizar seguimiento de cambios/comentarios/operaciones sensibles a esquemas.

Ese enfoque funciona porque los problemas de Word generalmente no tienen que ver con la calidad de la redacción. Se trata de corrección estructural y compatibilidad.

Directorio y estructura de código

Esta habilidad se puede entender en cuatro capas.

1. Capa de orientación: `SKILL.md`

SKILL.md hace dos trabajos importantes:

Define las condiciones de activación.
Si una solicitud menciona Word, .docx, comentarios, seguimiento de cambios, TOC, números de página o formato de documento pulido, se debe activar esta habilidad.
Define rutas de ejecución.
Los diferentes tipos de tareas se asignan a diferentes cadenas de herramientas, en lugar de improvisar cada ejecución.

También captura reglas prácticas de compatibilidad, por ejemplo:

docx-js por defecto es A4, no Carta estadounidense.
El tamaño de la página horizontal debe seguir las normas internas de docx-js.
Las listas no deben crearse a partir de viñetas Unicode manuales.
El ancho de la tabla necesita ajustes coordinados a nivel de tabla y celda.
Se requiere “tipo” de imagen.
Los archivos generados deben ser validados.

Esta es una fuerte señal de que el objetivo no es simplemente “generar algo”, sino “generar algo que sea sólido”.

2. Capa de paquete de Office: `scripts/office/*`

Esta capa trata .docx/.pptx/.xlsx como paquetes Open XML.

`desempaquetar.py`

Este script descomprime archivos y prepara XML para una edición más segura:

Extrae el contenido del paquete ZIP
Imprime XML y .rels
Opcionalmente ejecuta merge_runs para DOCX
Opcionalmente ejecuta simplify_redlines para DOCX
Escapa de comillas tipográficas a entidades XML

Entonces no se trata sólo de descompresión. Normaliza el contenido en una forma fácil de editar.

`paquete.py`

Este script vuelve a empaquetar un directorio en .docx/.pptx/.xlsx.
Antes del envasado, puede:

Ejecutar validación y reparación automática.
Condensar el formato XML de forma segura

Si se proporciona “–original”, se compara y valida con el contexto de origen.
Eso es importante porque “reempaquetado exitosamente” no es igual a “semánticamente seguro”.

`validar.py`

Ésta es la puerta de la calidad. Comprueba:

XML bien formado
Corrección del espacio de nombres
Restricciones de identificación únicas
Consistencia de relación/tipo de contenido
Cumplimiento de XSD
Reglas de preservación de espacios en blanco.
Restricciones de inserción/eliminación/marcador de comentarios

Para el trabajo DOCX, este es un componente principal, no un extra opcional.

`soffice.py`

Este asistente envuelve la ejecución de LibreOffice para entornos restringidos/aislados.
Configura SAL_USE_VCLPLUGIN=svp y puede aplicar una corrección para las limitaciones del socket AF_UNIX cuando sea necesario.

Eso nos dice que la habilidad está diseñada para flujos de trabajo de agentes automatizados, no solo para uso manual local.

3. Capa específica de Word: comentarios, revisiones y líneas rojas

`comentario.py`

Este script agrega comentarios a DOCX, incluida la configuración de paquetes requerida en varias partes:

palabra/comentarios.xml
comentariosExtendido.xml
comentariosIds.xml
comentariosExtensible.xml
marcadores de rango de comentarios en document.xml
declaraciones en [Content_Types].xml y document.xml.rels

Si las partes de comentarios aún no existen, puede inicializar plantillas y relaciones/tipos de contenido requeridos.

`aceptar_cambios.py`

Este script acepta todos los cambios rastreados a través de LibreOffice headless + macro (.uno:AcceptAllTrackedChanges) en lugar de una frágil cirugía XML sin formato.

Esa es una elección pragmática porque aceptar revisiones es una operación a nivel de comportamiento, no solo eliminar etiquetas <w:ins>/<w:del>.

`validadores/redlining.py`

Esta es una de las piezas más valiosas.
Elimina los cambios rastreados para un autor específico tanto en documentos originales como modificados, luego compara el texto resultante para verificar que los cambios estén representados correctamente en el marcado de revisión.

Por tanto, valida la semántica de revisión, no sólo la sintaxis XML.

4. Esquema y capa de soporte: `schemas/`, `helpers/`, `templates/`

`esquemas/`

Contiene archivos XSD relacionados con OOXML/ECMA/Microsoft utilizados por los validadores.
Por lo tanto, la validación se basa en restricciones de esquema formal.

`ayudantes/`

Incluye utilidades como:

-merge_runs.py

simplificar_redlines.py

Estos estabilizan la estructura XML para lograr ediciones y diferencias más claras.

`plantillas/`

Contiene plantillas XML necesarias para admitir comentarios, que incluyen:

comentarios.xml
comentariosExtendido.xml
comentariosIds.xml
comentariosExtensible.xml
personas.xml

Estas plantillas ayudan a evitar inconsistencias a nivel de paquete al crear partes relacionadas con comentarios.

Patrones de uso típicos

Desde SKILL.md, los flujos de trabajo más comunes son:

Escenario 1: leer/analizar un DOCX existente

Utilice pandoc para la extracción a nivel de texto con seguimiento de cambios:

`1`	`pandoc --track-changes=all document.docx -o output.md`

Utilice el desembalaje para la inspección XML sin formato:

`1`	`python scripts/office/unpack.py document.docx unpacked/`

Escenario 2: crear un nuevo DOCX

Utilice docx-js para la generación:

`1`	`npm install -g docx`

Luego valide:

`1`	`python scripts/office/validate.py doc.docx`

Escenario 3: editar un DOCX existente

Flujo de trabajo principal:

1
2
3

python scripts/office/unpack.py document.docx unpacked/
# edit XML under unpacked/
python scripts/office/pack.py unpacked/ output.docx --original document.docx

--original es la parte crítica porque permite controles estructurales y de revisión más sólidos.

Escenario 4: aceptar todos los cambios rastreados

`1`	`python scripts/accept_changes.py input.docx output.docx`

Requiere LibreOffice; útil para producir un archivo limpio posterior a la revisión.

Escenario 5: Agregar comentarios

1
2

python comment.py unpacked/ 0 "Comment text"
python comment.py unpacked/ 1 "Reply text" --parent 0

Aún necesita colocar marcadores de rango de comentarios en document.xml donde debe adjuntarse el comentario.

Advertencias clave para recordar

1. `.docx` no es un archivo de texto sin formato

Una única edición puede implicar cuerpo XML, relaciones, tipos de contenido, partes de comentarios, ID y restricciones de esquema.

2. La generación `docx-js` todavía necesita barreras de seguridad explícitas

Los valores predeterminados pueden ser incorrectos para el diseño objetivo y los objetivos de compatibilidad.

3. Los comentarios y los cambios rastreados son operaciones de varias partes

Son funciones a nivel de paquete, no ediciones de una sola etiqueta.

4. “Se abre correctamente” no significa “modificado correctamente”

Muchos problemas solo surgen más tarde durante la edición, revisión, apertura entre aplicaciones o aceptación de cambios.

5. La preparación ambiental importa

Necesita herramientas como pandoc, LibreOffice/soffice, docx-js y Python deps (defusedxml, lxml) disponibles.

Para qué sirve esta habilidad (y para qué no)

Buen ajuste

Generación de informes de Word por lotes
Producción de documentos formales estructurados.
Ediciones automatizadas a .docx existente
Flujos de trabajo conscientes de los cambios rastreados
Inserción automática de comentarios.
Canalizaciones de documentos basados en agentes/scripts

No es ideal

Casos de salida muy simples solo en PDF
Extracción de texto puro sin requisitos de fidelidad del documento.
Flujos de trabajo de edición visual totalmente manuales.
Expectativas de dependencia cero para la automatización de Word de un extremo a otro

Resumen

skills/docx de Anthropic es fuerte no porque pueda “generar archivos de Word”, sino porque codifica por qué falla la automatización de Word y cómo manejar esos modos de falla sistemáticamente.
Combina generación, edición XML de bajo nivel, semántica de revisión, validación de esquemas y compatibilidad entre aplicaciones en un flujo de trabajo ejecutable.

Si su caso de uso incluye ediciones DOCX existentes, comentarios, cambios rastreados o automatización sensible a la compatibilidad, este diseño es muy práctico y de gran valor.

Ubicación del código: https://github.com/anthropics/skills/tree/main/skills/docx

DOCX on KnightLi Blog

Análisis de la habilidad del agente docx de Anthropic: características, estructura del código, uso y advertencias

Qué resuelve esta habilidad

Directorio y estructura de código

1. Capa de orientación: SKILL.md

2. Capa de paquete de Office: scripts/office/*

desempaquetar.py

paquete.py

validar.py

soffice.py