Arquitectura de skills (un skill es una instrucción reutilizable para Claude): 2 arquetipos

Módulo: Skills, experiencia reutilizable | Tiempo: ~25 min de teoría + 30 min de práctica

Lo esencial

Hay dos tipos de skills valiosos: los que le enseñan al modelo algo nuevo (por ejemplo, reglas de diseño con las que no fue entrenado) y los que codifican tu forma personal de trabajar (que el modelo, por definición, no puede conocer). Los primeros pueden volverse obsoletos, porque los modelos se actualizan. Los segundos, nunca: son tu experiencia única y no existe en ningún otro lugar.

Conceptos clave

• Capability Uplift Skills: amplían las capacidades del modelo, con riesgo de volverse obsoletos
• Encoded Preference Skills: codifican un proceso personal o de negocio, con valor a largo plazo
• Dónde guardar los skills: de forma global o a nivel de proyecto
• Tamaño de un skill: menos de 500 líneas; los datos grandes van en archivos de referencia
• Subagentes (un subagente es un agente hijo) dentro de los skills para el trabajo pesado

Teoría

Tipo 1: Capability Uplift Skills

🎨 Imagínalo así: un Capability Uplift es como un acordeón para un empleado nuevo. Claude es inteligente, pero no conoce tu nicho. El skill le dice: "en Ecuador los bienes raíces funcionan así, estas son las 7 reglas". Empleado inteligente + acordeón = trabaja bien desde el primer día.

Qué es: skills que le dan al modelo conocimientos o habilidades que no trae por defecto.

Ejemplos:

• "Lineamientos de diseño front-end para landing pages que convierten"
• "Buenas prácticas de visualización de datos según el libro de Tufte"
• "Reglas para redactar documentos legales en Ecuador"
• "Estándares de seguridad para productos fintech (PCI DSS)"

Por qué funcionan: Claude conoce los principios generales del diseño, pero no los detalles de tu nicho ni de una metodología concreta. El skill cubre ese hueco.

Riesgo de volverse obsoleto:

Claude se actualiza. Cada nueva generación de modelos se entrena con más datos y sabe más: a octubre de 2026 los vigentes son Opus 5.5 y Sonnet 5.5; la lista al día está en la página Lo vigente. Un skill de "lineamientos de diseño front-end" escrito hoy puede sobrar en un año, porque el modelo lo aprenderá por su cuenta.

Cómo comprobar si sigue siendo útil:

Cada 3-6 meses haz una prueba: pídele al modelo la tarea SIN el skill.
Si el resultado es igual de bueno, el skill ya caducó y puedes borrarlo.

Cuándo crear un Capability Uplift:

• Reglas específicas de tu nicho (bienes raíces, medicina, derecho)
• Estándares locales (leyes de un país concreto, el mercado local)
• Metodologías propias (tu sistema interno de evaluación)
• Información que cambia (competidores, precios)

Tipo 2: Encoded Preference Skills

Qué es: skills que codifican tu estilo personal, tus preferencias y tus procesos de negocio.

Ejemplos:

• "Mi forma de crear infografías: primero los datos en una tabla, luego 3 opciones de visualización, luego elijo"
• "Nuestro proceso de onboarding de un cliente nuevo: pasos 1-7 con preguntas concretas"
• "Cómo escribo correos a prospectos en frío: estructura, tono, extensión, llamado a la acción"
• "La voz de marca de una agencia inmobiliaria: experto observador y mesurado, sin exageraciones"

Por qué no caducan:

El modelo nunca sabrá exactamente cómo quieres trabajar tú: son tus preferencias. Ni el modelo más inteligente adivinará:

• Qué formato de reporte te gusta
• Qué preguntas les haces a los clientes en la primera reunión
• Qué tono tiene tu marca
• Cómo priorizas el backlog de tu producto

Esta es tu experiencia única codificada. Un competidor no puede copiarla. El modelo no puede inventarla. Solo tú la conoces.

Los más valiosos a largo plazo: precisamente los Encoded Preference Skills construyen un foso (moat) alrededor de tu negocio. Cuantos más skills de este tipo tengas, más difícil será para la competencia reproducir tus procesos.

