Crea una Claude Skill que genera Word con tu plantilla

TL;DR: Una Claude Skill es una carpeta con un archivo SKILL.md que enseña a Claude un flujo repetitivo. En este artículo construimos una skill que genera documentos Word (.docx) respetando tu plantilla de marca: misma tipografía, mismos colores, mismo membrete, sin copiar y pegar. Verás la anatomía de una skill, cómo decide Claude activarla y cómo rellenar plantillas con docxtpl, además de qué cambia cuando lo llevas a producción.

El problema: cada informe empieza desde cero

Generar un .docx con IA es fácil. Generar uno que respete tu plantilla corporativa, con su portada, su pie de página y su tipografía exacta, es otra cosa. Lo normal es que el agente devuelva un Word genérico y acabes ajustando estilos a mano cada vez.

Ese ajuste manual es justo el tipo de tarea que una Claude Skill resuelve bien: un procedimiento que repites, con reglas claras y un formato de salida fijo. En lugar de explicarle a Claude cómo es tu marca en cada conversación, lo encapsulas una vez y lo reutilizas. Esto importa porque convierte un flujo frágil (depende de que recuerdes pegar las instrucciones) en uno reproducible y compartible con tu equipo.

¿Qué es una Claude Skill?

Una Claude Skill es una carpeta con instrucciones, scripts y recursos que Claude descubre y carga bajo demanda para realizar mejor una tarea concreta. El único archivo obligatorio es SKILL.md, que contiene metadatos (frontmatter YAML) y las instrucciones en Markdown.

La idea de fondo es la misma que separa un buen diseño de uno enredado: cada pieza tiene una responsabilidad. Si te interesa ese principio aplicado a software, lo desarrollé en la guía sobre separación de responsabilidades. Una skill aplica esa misma lógica al conocimiento del agente: instrucciones por un lado, plantillas por otro, código ejecutable aparte.

Anatomía de una skill

La estructura típica de una skill orientada a documentos es esta:

brand-docx/
├── SKILL.md          # obligatorio: instrucciones + frontmatter
├── scripts/          # opcional: código Python/Bash que Claude ejecuta
│   └── fill_template.py
├── references/       # opcional: docs que Claude lee solo si las necesita
│   └── brand-rules.md
└── assets/           # opcional: plantillas, logos, fuentes para la salida
    ├── plantilla.docx
    └── logo.png

• SKILL.md: el cerebro. Define qué hace la skill y cuándo activarla.
• scripts/: lógica determinista (rellenar la plantilla, validar el XML).
• references/: documentación extensa que solo se carga cuando hace falta.
• assets/: tu plantilla .docx, el logo y las fuentes de marca.

Cómo decide Claude activar tu skill

El campo description del frontmatter es lo que selecciona la skill. Claude no carga la skill entera de entrada: arranca solo con un índice ligero (nombre y descripción de cada skill), lee el SKILL.md completo cuando la tarea encaja, y abre los archivos de references/ o ejecuta los scripts/ solo si los necesita.

Esto se llama progressive disclosure (revelado progresivo) y es la razón de que puedas tener muchas skills sin saturar el contexto. Según la documentación de Anthropic, el índice inicial cuesta unos cientos de tokens frente a las decenas de miles que costaría cargar toda la documentación. Si te preocupa cuánto contexto consumes (y debería, lo expliqué en por qué cruzar los 200k tokens vacía tu presupuesto), este diseño juega a tu favor.

La recomendación oficial de Anthropic es mantener el SKILL.md por debajo de 500 líneas. Si crece más, mueve los detalles a references/.

Implementación paso a paso

1. Crea la carpeta y el SKILL.md

En Claude Code, las skills viven en ~/.claude/skills/ (personales) o .claude/skills/ (del proyecto). El nombre de la carpeta es el nombre del comando. Empieza por el frontmatter, que es lo que de verdad importa:

---
name: brand-docx
description: >
  Genera documentos Word (.docx) con la plantilla de marca de la empresa.
  Úsala cuando el usuario pida un informe, memo, carta o propuesta en Word,
  mencione .docx, plantilla corporativa, membrete o estilo de marca.
---

# Generar Word con plantilla de marca

Cuando el usuario pida un documento Word, NO formatees a mano.
Usa siempre la plantilla en assets/plantilla.docx y el script de relleno.

Fíjate en la description: incluye términos disparadores naturales ("informe", "memo", "plantilla corporativa", ".docx"). Cuantas más variantes reales metas, mejor acierta Claude al decidir si la skill aplica. Es el mismo cuidado que pones al escribir un buen CLAUDE.md sin ambigüedades, pero a nivel de tarea en vez de proyecto.

2. Elige el enfoque técnico correcto

Aquí está la decisión clave. No hay un único modo de producir un .docx, y elegir mal te complica la vida. Esta es la comparativa de los cuatro enfoques habituales:

Enfoque	Cuándo usarlo	Pros	Contras
docx-js (Node)	Crear documentos nuevos desde cero	Control total del layout, generación server-side	No parte de tu plantilla visual; reconstruyes estilos
python-docx	Crear o editar con estilos definidos	API clara en Python, manejo de tablas y texto	Replicar una marca exacta requiere trabajo
docxtpl	Rellenar TU plantilla con datos	Respeta la marca al 100%, usa placeholders Jinja2	Necesitas preparar la plantilla con variables
unpack/pack XML	Editar OOXML a bajo nivel	Acceso a todo (tracked changes, comentarios)	Frágil, verboso, fácil de romper

Para nuestro caso (respetar una plantilla de marca), docxtpl gana sin discusión. Un .docx es por dentro un ZIP con XML, y reconstruir tu marca desde cero con código es perder el tiempo cuando ya tienes el diseño hecho. La skill oficial docx de Anthropic, de hecho, usa docx-js para crear y un flujo de unpack/pack para editar; nosotros aprovechamos la plantilla que ya existe.

