manuales-factorpesca/SKILL.md

name, description, license, metadata, allowed-tools

name	description	license	metadata	allowed-tools
manuales-factorpesca	Genera manuales de usuario en PDF con un diseño visual estandarizado (paleta azul marino, tipografía Inter, página Letter) a partir de una aplicación web real. Combina la skill playwright-skill de lackeyjb para capturar pantallas con un generador HTML→PDF basado en Playwright. Aplica estructura editorial (portada, índice, requisitos previos, capítulos numerados, solución de problemas, glosario, aviso de propiedad) y un checklist de calidad antes de entregar. Use when the user asks to create, regenerate, or review a Spanish-language user manual PDF for a web application, or when they need the FactorPesca editorial design system applied to a technical document.	UNLICENSED	author version factorpesca 1.0.0	Bash(node:*) Bash(npm:*) Read Write Edit Glob Grep

manuales-factorpesca

Objetivo

Crear manuales de usuario en PDF para aplicaciones web de FactorPesca, con un diseño visual consistente (paleta azul marino, Inter, página Letter) y contenido verificado a partir de la aplicación real.

Cuándo usar esta skill

• El usuario pide "manual de usuario", "manual PDF", "documentación para usuarios".
• El usuario pide regenerar, actualizar o revisar un manual existente.
• Se necesita aplicar el sistema de diseño FactorPesca a un manual nuevo o existente.

Herramientas

• Captura y navegación: usa la skill playwright-skill de lackeyjb para recorrer la aplicación y obtener las capturas de pantalla. Es la fuente oficial de los artefactos visuales.
• Generación de PDF: usa el script scripts/build-manual.js, que importa Playwright directamente. No es estrictamente necesario instalar Chromium dos veces: la skill de lackeyjb ya lo trae.
• No inventes pantallas: cada captura debe corresponder a un estado real de la aplicación, capturado con Playwright.

Instalación de la skill auxiliar (ejecutar una sola vez por entorno):

# Global
npx skills add lackeyjb/playwright-skill --skill playwright-skill --global --yes

# Local al proyecto
npx skills add lackeyjb/playwright-skill --skill playwright-skill --yes

Estructura de la skill

manuales-factorpesca/
├── SKILL.md                        # este archivo
├── references/
│   ├── estilo.md                   # paleta, tipografía, componentes, tono
│   ├── capturas.md                 # cómo capturar con playwright-skill
│   ├── estructura.md               # anatomía obligatoria del documento
│   └── calidad.md                  # checklist pre-entrega
├── templates/
│   ├── manual.html                 # plantilla semántica
│   ├── manual.css                  # estilos pantalla + @page Letter
│   └── manual.js                   # auto-TOC, anotaciones, numeración
└── scripts/
    ├── build-manual.js             # Playwright: HTML → PDF
    ├── package.json
    └── README.md

Carga references/estilo.md antes de empezar para conocer la paleta y los componentes disponibles. Carga references/estructura.md para conocer la anatomía obligatoria del documento.

Flujo de trabajo

1. Identificar la aplicación, la audiencia y el objetivo del manual.
2. Definir los procesos que se documentarán. Confirmar con el usuario el alcance antes de empezar.
3. Preparar el entorno: instalar dependencias de la skill playwright-skill y de scripts/ (npm install).
4. Capturar las pantallas siguiendo references/capturas.md. Guardar en artifacts/ con el patrón NN-slug.png.
5. Redactar el contenido en español claro, una acción principal por paso.
6. Rellenar templates/manual.html: portada, índice, resumen, requisitos, capítulos, troubleshooting, glosario, aviso de propiedad.
7. Construir el PDF con node scripts/build-manual.js.
8. Verificar el PDF aplicando references/calidad.md.
9. Entregar el archivo final desde dist/.

Reglas editoriales

• Títulos descriptivos y pasos numerados. Una acción principal por paso.
• Indicar el resultado esperado después de acciones importantes.
• Añadir callouts de advertencia antes de operaciones irreversibles.
• Evitar párrafos largos. Dividir en pasos o listas.
• Mantener consistencia con los nombres de botones y campos de la UI.
• Tono: segunda persona, presente indicativo para acciones, futuro para consecuencias. Sin "simplemente", "fácilmente", "obviamente".
• No incluir contraseñas, tokens, datos personales reales ni identificadores confidenciales en capturas ni en el texto.

Capturas de pantalla

• Capturar después de que la UI termine de actualizarse (await page.getByRole(...).waitFor()).
• Usar viewport 1440×900 a 2x de DPI para nitidez en impresión.
• Anotar las capturas con círculos numerados (<ol class="annotations" data-annotations='[{"x":50,"y":30,"n":1}]'>).
• Cerrar banners de cookies, tooltips de onboarding y notificaciones.
• Nombres NN-slug.png dentro de artifacts/.

Detalles completos en references/capturas.md.

Estilo visual obligatorio

• Paleta: azul marino FactorPesca (#0B2545 primary, #F4A300 accent).
• Tipografía: Inter (cuerpo) y JetBrains Mono (código).
• Página Letter 8.5×11", márgenes 22mm.
• Cabecera con nombre del capítulo (eyebrow small caps).
• Pie con "FactorPesca · Manual de usuario" y "Página X de Y".
• Portada a sangre (full bleed navy).

Detalles y excepciones en references/estilo.md.

Estructura obligatoria del documento

1. Portada
2. Índice (auto-generado)
3. Resumen ejecutivo
4. Requisitos previos
5. Capítulos (uno por proceso)
6. Solución de problemas
7. Glosario (opcional)
8. Aviso de propiedad y confidencialidad (obligatoria)

Detalles y reglas de salto de página en references/estructura.md.

Generación del PDF

Tras editar templates/manual.html:

cd manuales-factorpesca
node scripts/build-manual.js

Por defecto produce dist/manual-{aplicacion}-v{version}.pdf. Más opciones en scripts/README.md.

Entrega y calidad

Antes de declarar el manual como terminado:

• Recorrer el manual página a página, marcando cualquier desviación.
• Aplicar el checklist completo de references/calidad.md.
• Corregir en el HTML fuente, no en el PDF.
• Volver a generar hasta que el checklist esté limpio.
• Marcar la versión como released y entregar el archivo desde dist/.

Anti-patrones

• Capturar pantallas con datos personales reales o placeholders que parezcan reales.
• Inventar mensajes, botones, opciones o pantallas que no existen en la app.
• Pegar imágenes sin alinearlas con la posición real del elemento.
• Usar un color fuera de la paleta autorizada.
• Cambiar la tipografía del manual a otra familia que no sea Inter o JetBrains Mono.
• Dejar capturas de pantalla con banners de cookies, tooltips o estados de carga.
• Declarar terminado un manual con pasos sin captura o capturas sin paso.
• Generar el PDF sin -webkit-print-color-adjust: exact (los callouts salen en blanco).