🎨 Imagínalo así: los Encoded Preference Skills son la receta de la salsa de la casa que la competencia nunca va a reproducir con exactitud. Aunque vean los ingredientes, no saben las proporciones, la temperatura ni el orden. Es tu ADN en un archivo.

Dónde guardar los skills: global o por proyecto

Carpeta global (~/.claude/skills/):

Disponible desde CUALQUIER proyecto
├── code-review-standards/SKILL.md   ← igual para todos los proyectos
├── email-writing-style/SKILL.md     ← mi estilo es el mismo en todas partes
└── data-analysis-approach/SKILL.md  ← mi forma de analizar datos

Cada skill es una carpeta, y el archivo principal dentro se llama SKILL.md.

Úsala para: skills universales, preferencias personales y estándares que aplican en todas partes.

Carpeta del proyecto (.claude/skills/):

Disponible SOLO en este proyecto
├── acme-realty-brand-voice/SKILL.md   ← específico de esta marca
├── ecuador-real-estate-rules/SKILL.md ← específico de este mercado
└── client-report-format/SKILL.md      ← formato para este cliente

Úsala para: skills de una marca concreta, procesos de un cliente, particularidades de un mercado.

Regla práctica: pregúntate "¿este skill se necesita solo en este proyecto o en todos?" → proyecto o global.

Tamaño del skill: la regla de las 500 líneas

El problema de los skills grandes:

Cuanto más grande es el skill, más tokens (un token es una unidad de texto para la IA) se gastan en cargarlo. Un skill de 2000 líneas significa que cada solicitud que lo usa = 2000 líneas de contexto (el contexto es el texto que la IA tiene a la vista). Eso es caro y lento.

🎨 Imagínalo así: un skill grande es como una mochila en la que metiste todo lo que podría servir en una excursión. Pesa 30 kg. La cargas siempre, incluso cuando solo vas por pan. La regla de las 500 líneas es la mochila de un día: solo lo necesario para hoy.

Regla: mantén el skill por debajo de 500 líneas (unos 5-10 KB). Es una recomendación de la documentación de Claude Code.

Qué sacar a archivos de referencia:

# No metas en SKILL.md:
# - La lista completa de 500 competidores
# - Todos los datos de precios (cambian)
# - Plantillas grandes (HTML/CSS)
# - Bibliotecas de ejemplos de contenido

# En su lugar, archivos aparte en la carpeta del skill, a los que SKILL.md hace referencia:
my-skill/
  SKILL.md
  data/competitors-database.json   # JSON grande
  templates/report-layout.html     # plantilla HTML
  brand/content-examples/          # carpeta con ejemplos

En el texto de SKILL.md escribes cuándo abrir cada archivo. El skill lee el archivo solo cuando hace falta: si la tarea no requiere análisis de competencia, competitors-database.json no se carga.

Contexto inline vs. archivos de referencia

Inline (directamente en el cuerpo del skill):

• Reglas críticas que siempre se aplican
• La estructura del proceso
• Parámetros y ajustes

Archivos de referencia:

• Datos voluminosos (listas, tablas)
• Plantillas (HTML, Excel)
• Datos que cambian (precios, competidores, tendencias)
• Ejemplos de contenido (más de 30 ejemplos)

Ejemplo:

# En el cuerpo del skill (inline):
## Pasos del análisis
1. Extraer las métricas clave
2. Comparar con los benchmarks (ver references/benchmarks.json)
3. Identificar anomalías (desviación >20% respecto al promedio)
4. Redactar un resumen ejecutivo (máximo 150 palabras)

# En references/benchmarks.json (no en el cuerpo; cifras ilustrativas):
{
  "email_open_rate": {"good": 25, "average": 20, "poor": 15},
  "conversion_rate": {"good": 3.5, "average": 2.0, "poor": 1.0},
  ...200 líneas de datos...
}

Subagentes dentro de los skills

Algunas tareas dentro de un skill son demasiado pesadas para un solo agente (un agente es un ejecutor autónomo de tareas):

## Paso 3: Análisis de competencia
Delega al subagente `competitor-researcher` con estos parámetros:
- Lista de competidores de references/competitors.json
- Tarea: reunir datos de los últimos 30 días
- Devolver: JSON con las métricas de cada competidor

