Mantener un blog técnico con estándares SEO serios siendo desarrollador en solitario es, básicamente, llevar tres trabajos distintos en paralelo: estratega de contenidos, redactor técnico e implementador WordPress. Cada uno requiere habilidades diferentes, herramientas diferentes y, si los haces mal por separado, el resultado es peor que si no hubiera hecho ninguno.
La solución que construí es un pipeline de SEO y generación de contenido con IA: un workspace en Claude Code con tres agentes especializados y cuatro herramientas CLI en Python que automatizan la parte mecánica de cada rol. Este artículo documenta cómo funciona el sistema, por qué lo diseñé así y lo que he aprendido usándolo en producción para gestionar el contenido de este blog.
El artículo que estás leyendo, de hecho, fue publicado usando este mismo pipeline.
El problema que intenté resolver
Publicar contenido con criterios SEO reales no es escribir y subir. Antes de escribir una sola palabra, necesitas saber qué queries atacas, qué intención hay detrás, qué entidades semánticas incluir, cómo se estructura el contenido y qué competidores tienes. Después de escribir, necesitas validar densidad de keywords, jerarquía de headings, ratio de listas y ausencia de frases AI-tell. Al publicar, necesitas configurar Rank Math, asignar schema, generar la imagen destacada y que el post llegue limpio a WordPress.
Si hago todo esto en una sola sesión de Claude Code sin estructura, el contexto se mezcla, la calidad baja y tarde o temprano cometo errores de implementación que luego tengo que corregir a mano.
El problema no es la capacidad del modelo. El problema es que mezclar tres disciplinas distintas en un solo agente generalista produce resultados mediocres en todas ellas. Un estratega SEO que también tiene que escribir copy y configurar WordPress hace peor las tres cosas que tres agentes IA especializados y coordinados entre sí.
Apliqué a este workspace el mismo principio que uso en mi workflow con Claude Code en Archivo Final: agentes especializados que se comunican a través de documentos estructurados, no a través del contexto de chat.
La arquitectura: tres agentes especializados
El workspace vive en gh_seo/ y tiene tres agentes definidos en .claude/agents/, cada uno con instrucciones detalladas, modelo asignado y output esperado.
La separación clave: los agentes de planificación nunca implementan. Cada agente genera su output en un archivo markdown específico. El siguiente agente lee ese archivo antes de empezar. Así el contexto fluye entre agentes sin que yo tenga que copiar y pegar nada.
@seo-strategist — investigación y brief
El estratega se encarga de todo lo que ocurre antes de escribir. Lee los objetivos del sitio desde CLAUDE.md, analiza el espacio de queries con el buscador, identifica competidores y produce un brief semántico completo.
Su output va a .claude/doc/{feature}/seo-strategy.md y contiene el brief completo: cluster de queries (principal + secundarias + long-tail), intención de búsqueda, tipo de contenido, jerarquía de headings con función semántica, entidades a mencionar con sus atributos, plan de interlinking contextual, recomendación de schema markup y el angle de Information Gain que define qué hace único este contenido vs. los 10 primeros resultados.
El agente tiene integrado el concepto de autoridad de tópico como objetivo a largo plazo: cada artículo no es una pieza aislada, sino un nodo en una red semántica que cubre el tema desde ángulos distintos. La estrategia de mapas topicales que usamos define qué topics cubrir y en qué orden para construir esa cobertura sistemáticamente.
@marketing-copywriter — redacción y QA
El copywriter recibe el brief del estratega y escribe el contenido completo. Su mandato es claro: voz de experto accesible, técnico sin ser condescendiente, honesto sobre limitaciones y con experiencia de primera mano como differentiator.
Cosas que no puede hacer:
- Usar “revolucionar”, “transformar”, “disruptivo” u otras palabras vacías de significado
- Usar patrones de relleno genéricos que no aportan información concreta
- Fabricar estadísticas o resultados que no existen
- Explicar lo básico a una audiencia técnica como si no supieran
Antes de entregar el copy, ejecuta el qa_checker.py para validación mecánica. Si el score es inferior a 75/100, identifica los issues concretos y corrige. Solo entonces marca la sesión como lista para implementación.
Su output va a .claude/doc/{feature}/copy-deliverable.md con el artículo completo, los meta SEO (title, description, focus keyword), el slug recomendado, el prompt para la imagen destacada y las notas para el implementer.
@wp-implementer — publicación técnica
El implementer es el único que toca WordPress. Lee el copy del copywriter y el brief del estratega, genera la imagen destacada con Gemini y publica en WordPress vía REST API.
Tiene una regla absoluta: siempre publicar como draft salvo instrucción explícita de Gabriel(osea yo). Una publicación en producción es irreversible desde el punto de vista de SEO (el post ya aparece en el índice, los bots lo rastrean). Mejor revisar el draft manualmente antes de publicar.
Las herramientas CLI del pipeline
Los tres agentes tienen acceso a un conjunto de herramientas Python en tools/. Son scripts de línea de comandos con argparse, diseñados para ser llamados desde Claude Code con comandos concretos.
serp_analyzer.py — análisis de competidores
Scraping y análisis de métricas SEO sobre URLs de competidores. Extrae word count, estructura de headings, links internos y externos, imágenes con audit de alt text, schema JSON-LD y meta fields.
tools/.venv/bin/python tools/serp_analyzer.py analyze \
--url "https://ejemplo.com/post" \
--output competitive-analysis/ejemplo.json
tools/.venv/bin/python tools/serp_analyzer.py batch \
--urls-file urls.txt \
--output-dir competitive-analysis/
El estratega lo usa para calibrar la longitud de contenido, identificar gaps semánticos y entender qué estructura de headings usan los primeros resultados.
qa_checker.py — control de calidad mecánico
El checker más importante del pipeline. Hace una auditoría mecánica del contenido antes de publicar: detecta problemas que el modelo tiende a introducir aunque le digas que no.
Checks que ejecuta:
- Word count total y por sección
- Jerarquía de headings (H1 único, sin saltos de nivel)
- Densidad de keyword focus (rango 0.5%-2.5%)
- Ratio listas/párrafos (contenido demasiado denso sin estructura)
- Repetición de n-gramas (frases calcadas que suenan a template)
- Frases AI-tell (lista de 25 patrones en español)
- Legibilidad (media de palabras por frase ≤25)
- Anchors descriptivos (detecta “aquí”, “haz clic”, “este enlace”)
- Longitud de meta fields (title ≤60, description ≤155)
tools/.venv/bin/python tools/qa_checker.py check \
--file .claude/doc/feature/copy-deliverable.md \
--keywords "pipeline seo,agentes ia"
Puntuación base 100, deducciones por severidad (high: -15, medium: -5, low: -2). Score ≥75 = apto para publicar.
En la práctica, el contenido técnico con mucho código puntúa algo más bajo porque los bloques de código rompen algunos ratios. El copywriter aprende a contextualizar el score según el tipo de contenido.
image_generator.py — imagen destacada con Gemini
Genera la imagen destacada del post desde un prompt en texto usando Gemini 2.5 Flash Image. El copywriter incluye el prompt en sus notas de handoff.
tools/.venv/bin/python tools/image_generator.py generate \
--prompt "An abstract isometric illustration of a modular content pipeline..." \
--output outputs/featured_image.png \
--aspect-ratio 16:9 \
--size 2K
Coste aproximado: $0.04 por imagen. Es lo suficientemente barato para usarlo en todos los posts sin pensarlo dos veces.
La herramienta también optimiza imágenes existentes para WordPress: redimensiona a 1920px y convierte a JPEG al 85% de calidad, que es el sweet spot para el equilibrio tamaño/calidad en web.
Para entender la integración de Gemini en estrategia de contenidos más allá de la imagen, hay un artículo relacionado sobre Gemini para estrategia de contenidos.
wp_publisher.py — publicación WordPress REST API
El tool más complejo del pipeline. Gestiona toda la comunicación con WordPress a través de la REST API: convierte el markdown a HTML, sube el post, asigna categorías y tags, configura los meta fields de Rank Math y sube la imagen destacada a la Media Library.
Autenticación con WordPress Application Passwords — sin contraseñas en el código, solo variables de entorno en .env.
tools/.venv/bin/python tools/wp_publisher.py publish \
--file .claude/doc/feature/copy-deliverable.md \
--title "Título del post" \
--status draft \
--category "Lab" \
--seo-title "SEO Title (máx 60 chars)" \
--seo-description "Meta description (máx 155 chars)" \
--focus-keyword "keyword principal" \
--featured-image outputs/featured_image.jpg
Para que los campos de Rank Math (title, description, focus keyword) funcionen vía API, hay que añadir un snippet en el functions.php del Astra Child theme(que es el que estoy usando) que registra esos campos como meta expuestos en la REST API. Sin él, el post se publica pero sin los campos SEO:
add_action('init', function () {
$seo_fields = ['rank_math_title', 'rank_math_description',
'rank_math_focus_keyword', 'rank_math_canonical_url'];
foreach ($seo_fields as $field) {
register_post_meta('post', $field, [
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'auth_callback' => function () { return current_user_can('edit_posts'); },
]);
}
});
Esto conecta con el trabajo previo sobre publicar en WordPress automáticamente con IA y extiende el concepto de WordPress API con Python con la capa de SEO y agentes.
El flujo completo: de una idea a un post publicado
El flujo real de una publicación nueva tiene estos pasos concretos:
1. Crear la sesión
Antes de invocar ningún agente, se crea el archivo de sesión en .claude/sessions/{feature}.md desde el template. Este archivo es el canal de comunicación entre los agentes IA del pipeline. No hay llamadas directas entre ellos — solo documentos estructurados.
2. @seo-strategist investiga y produce el brief
El estratega lee CLAUDE.md para contexto del proyecto, consulta las referencias de metodología en .claude/skills/seo/references/ y, si el tema lo requiere, analiza competidores con serp_analyzer.py. El output completo va a .claude/doc/{feature}/seo-strategy.md. Cuando termina, rellena “Decisiones estratégicas” en la sesión y avanza el estado a copy.
3. @marketing-copywriter escribe el contenido
El copywriter lee TODO el documento de sesión antes de escribir — incluyendo las decisiones del estratega. Lee también el brief completo en .claude/doc/{feature}/seo-strategy.md. Escribe el artículo siguiendo la jerarquía de headings del brief, integrando naturalmente las entidades y respetando la voz del blog.
Antes de entregar, ejecuta qa_checker.py. Si el score es <75, revisa los issues del informe y aplica las correcciones necesarias. El output final va a .claude/doc/{feature}/copy-deliverable.md. Rellena “Decisiones de copy” en la sesión y avanza el estado a implementation.
4. @wp-implementer publica
El implementer lee el documento de sesión y el contenido del copywriter, genera el featured image con image_generator.py usando el prompt incluido en las notas de handoff, y ejecuta wp_publisher.py para publicar el post como draft con todos los meta fields de Rank Math. Rellena “Implementación” en la sesión y avanza el estado a done.
5. Revisión manual
El draft queda en WordPress para revisión antes de publicar. Verifico meta tags, schema, preview en móvil y que los internal links funcionen. Cuando todo está correcto, publico.
Las sesiones compartidas: cómo se comunican los agentes
El archivo de sesión es la pieza de coordinación más importante del sistema. Es el contrato entre agentes.
Su estructura:
.claude/sessions/{feature}.md
├── Estado actual (backlog → strategy → copy → implementation → done)
├── Decisiones estratégicas (rellena @seo-strategist)
├── Decisiones de copy (rellena @marketing-copywriter)
└── Implementación (rellena @wp-implementer)
Cada agente lee el documento completo antes de empezar, incluso las secciones que no son suyas. Esto es intencional. El copywriter necesita saber las decisiones del estratega. El implementer necesita saber las notas del copywriter. El contexto fluye hacia adelante sin fricción.
El mismo patrón de sesiones compartidas que uso en Archivo Final, pero aplicado al workflow de contenido. Los Claude Code templates explican cómo estructurar estos archivos de agentes de forma que sean reutilizables entre proyectos.
Lo que funciona y lo que no
Lo que funciona bien:
- La separación de responsabilidades es la decisión más valiosa. El @seo-strategist produce briefs más rigurosos cuando no tiene que preocuparse de si el texto fluye bien. El @marketing-copywriter escribe mejor cuando no tiene que pensar en slugs y schema markup. El @wp-implementer no comete errores de configuración porque solo hace eso.
- El
qa_checker.pydetecta consistentemente los mismos problemas que antes llegaban al draft: frases de relleno genéricas, headings mal jerarquizados y anchors sin descripción. No es perfecto, pero es barato de ejecutar y elimina el 80% de los issues mecánicos. - El featured image generado con Gemini tiene calidad suficiente para publicación. $0.04 por imagen es un coste irrelevante. El prompt del copywriter, cuando es específico sobre estilo artístico y evita los clichés (chips, circuitos, robots azul neón), produce resultados decentes.
Lo que no funciona bien todavía:
El @seo-strategist a veces produce briefs demasiado ambiciosos en términos de word count. Un artículo de 3000 palabras no es mejor que uno de 1800 si la diferencia son secciones de relleno. Hay que filtrar activamente el brief antes de pasarlo al copywriter.
Los meta fields de Rank Math requieren el snippet de PHP en functions.php. Si no está instalado, los posts se publican sin title tag ni meta description configurados. Es una dependencia de configuración que hay que verificar antes de cada sesión de publicación.
Conclusión
Este pipeline de SEO y generación de contenido con IA no es una solución perfecta. Es una iteración estable sobre el problema de publicar contenido de calidad siendo un solo desarrollador con tiempo limitado.
Lo que sí consigue: que la calidad mínima de cada publicación sea predeciblemente buena. Los agentes especializados, combinados con las herramientas de verificación mecánica, eliminan los errores de descuido. El tiempo que antes dedicaba a configurar Rank Math, redimensionar imágenes o verificar la densidad de keywords lo dedico ahora a lo que sí requiere criterio humano: revisar el brief, ajustar el tono y decidir qué publicar.
Si estás gestionando un blog técnico y quieres montar algo similar, el punto de entrada más fácil es el wp_publisher.py + un agente copywriter bien definido. El resto del sistema lo puedes ir añadiendo según lo necesites.
El código de este workspace está en un repositorio privado, pero los patrones son directamente aplicables. Si tienes preguntas concretas o quieres que profundice en alguna parte del sistema, escríbeme.