3. Prepara la plantilla con placeholders

Abre tu plantilla.docx en Word y, donde quieras texto dinámico, escribe variables con sintaxis Jinja2: {{ titulo }}, {{ cliente }}, {{ fecha }}. Mantén la tipografía y los estilos intactos; docxtpl solo sustituye el texto de los marcadores.

4. El script de relleno

El script vive en scripts/fill_template.py y hace una sola cosa: cargar la plantilla, inyectar el contexto y guardar el resultado.

# Rellena la plantilla de marca con los datos y guarda el .docx final
from docxtpl import DocxTemplate
import json, sys

# El contexto llega como JSON desde Claude (titulo, cliente, fecha, secciones...)
contexto = json.loads(sys.argv[1])

doc = DocxTemplate("assets/plantilla.docx")   # plantilla con estilos de marca
doc.render(contexto)                            # sustituye {{ variables }}
doc.save("salida.docx")                         # conserva fuentes y membrete
print("Documento generado: salida.docx")

Dependencia no estándar: docxtpl (instálala con pip install docxtpl; arrastra python-docx y jinja2). En el SKILL.md indica a Claude que invoque este script en vez de formatear a mano, y que pase el contexto como JSON. El resultado: un Word idéntico a tu marca con el contenido que pidas.

Caso real: propuestas comerciales

El escenario donde esto brilla es el de documentos recurrentes con estructura fija y contenido variable: propuestas comerciales, informes de estado, cartas de contratación. En equipos de producto, una persona redacta el fondo y la marca se aplica sola.

El flujo queda así: pides a Claude "genera una propuesta para el cliente X con estos tres entregables", la skill se activa por la description, Claude redacta el contenido, construye el JSON de contexto y ejecuta el script. Sale un .docx listo para enviar. El antes era media hora peleándote con estilos; el después son segundos. Si además alimentas el contenido desde documentos existentes, el patrón conecta bien con un pipeline de extracción y preparación de datos con Python.

En Producción

El salto del tutorial a producción tiene aristas que conviene conocer antes de confiarle la skill a un equipo.

• Rendimiento y coste: la generación del .docx es local y casi instantánea; el coste real son los tokens que Claude gasta redactando el contenido. Gracias al progressive disclosure, tener la skill instalada no suma apenas contexto hasta que se usa. En un uso normal de desarrollador, hablamos de unos pocos euros al mes en API, no de cientos.
• Manejo de errores: valida el contexto antes de renderizar. Si falta una variable que la plantilla espera, docxtpl falla o deja huecos. Define valores por defecto y un esquema claro de qué campos son obligatorios.
• Versionado: trata la skill como código. Guárdala en el repo bajo .claude/skills/, revisa los cambios en pull request y comparte una sola fuente de verdad. Así evitas que cada persona tenga su propia copia divergente de la plantilla.
• Aislamiento: las skills pueden ejecutar código, así que revisa qué scripts instalas de terceros. Una skill maliciosa es código con permisos. Si quieres entender cómo encajan skills, memoria y seguridad como sistema, lo traté en el artículo sobre agent harness.

Errores comunes y depuración

• Error: la skill no se activa nunca. Causa: la description es vaga o le faltan términos disparadores. Solución: añade frases naturales que un usuario diría de verdad ("propuesta en Word", "informe con membrete").
• Error: el índice de contenidos sale vacío o desactualizado. Causa: un TOC en Word no se recalcula al generar el archivo. Solución: avisa de que hay que abrir el documento y pulsar actualizar campos; no es un bug de la skill.
• Error: los estilos de la plantilla se pierden. Causa: usaste un enfoque que reconstruye el documento (docx-js) en vez de rellenar la plantilla. Solución: vuelve a docxtpl sobre assets/plantilla.docx.
• Error: las comillas tipográficas se rompen. Causa: mezcla de comillas rectas y curvas en el XML. Solución: normaliza el texto del contexto antes de renderizar.

Preguntas frecuentes

¿Una Claude Skill funciona solo en Claude Code?

No. El formato SKILL.md funciona en Claude Code, en claude.ai y a través de la API. Anthropic ofrece skills preconstruidas para Word, Excel, PowerPoint y PDF, y puedes crear las tuyas en cualquiera de esos entornos.

¿Cuál es la diferencia entre SKILL.md y CLAUDE.md?

CLAUDE.md guarda contexto persistente del proyecto que se carga siempre; un SKILL.md describe un flujo de trabajo y solo se carga cuando la tarea lo necesita. Usa CLAUDE.md para hechos del proyecto y skills para procedimientos repetibles.

¿Necesito saber programar para crear una skill?

Para una skill de instrucciones puras, no: basta un SKILL.md con reglas claras. Para generar Word con plantilla sí conviene un script corto en Python, pero el propio Claude puede escribirlo y mantenerlo por ti.

Cierre

Hemos visto cómo una skill convierte un flujo manual y frágil (formatear cada Word a mano) en uno reproducible: una carpeta con SKILL.md, una plantilla en assets/ y un script con docxtpl que respeta tu marca al detalle. La clave está en cuidar la description para que Claude active la skill en el momento justo, y en elegir el enfoque técnico correcto en lugar de reconstruir estilos desde cero. Versiónala como código y tendrás una pieza que todo el equipo reutiliza sin duplicar lógica.

¿Has empaquetado ya algún flujo repetitivo en una skill? Cuéntame qué automatizaste en los comentarios o en Twitter @sergiomarquezp_. En el próximo artículo le daremos una vuelta a cómo compartir skills entre proyectos sin que se conviertan en un vertedero de carpetas.