El agente principal espera el resultado → continúa con el paso 4.

Nota (a octubre de 2026): en Claude Code los subagentes trabajan en segundo plano por defecto. Si el paso 4 depende del resultado, escribe explícitamente en la instrucción que hay que esperarlo. Y un skill completo puede ejecutarse en un contexto aparte con el campo context: fork en el frontmatter.

🎨 Imagínalo así: un subagente dentro de un skill es como el maestro de obras que contrata trabajadores para una etapa concreta. El maestro de obras (agente principal) dirige la construcción. En la etapa de cimientos contrata a los que cavan (subagente). Ellos cavan y el maestro de obras no gasta energía. Los trabajadores se van y el maestro de obras sigue.

Para qué: el análisis de competencia es una tarea larga (muchas solicitudes, muchos datos). Al delegarla a un subagente:

• Mantienes limpio el contexto del agente principal
• Puedes lanzar varios subagentes en paralelo
• El subagente puede usar un modelo más barato (Haiku para recolectar datos)

Cómo auditar tu biblioteca de skills cada trimestre

Cada 3-6 meses:

1. Revisa los Capability Uplift: prueba el modelo sin el skill. Si sale bien, bórralo.
2. Actualiza los datos en los archivos de referencia: ¿cambiaron los precios de la competencia? Actualízalos.
3. Evalúa el uso: ¿qué skills no se han usado en más de 60 días? ¿Vale la pena conservarlos?
4. Encuentra duplicados: ¿dos skills hacen algo parecido? Únelos.

🎨 Imagínalo así: auditar tus skills es como ordenar la cochera cada trimestre. Esta herramienta no la toqué en un año: ¿por qué ocupa lugar? Esta duplica a aquella: las junto. Esta ya es vieja y la nueva es mejor: la tiro. La cochera debe ser un taller, no un museo.

La biblioteca de skills debe mantenerse ligera: no una colección por coleccionar, sino una herramienta de trabajo.

Práctica

Tarea: clasifica 5 skills potenciales en los dos tipos

1. Toma 5 tareas que haces con regularidad:
   • Por ejemplo: escribo correos a clientes, analizo datos, creo publicaciones para redes sociales, preparo presentaciones, hago code review
2. Para cada tarea define: ¿es Capability Uplift o Encoded Preference?
   • Pregúntate: "¿Puede el modelo hacer esto sin mi experiencia personal?"
   • Si SÍ → Capability Uplift
   • Si NO (hace falta mi estilo o mi proceso personal) → Encoded Preference
3. Para cada skill define: ¿global o de proyecto?
4. Estima el tamaño: ¿qué irá inline y qué en archivos de referencia?
5. Extra: crea ahora mismo un Encoded Preference Skill: elige la tarea más personal de las cinco

Herramientas y recursos

• ~/.claude/skills/<nombre>/SKILL.md: skills globales (crea la carpeta si todavía no existe)
• .claude/skills/<nombre>/SKILL.md: skills del proyecto
• Documentación de Skills en Claude Code: la guía oficial de skills
• /skill-doctor: revisa el estado de los skills en Claude Code (el comando apareció en 2026; lista de comandos: documentación)
• /skills: comando para ver los skills instalados

Ideas clave

Encoded Preference Skills = tu foso competitivo. Codifica tus procesos: la competencia no los copiará y el modelo no los adivinará.

Los Capability Uplift Skills envejecen a medida que se actualizan los modelos. Revísalos cada 3-6 meses: no cargues peso muerto.

Un skill de más de 500 líneas es señal de problema. Los datos grandes van a archivos de referencia; la lógica, al cuerpo.

Lecciones relacionadas

• ← Qué son los Skills: conceptos básicos, el marco de creación en 6 pasos
• ← Creamos un skill desde cero EN VIVO: práctica de creación con Skill Creator
• → Evals: skills que se mejoran solos: probar skills, el ciclo de automejora
• → Subagentes: trabajadores especializados que los skills pueden llamar

Siguiente lección

→ Evals: skills que se mejoran solos: cómo comprobar y mejorar los skills con datos