SPEC y SKILL:
el nivel siguiente cuando
las instrucciones no son suficientes
Las instrucciones del proyecto definen cómo trabaja Claude contigo. Pero cuando el trabajo crece en volumen y en complejidad, necesitas algo más. Esto es lo que tengo montado en producción después de más de 50 proyectos iterados.
Instrucciones del proyecto: le dicen a Claude cómo trabajar contigo. El tono, las reglas, los límites.
SPEC: documentos de referencia que Claude consulta. Estándares visuales, paletas, normas de formato, identidad de marca. Lo que no cambia.
SKILL: procedimientos paso a paso que Claude ejecuta. El pipeline técnico exacto para una tarea concreta. Lo que se repite.
Las tres capas juntas hacen que Claude funcione igual de bien en la sesión 1 que en la sesión 50. Sin que tú repitas nada.
- 01 El problema que las instrucciones no resuelven
- 02 Qué es una SPEC y cuándo la necesitas
- 03 Qué es una SKILL y cuándo la necesitas
- 04 Las tres capas: cómo encajan
- 05 Mis SPEC y SKILL reales: el proyecto de Elio y el de contenido
- 06 Cómo escribir una SPEC desde cero
- 07 Cómo escribir una SKILL desde cero
- 08 Errores que cometí al montar este sistema
- 09 Los números reales antes y después
- —— Conclusión
El problema que las instrucciones no resuelven
Por qué a partir de cierto punto, las instrucciones no son suficientes.
Llevo más de un año trabajando con Claude. He iterado más de 50 proyectos.
Hubo un momento en que las instrucciones del proyecto estaban bien escritas, el tono estaba definido, las reglas de trabajo eran claras. Y aun así Claude seguía produciendo cosas inconsistentes.
Un carrusel con los colores ligeramente distintos al anterior. Un prompt de agente de voz que olvidaba una buena práctica básica. Un artículo con una estructura diferente a los demás.
No era fallo de Claude. Era fallo de arquitectura.
Las instrucciones le decían cómo comportarse. Pero no le daban los estándares de referencia ni el procedimiento exacto para ejecutar.
Las instrucciones del proyecto tienen un límite natural. Son texto libre. Cuanto más largas, más difícil para Claude mantener coherencia con todo a la vez.
La solución no es escribir instrucciones más largas. Es separar lo que pertenece a instrucciones de lo que pertenece a documentos de referencia y procedimientos.
La pregunta que lo aclara todo
¿Esto es una regla de comportamiento o es información de referencia?
Si es una regla de comportamiento: va en las instrucciones del proyecto.
Si es información de referencia que Claude consulta cuando la necesita: va en una SPEC.
Si es un procedimiento paso a paso que Claude ejecuta de forma idéntica cada vez: va en una SKILL.
Qué es una SPEC y cuándo la necesitas
Un documento de referencia que Claude consulta. No instrucciones. Estándares.
Una SPEC es un documento que define estándares. Lo que no cambia. El conocimiento de referencia que Claude necesita consultar para producir trabajo consistente.
La diferencia con las instrucciones es importante. Las instrucciones definen comportamiento. La SPEC define conocimiento.
| Instrucciones del proyecto | SPEC |
|---|---|
| "No generes código sin validar el stack primero" | Paleta de colores exacta con valores hex |
| "Pregunta antes de proponer arquitecturas" | Escala tipográfica completa por elemento |
| "Usa primera persona en todo el contenido" | Ejemplos de frases que suenan a la marca y que no |
| "Sin emojis bajo ninguna circunstancia" | Reglas de formato de LinkedIn con medidas exactas |
| "Itera conmigo antes de entregar el borrador final" | Estructura de slides con zonas seguras en píxeles |
Cuándo necesitas una SPEC
Necesitas una SPEC cuando Claude tiene que producir trabajo que respete estándares fijos que no caben bien en instrucciones de texto libre.
Los casos más comunes:
- Identidad visual. Colores exactos, tipografías, tamaños, proporciones, elementos de marca. Todo lo que tiene un valor fijo que Claude tiene que respetar para producir piezas coherentes.
- Voz y tono. Cómo hablas, qué vocabulario usas, qué evitas, ejemplos reales de tu estilo. Una SPEC de voz bien escrita es lo que evita que Claude produzca texto genérico de LinkedIn cuando le pides un post.
- Formato técnico. Especificaciones de un formato concreto: medidas de un PDF, estructura de un documento, campos de un formulario, parámetros de una API.
- Reglas de negocio. Lógica que Claude tiene que aplicar de forma consistente: criterios de cualificación, condiciones de precios, política de descuentos, flujos de decisión.
Ejemplo real: SPEC-01 de identidad visual
Tengo una SPEC que define toda la identidad visual de mi marca personal para carruseles de LinkedIn. Incluye la paleta de colores completa con los hex exactos, los dos tipos de letra con todos sus pesos, la escala tipográfica con el tamaño exacto de cada elemento en cada contexto, las reglas de espaciado, los elementos de marca obligatorios en cada slide y una lista explícita de lo que nunca se hace.
Claude la lee antes de generar cualquier pieza visual. El resultado es consistente de una pieza a otra sin que yo tenga que supervisar los detalles visuales.
Estructura de una SPEC
No hay una estructura universal. Lo que sí tiene que haber:
- Un título y propósito claro. Una línea que dice exactamente qué define este documento.
- Las reglas o estándares, con valores concretos. No "usa colores de la marca" sino los hex exactos.
- Ejemplos cuando aplica. En una SPEC de voz, ejemplos de frases que suenan bien y frases que no. En una SPEC visual, referencias de lo que se hace y lo que no se hace.
- Una sección explícita de lo que nunca se hace. Esto es lo que más ahorra correcciones.
# SPEC-02: Voz y tono
## Propósito
Define cómo se escribe y comunica esta marca.
Si no suena a esto, se reescribe.
## Lo que sí
- Directa. Primera frase va al grano.
- Técnica. Con datos, métricas, ejemplos concretos.
- Honesta. Cuenta errores sin maquillarlos.
- Primera persona siempre.
## Lo que nunca
- Emojis o emoticonos. Nunca.
- Frases hype: "sin filtros", "game changer", "disruptivo".
- Coaching style: "¿Te atreves?", "Transformación".
- Pedir likes o comentarios.
## Ejemplos que suenan bien
- "334 llamadas analizadas. Sin escuchar ni una."
- "Lo activé. Lo probé. Y ya no he vuelto atrás."
## Ejemplos que no suenan bien
- "Estoy emocionada de compartir este increíble logro."
- "¿Te atreves a dar el salto?"Qué es una SKILL y cuándo la necesitas
Un procedimiento paso a paso. No estándares. Ejecución.
Una SKILL es diferente. No define qué tiene que ser el output. Define cómo ejecutar el proceso para llegar a él.
Si la SPEC responde a «¿cómo tiene que quedar esto?», la SKILL responde a «¿cómo se hace esto exactamente?».
Las SKILL son especialmente útiles cuando la tarea implica herramientas, código o un pipeline técnico con pasos concretos que tienen que ejecutarse en un orden específico y con parámetros exactos.
Cuándo necesitas una SKILL
- Tareas técnicas repetitivas. Generación de archivos, conversiones, pipelines de datos, scripts que se ejecutan con la misma lógica siempre.
- Procesos con parámetros exactos. Cuando hay valores específicos que si se equivocan, el output falla. Viewport de Playwright, tamaño de página de ReportLab, tiempo de espera para carga de fuentes.
- Workflows con orden específico. Cuando los pasos tienen que ejecutarse en una secuencia concreta y saltarse uno o cambiar el orden rompe el resultado.
- Procesos que han tenido errores documentados. Si algo ha fallado y has encontrado la solución, esa solución va en la SKILL para que no se repita el error.
La SKILL tiene memoria de errores
Una de las cosas más útiles de las SKILL es que puedes documentar en ellas los errores que ya cometiste. «No usar viewport 1080×1080 en Playwright: incorrecto, debe ser 1080×810.» «No olvidar wait_for_timeout mínimo 3000ms para carga de fuentes.»
Claude lee la SKILL antes de ejecutar. Si el error está documentado, no se repite.
Estructura de una SKILL
- Propósito: qué tarea resuelve esta SKILL.
- Dependencias: qué SPEC u otros documentos hay que leer antes.
- Pipeline paso a paso: cada paso numerado, con el código o los comandos exactos cuando aplica.
- Parámetros críticos: los valores que no pueden cambiarse. Con el valor correcto explícito.
- Errores comunes a evitar: los que ya ocurrieron, documentados para que no se repitan.
- Validación final: checklist de lo que tiene que estar bien antes de dar el trabajo por terminado.
# SKILL-01: Generar carrusel LinkedIn
## Propósito
Pipeline completo para generar carrusel PDF
con identidad visual de marca.
Leer SPEC-01, SPEC-02 y SPEC-03 antes de ejecutar.
## Pipeline
### Paso 1: Definir contenido
Antes de escribir código, definir:
- Tema y número de parte (si es serie)
- Número de slides (6-10 óptimo, 8 ideal)
- Estructura aplicando las 4 mecánicas del algoritmo
- Copy de cada slide
### Paso 2: Generar HTML por slide
Tamaño OBLIGATORIO: 1080 x 810 px (4:3)
[CSS base obligatorio incluido en la SKILL]
[Estructura HTML de cada slide incluida]
### Paso 3: Renderizar a PNG
# Playwright — viewport OBLIGATORIO: 1080x810
page = browser.new_page(viewport={"width": 1080, "height": 810})
page.goto(f"file://{html_path.absolute()}")
page.wait_for_timeout(3000) # Mínimo 3000ms para fuentes
### Paso 4: Compilar PDF
# ReportLab — page size OBLIGATORIO: (1080, 810)
PAGE_SIZE = (1080, 810)
## Errores comunes a evitar
- Usar viewport 1080×1080 — INCORRECTO
- wait_for_timeout menor a 3000ms — fuentes no cargan
- Rutas relativas en Playwright — usar file:// con path absolutoLas tres capas: cómo encajan
Instrucciones, SPEC, SKILL. Cada una en su sitio.
Las tres capas no compiten entre sí. Se complementan. Y cada una tiene su función específica dentro del proyecto.
Instrucciones del proyecto
Definen cómo trabaja Claude contigo. Tono, comportamiento, reglas de proceso, límites. Se aplican siempre, en cada chat del proyecto.
SPEC
Documentos de referencia que Claude consulta cuando los necesita. Definen estándares: identidad visual, voz, formato. Son el «qué tiene que ser» del output.
SKILL
Procedimientos de ejecución. Claude los lee antes de ejecutar una tarea técnica concreta. Son el «cómo se hace» del output.
Output consistente
Las tres capas juntas producen resultados coherentes, sin que tú tengas que repetir contexto ni supervisar detalles en cada sesión.
| Capa | Qué define | Cuándo se aplica | Ejemplo real |
|---|---|---|---|
| Instrucciones | Comportamiento de Claude contigo | Siempre, en cada chat | "No generes código sin validar el stack" |
| SPEC | Estándares del output | Cuando el output tiene que respetar estándares fijos | Paleta de colores exacta, voz y tono, medidas de LinkedIn |
| SKILL | Procedimiento de ejecución | Cuando la tarea implica un pipeline técnico específico | Pipeline HTML → Playwright → ReportLab para carruseles |
Lo que nunca hay que hacer
Meter todo en las instrucciones del proyecto. He visto esto muchas veces y lo he hecho yo misma al principio. Instrucciones de 3000 palabras mezclando comportamiento, estándares visuales, procedimientos técnicos y reglas de negocio.
El resultado: Claude se satura. Aplica algunas cosas y se le olvidan otras. El output es inconsistente aunque el sistema esté bien pensado.
Cada capa tiene su lugar. Lo que va en SPEC, en SPEC. Lo que va en SKILL, en SKILL.
Mis SPEC y SKILL reales: el proyecto de Elio y el de contenido
Lo que tengo montado en producción ahora mismo.
Tengo dos proyectos principales en Claude. El proyecto de agentes de voz, donde construyo y mejoro a Elio. Y el proyecto de contenido, donde genero carruseles de LinkedIn, artículos y materiales de marca.
Son radicalmente distintos. Y sus SPEC y SKILL también.
Proyecto de contenido: las SPEC
Este proyecto tiene 3 SPEC subidas como archivos:
- SPEC-01: Identidad visual. Paleta completa con hex exactos. Los dos tipos de letra con todos sus pesos. Escala tipográfica elemento a elemento. Los elementos de marca obligatorios en cada pieza. La lista de lo que nunca se hace: sin emojis, sin sombras, sin bordes redondeados grandes, sin gradientes detrás de texto.
- SPEC-02: Voz y tono. Cómo escribo. Lo que digo y lo que nunca digo. Vocabulario propio. Ejemplos de frases que suenan a mí y frases que no suenan a mí. La regla de oro: si un texto podría haberlo escrito cualquier persona de LinkedIn, se reescribe.
- SPEC-03: Formato LinkedIn. Las medidas exactas del carrusel (1080×810 px, relación 4:3). Las zonas seguras en píxeles. Los tamaños mínimos de tipografía para móvil. Las mecánicas del algoritmo de LinkedIn que hay que tener en cuenta al estructurar el contenido.
Proyecto de contenido: la SKILL
La SKILL-01 define el pipeline completo para generar un carrusel PDF. Tiene 5 pasos:
- Paso 1: definir el contenido. Tema, número de slides, estructura aplicando las mecánicas del algoritmo de LinkedIn, copy de cada slide.
- Paso 2: generar el HTML de cada slide. Con el CSS base completo incluido en la SKILL para que Claude no lo tenga que inferir.
- Paso 3: renderizar a PNG con Playwright Chromium. Con el viewport correcto (1080×810) y el tiempo de espera mínimo para carga de fuentes (3000ms).
- Paso 4: compilar el PDF con ReportLab. Con el page size correcto (1080, 810).
- Paso 5: validación final. Checklist de 15 puntos que tiene que estar bien antes de entregar.
La SKILL también incluye la sección de errores comunes a evitar. Los que ya ocurrieron y están documentados para que no se repitan.
Proyecto de agentes de voz: las SPEC
Este proyecto tiene un tipo de SPEC completamente diferente. No hay identidad visual. Hay reglas de negocio y especificaciones técnicas.
- Contexto del sistema. Qué es Elio, qué hace, con qué stack técnico funciona (Retell AI + GPT-4.1 + ElevenLabs + Cal.com + N8N), qué integraciones tiene activas, qué métricas son las que importan.
- Buenas prácticas de voz. Voz no es texto. Las reglas específicas que se aplican en prompts para agentes de voz: una pregunta por turno, números deletreados, latencia, manejo de interrupciones. Los errores de producción documentados.
- Casos de prueba. Transcripciones reales de llamadas anotadas. Lo que funcionó y lo que no. El feedback que guía la iteración.
Por qué las SPEC del proyecto de voz son tan diferentes
En el proyecto de contenido, las SPEC definen estética y estilo. Claude las usa para producir piezas visuales y textuales consistentes.
En el proyecto de agentes de voz, las SPEC definen el contexto técnico y las reglas de funcionamiento. Claude las usa para generar prompts que funcionen en producción, no en demos controladas.
El principio es el mismo: información de referencia que Claude consulta. El contenido es radicalmente distinto porque el trabajo es radicalmente distinto.
Cómo escribir una SPEC desde cero
Sin plantillas mágicas. Solo el proceso que funciona.
La forma más rápida de escribir una SPEC es empezar por el problema que tienes ahora mismo.
¿Qué produce Claude que siempre tienes que corregir? ¿Qué le repites en cada sesión? ¿Qué estándar no respeta aunque se lo hayas dicho? Ese es el contenido de la SPEC.
1. Identifica qué repites
¿Qué le dices a Claude en cada sesión que podría estar documentado? Eso es el núcleo de tu SPEC.
2. Documenta con valores concretos
No «usa mis colores de marca». Escribe los hex exactos. No «tono directo». Escribe ejemplos concretos de lo que sí y lo que no.
3. Añade la sección «lo que nunca»
Los negativos explícitos son los que más reducen correcciones. Documenta lo que Claude hace por defecto y que siempre corriges.
4. Prueba con una tarea real
Dale la SPEC a Claude y pídele la misma tarea que siempre corriges. ¿Necesita menos correcciones? La SPEC funciona.
5. Itera sobre la SPEC, no sobre los prompts
Si Claude sigue produciendo algo que no es correcto, el problema está en la SPEC, no en el prompt de la tarea. Actualiza la SPEC con lo que falta.
La longitud no es virtud
Una SPEC de 500 palabras bien escrita vale más que una de 3000 palabras mal estructurada. Lo que importa es que los estándares estén claros, con valores concretos, y que lo que no se hace esté explícito.
Cuando la SPEC crece mucho, es señal de que hay que dividirla en dos.
Cómo escribir una SKILL desde cero
Documenta el proceso que ya funciona, no el que debería funcionar.
El error más habitual al escribir una SKILL es intentar diseñar el proceso perfecto desde cero. Eso no funciona.
Una SKILL se escribe después de que el proceso funciona. Documentas lo que ya ejecutas bien, con los parámetros exactos que usas, incluyendo los errores que ya cometiste y la solución que encontraste.
1. Ejecuta la tarea manualmente primero
Trabaja con Claude en la tarea concreta. Cuando el resultado está bien, anota lo que hiciste exactamente.
2. Identifica los parámetros críticos
¿Qué valores exactos marcan la diferencia entre que funcione y que falle? Esos son los que van en la SKILL con el valor correcto explícito.
3. Documenta los errores que ya ocurrieron
Cada vez que algo falla y encuentras la solución, documéntalo en la sección «errores comunes a evitar». Es la parte más valiosa de la SKILL.
4. Añade el checklist de validación
Antes de dar el trabajo por terminado, ¿qué tiene que estar bien? Eso es el checklist. Si algo falla en producción que debería estar en el checklist, añádelo.
5. Prueba la SKILL con la tarea completa
Claude lee la SKILL y ejecuta la tarea desde cero. Si produce el mismo resultado correcto que cuando lo haces tú, la SKILL está bien escrita.
La SKILL no es suficiente sin la SPEC
Una SKILL dice cómo ejecutar. Una SPEC dice cómo tiene que quedar. Las dos son necesarias para tareas que implican tanto un proceso técnico como un output con estándares visuales o de contenido.
Para generar un carrusel necesito la SKILL del pipeline técnico y las SPEC de identidad visual, voz y formato. Sin las SPEC, la SKILL produce algo técnicamente correcto pero visualmente inconsistente.
Errores que cometí al montar este sistema
Documentados. Sin maquillar.
Los números reales antes y después
Sin retórica. Solo lo que cambió.
Los 30 minutos de contexto repetido en cada sesión no parecen mucho. Multiplicado por todas las sesiones de trabajo que tengo a la semana, es tiempo real. No tiempo imaginario de productividad. Tiempo real que antes invertía en contextualizar y ahora invierto en trabajar.
Lo que no cambia con este sistema: el trabajo sigue siendo duro. Los agentes de voz siguen requiriendo testing real, análisis de transcripciones y correcciones de producción. Los carruseles siguen requiriendo que yo cree el contenido, defina el tema y tenga algo que contar. Claude no reemplaza el criterio. Lo amplifica.
Por dónde empezar si tienes menos de una hora
Sin montar el sistema perfecto desde el primer día.
No intentes montar las tres capas a la vez. Empieza por lo que más tiempo te cuesta ahora mismo.
Si cada vez que le pides contenido a Claude tienes que corregir el tono: escribe una SPEC de voz de 300 palabras. Con lo que sí, lo que nunca, y 5 ejemplos de cada uno.
Si cada vez que le pides piezas visuales tienes que corregir los colores y tipografías: escribe una SPEC de identidad con los valores hex exactos y la escala tipográfica.
Si tienes un proceso técnico que repites siempre y que tiene parámetros que hay que respetar: documenta ese proceso como SKILL. Con el código que funciona, los valores correctos y los errores que ya cometiste.
Con 2 documentos bien escritos, el comportamiento de Claude en ese proyecto cambia de forma visible. Lo he comprobado.
El sistema aprende una vez.
Tú no repites nunca.
Eso es todo.