IA en el desarrollo
Cómo trabajo con agentes en esta web
Uso Claude Code a diario; cada PR lo reviso y lo firmo yo. Aquí está el contexto que le doy, las skills que usa, cuándo delega en subagentes y las reglas que no se salta.
El catálogo se genera al compilar desde .claude/skills. Ver también el sistema de diseño y el CMS.
Cómo funciona
Contexto, skills y agentes
AGENTS.md · CLAUDE.md
Contexto del proyecto
Lo que el agente lee al empezar cada sesión: qué es la web, cómo fluye el contenido del CMS, los comandos y las reglas. CLAUDE.md solo importa AGENTS.md, para que sirva a cualquier agente.
.claude/skills/<nombre>/SKILL.md
Skills
Instrucciones empaquetadas para un tipo de tarea. Al empezar, el agente solo ve el nombre y la descripción de cada una; carga el resto cuando la tarea encaja, o cuando la pido con /nombre.
references/ · scripts/
Referencias y scripts
Material que la skill abre solo si lo necesita: guías de WCAG, plantillas o un script como el de ui-qa, que se ejecuta en lugar de leerse. Así el contexto no se llena de lo que no toca.
Explore · Plan · general-purpose
Agentes y subagentes
El agente principal puede delegar una búsqueda o una investigación en otro con contexto propio. Vuelve solo la conclusión, y el hilo principal sigue limpio.
La descripción es lo que decide
El agente elige una skill leyendo solo su descripción, así que cada una dice qué hace y en qué situaciones usarla, con las palabras que yo usaría al pedirlo. Las propias están en español y nombran archivos del repositorio; las de terceros conservan su texto original para poder actualizarlas.
markdown · .claude/skills/ui-qa/SKILL.md
---
name: ui-qa
description: Comprueba la UI de pacosegovia.es en Chrome real, con toques
y clics de verdad en cinco tamaños. Úsala después de tocar componentes,
estilos, animaciones, z-index o el layout…
---
# QA de la UI
…Skills
12 skills instaladas
Propias
Escritas para este repositorio · 4
/cms-schema
Cambiar campos o colecciones de Payload y llevarlos hasta la web: esquema, migración, cms-pull y componentes.
Descripción que lee el agente
Cambia el esquema de Payload en cms/ (campos, pestañas, globals, colecciones, plugins) y lo lleva hasta la web sin romper el despliegue. Úsala al añadir, renombrar o quitar un campo, o al tocar cms/src/collections, cms/src/globals o scripts/cms-pull.ts.
/deploy
1 script
Preparar, lanzar y diagnosticar despliegues de la web (GitHub Actions y FTPS) y del CMS (Docker).
Descripción que lee el agente
Prepara, lanza, verifica y diagnostica despliegues de la web (GitHub Actions y FTPS) y del CMS (Docker). Úsala antes de mergear a main, al preguntar si un PR está listo, cuando falle el workflow Desplegar, o al tocar deploy.yml, check-deploy-plan.py o CMS_URL.
/site-copy
Escribir y revisar textos con la voz acordada, y decir si van al CMS o al repositorio.
Descripción que lee el agente
Escribe o revisa los textos de pacosegovia.es con la voz acordada y los deja en el lugar correcto (CMS o repositorio). Úsala al redactar o corregir titulares, servicios, casos, trayectoria o contacto, en español o inglés, y al revisar si un texto suena a IA.
/ui-qa
1 script
Abrir la web en Chrome y pulsarla de verdad en cinco tamaños, en claro y oscuro, buscando solapes y desbordes.
Descripción que lee el agente
Comprueba la UI de pacosegovia.es en Chrome real, con toques y clics de verdad en cinco tamaños. Úsala después de tocar componentes, estilos, animaciones, z-index o el layout, antes de mergear un cambio visual, y cuando algo no se pueda pulsar, se solape o se desborde en móvil.
Calidad web
web-quality-skills · MIT · 6
/web-quality-audit
v2.0 · 1 referencia · 1 script
Auditoría completa: rendimiento, accesibilidad, SEO, buenas prácticas y navegación por agentes.
Descripción que lee el agente
Run an evidence-led web quality audit covering performance, accessibility, SEO, best practices, and agentic browsing. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".
/performance
v2.0 · 2 referencias
Tiempo de carga, peso de la página y recursos que bloquean.
Descripción que lee el agente
Optimize web performance for faster loading and better user experience. Use when asked to "speed up my site", "optimize performance", "reduce load time", "fix slow loading", "improve page speed", or "performance audit".
/core-web-vitals
v2.0 · 3 referencias
LCP, INP y CLS con datos de campo y de laboratorio.
Descripción que lee el agente
Optimize Core Web Vitals (LCP, INP, CLS) for better page experience using field and lab evidence. Use when asked to "improve Core Web Vitals", "fix LCP", "reduce CLS", "optimize INP", "page experience optimization", or "fix layout shifts".
/accessibility
v2.0 · 2 referencias
WCAG 2.2: teclado, lectores de pantalla, contraste y semántica.
Descripción que lee el agente
Audit and improve web accessibility following WCAG 2.2 guidelines. Use when asked to "improve accessibility", "a11y audit", "WCAG compliance", "screen reader support", "keyboard navigation", or "make accessible".
/best-practices
v2.0 · 1 referencia
Cabeceras de seguridad, contenido mixto, APIs obsoletas y errores de consola.
Descripción que lee el agente
Audit a rendered page for Lighthouse best practices — security headers, mixed content, deprecated APIs, and console errors. Use when asked for a "Lighthouse best practices audit", "security headers", "mixed content", or "console errors on the page".
/seo
v2.0 · 1 referencia
Metadatos, datos estructurados, sitemap e indexación.
Descripción que lee el agente
Optimize for search engine visibility and ranking. Use when asked to "improve SEO", "optimize for search", "fix meta tags", "add structured data", "sitemap optimization", or "search engine optimization".
Marketing
coreyhaines31/marketingskills · MIT · 2
/cro
v2.0.3 · 2 referencias
Revisar la portada o el formulario de contacto y ordenar los cambios por impacto en conversión.
Descripción que lee el agente
When the user wants to optimize, improve, or increase conversions on any marketing page or form — including homepage, landing pages, pricing pages, feature pages, lead capture forms, or contact forms. Also use when the user says 'CRO,' 'conversion rate optimization,' 'this page isn't converting,' 'improve conversions,' 'why isn't this page working,' 'my landing page sucks,' 'form abandonment,' 'nobody's converting,' 'low conversion rate,' or 'this page needs work.' Use this even if the user just shares a URL and asks for feedback. For signup/registration flows, see signup. For post-signup activation, see onboarding. For popups/modals, see popups.
/ai-seo
v2.12.0 · 15 referencias
Que ChatGPT, Perplexity o Claude citen la web: estructura, llms.txt y legibilidad para agentes.
Descripción que lee el agente
When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'llms-full.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' 'agent-readable site,' 'agent readiness,' 'is my site agent-ready,' 'WebMCP,' 'do listicles still work for AI,' 'ChatGPT stopped citing comparison pages,' 'how do LLMs see our brand,' 'LinkedIn for AEO,' or 'AI citation format shift.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema.
De las más de cincuenta skills de marketing de Corey Haines me quedé con dos, las que cubren algo que las demás no cubren. Cada skill instalada suma su descripción al contexto de todas las sesiones y puede activarse donde no toca: las de redacción competían con site-copy, que ya tiene la voz y las decisiones de la web.
Agentes y subagentes
Delegar solo cuando compensa
Un subagente arranca de cero: no sabe lo que ya se ha leído en la conversación y tiene que volver a descubrirlo. Por eso no lo uso para tareas pequeñas. Compensa cuando hay trabajo independiente que se puede hacer en paralelo, o cuando una búsqueda llenaría el hilo principal de archivos que luego no importan.
Ejemplo real: al preparar esta página, un subagente leyó el catálogo de marketing-skills.com mientras el agente principal revisaba el repositorio de las skills. Volvió con la lista resumida y el agente principal decidió qué instalar.
- Agente principal
- Casi todo: leer, editar, ejecutar y verificar. Mantiene el hilo de la tarea y es quien decide.
- Explore
- Búsquedas amplias en el código cuando solo importa dónde está algo, no el contenido de cada archivo. Solo lectura.
- Plan
- Diseñar un cambio grande antes de tocar nada: archivos afectados, orden y riesgos. Solo lectura.
- general-purpose
- Investigaciones de varios pasos que no dependen del resto, como revisar varias fuentes externas a la vez.
- web-fetch
- Leer una página pública y devolver la respuesta, no la página entera.
Flujos de trabajo
Qué skills entran en cada tarea
Cambio visual
- Rama nueva
- Código y pnpm check
- ui-qa en cinco tamaños
- accessibility si toca interacción
- deploy: PR y revisión
Texto nuevo
- site-copy: voz y decisiones tomadas
- Borrador en español e inglés
- Repaso del conjunto, no solo de la frase
- Lo publico yo en el CMS
Mejorar conversión
- cro sobre la portada y el formulario
- Cambios ordenados por impacto
- site-copy para el texto final
- ui-qa si cambia la interfaz
Visibilidad
- seo: técnico y metadatos
- ai-seo: citas en asistentes
- web-quality-audit al final
Campo nuevo en el CMS
- cms-schema: esquema y migración
- Base de datos de prueba
- cms-pull y componente
- deploy: CMS antes que la web
Reglas
Lo que el agente no hace
- Nada va a producción sin mí
- Un push a main publica la web. El agente trabaja en una rama y solo mergea si se lo pido; cada PR lo reviso y lo firmo yo.
- Despliegue con red
- El agente nunca lanza una sincronización FTP a mano. Un script revisa el plan antes de desplegar y lo para si fuera a borrar algo fuera de lo que genera el build.
- Secretos fuera del chat
- No imprime variables de entorno, ni para diagnosticar: solo comprueba si están definidas.
- Producción no es un banco de pruebas
- Los cambios de esquema se prueban contra otra base de datos, nunca contra la del CMS publicado.
- La CSP decide
- Ningún script, estilo o recurso externo entra sin revisar la política de seguridad de contenido.
- Verificar antes de dar por hecho
- Tipos, build y ui-qa antes de decir que algo funciona. Si un paso falla o se salta, se dice.
Estas reglas están escritas en AGENTS.md y en las skills de despliegue y CMS, con el motivo de cada una. Una regla sin motivo se acaba saltando.
Instalar y usar
Cómo añadir una skill
Una skill es una carpeta con un SKILL.md. Las del proyecto viven en .claude/skills y viajan con el repositorio, así que cualquiera que lo clone trabaja con las mismas.
Para usarlas basta con pedir la tarea: el agente las carga solo cuando la descripción encaja. También se pueden lanzar a mano con /nombre, por ejemplo /ui-qa después de tocar un componente.
sh
# Una o varias skills del repositorio de marketing
npx skills add coreyhaines31/marketingskills --skill cro ai-seo
# O copiarlas a mano: cada skill es una carpeta
.claude/skills/cro/
SKILL.md # nombre, descripción e instrucciones
references/ # se abren solo si hacen falta
LICENSE