Skills: empaquetar experiencia reutilizable

Módulo 5 · Extensibilidad · Lección 4 de 8

Los estándares del cliente viven en un documento que nadie lee.

Al terminar esta lección podrás explicar qué es una Skill, describir cómo Claude la descubre y la carga, e identificar tres tipos de oportunidades de Skill en una activación.

Concepto

Una Skill es experiencia que Claude puede descubrir y cargar solo cuando es relevante

Tres semanas después de iniciar la activación, el equipo de ingeniería quiere que Claude Code siga en cada sesión su estándar de documentación de APIs internas. Sin una Skill, Claude olvida lo que ocurrió entre sesiones. Con una, nunca vuelve a necesitar que se lo expliquen.

Una Skill es una carpeta de archivos (instrucciones, scripts, plantillas) que le da a Claude una capacidad específica y reutilizable. La propiedad clave: Claude carga una Skill solo cuando es relevante para la tarea actual. Una Skill que no se necesita en la sesión actual no añade overhead; simplemente no se carga.

Dos categorías cubren la mayoría de los casos de uso en una activación:

Tipo	Qué cubre	Ejemplo
Skills de capacidad (Capability Skills)	Cosas que Claude no puede hacer bien sin instrucciones especializadas: generar archivos de Office en el formato del cliente, diseños PDF complejos, aplicar plantillas de salida propietarias.	Una Skill de generación de PDF no se carga cuando un desarrollador escribe tests; se activa cuando se le pide a Claude producir un documento con formato.
Skills de conocimiento (Knowledge Skills)	Flujos de trabajo y estándares específicos de la organización: convenciones de código, lenguaje de cumplimiento, requisitos de descripción de PRs, formato de post-mortem de incidentes, guías de marca.	Si alguna vez viste a un equipo ignorar un estándar porque nadie tenía tiempo de consultarlo, esto es lo que lo resuelve: el estándar queda exactamente donde Claude puede encontrarlo, y se activa cuando alguien escribe la firma de una función.

El patrón que hace valiosas a las Skills

Una Skill convierte un documento que nadie lee de forma consistente en algo que Claude aplica automáticamente. El estándar de TypeScript del cliente, su plantilla de PR, su checklist de revisión de seguridad: todo eso existe, solo que no está en el contexto de Claude. Una Skill lo pone ahí.

Estructura

Anatomía de una Skill: una carpeta, un SKILL.md y archivos empaquetados opcionales

La Skill mínima viable es un solo archivo. Las Skills de activaciones reales suelen empaquetar algunos archivos más.

Estructura mínima

flowchart TD
    root["my-skill/"] --> skill["SKILL.md (obligatorio)"]

El SKILL.md tiene dos partes: el frontmatter YAML (los metadatos que Claude lee primero) y el cuerpo (las instrucciones que Claude carga si la Skill es relevante).

Plantilla de SKILL.md

---
name: API Documentation Standards
description: Apply client's internal REST API documentation format
when writing or reviewing any endpoint specification
---
## Overview
[Instructions Claude follows when this skill loads]
## Format Requirements
[Specifics: header format, field definitions, required fields]
## Example
[One worked example of a compliant spec]
Read ./endpoint-template.yaml for the full schema

Para material de referencia extenso, empaquétalo en archivos enlazados. Claude solo los lee cuando los necesita, no en cada tarea.

Estructura enriquecida con recursos empaquetados

flowchart TD
    root["api-docs-skill/"] --> skill["SKILL.md"]
    root --> tpl["endpoint-template.yaml (se carga bajo demanda)"]
    root --> ex["example-spec.yaml (se carga bajo demanda)"]
    root --> script["apply_template.py (se ejecuta si hace falta)"]

Mecánica

Carga progresiva: cómo Claude decide qué Skills cargar

Claude no carga todo. Pasa por tres pasos antes de tocar el contenido de una Skill.

Paso	Qué ve Claude	Resultado
Paso 1: escaneo	Solo el nombre y la descripción de la Skill	Decide: ¿es relevante para esta tarea?
Paso 2: carga	El cuerpo completo de SKILL.md	Lee las instrucciones y los ejemplos
Paso 3: obtención	Los archivos enlazados empaquetados (si hacen falta)	Accede a plantillas, especificaciones y scripts

flowchart LR
    s1["Paso 1: escaneo (nombre y descripción)"] -->|"Relevante"| s2["Paso 2: carga (SKILL.md completo)"]
    s1 -->|"No relevante"| no["No se carga"]
    s2 -->|"Si hacen falta"| s3["Paso 3: obtención (archivos enlazados)"]

Esto hace que el campo description sea la línea más importante que escribirás. Si no describe con precisión cuándo usar la Skill, Claude no la cargará cuando debería, o la cargará cuando no debería.

La implicación práctica para el trabajo de activación: una biblioteca de 10 a 20 Skills especialistas no degrada el rendimiento en cada tarea. El overhead es proporcional a la relevancia, no al número de Skills instaladas.

La carga contextual es el comportamiento predeterminado, pero no es la única vía. Los usuarios también pueden invocar una Skill directamente por nombre (por ejemplo, /skill-name) o referenciarla explícitamente en sus instrucciones para forzarla en el contexto, sin importar la evaluación de relevancia de Claude.

Aplicación en la activación

Tres oportunidades de Skill en una activación de 30 días

El checklist de descubrimiento previo al kickoff pide inventariar qué Skills, MCPs y plugins tiene ya el cliente. Lo que no aparezca en ese inventario, lo construyes. Estos tres patrones cubren la mayor parte de lo que vas a construir.

• Patrón 1: refinado con la experiencia. Tareas repetidas con estándares de calidad establecidos: formato de revisión de código, post-mortem de incidentes, requisitos de descripción de PRs. El equipo del cliente ya sabe qué es un buen resultado. Empaquétalo.
• Patrón 2: la calidad depende de los materiales. Tareas en las que Claude necesita material de referencia para hacer bien el trabajo: formato de especificación de API, lenguaje de cumplimiento normativo, catálogo interno de servicios, convenciones de modelos de datos. Empaqueta la referencia; Claude la lee cuando la necesita.
• Patrón 3: brecha de capacidad. Algo que Claude no puede hacer bien sin instrucciones especializadas: generar documentos en un formato específico del cliente, aplicar un esquema propietario, ejecutar un paso de validación personalizado. Una Skill de capacidad con scripts y plantillas empaquetados cierra la brecha.

Cuándo construir frente a cuándo instalar. El Plan de activación ubica el inventario de Skills en el pre-kickoff y el trabajo de profundidad en la Semana 2. Para la Semana 4, las Skills que construiste se empaquetan en el plugin del equipo. No construyas Skills desde cero si el cliente o el marketplace de Anthropic ya tiene una. Revisa primero.

Ejemplo resuelto: un cliente, tres oportunidades identificadas en la Semana 2

Una firma de servicios financieros del Reino Unido, con un equipo de ingeniería de 50 personas. Semana 2 de una activación de 30 días. Tres observaciones, tres patrones, tres construcciones.

Situación 1 · Patrón 1. Cada mañana, dos ingenieros senior escriben informes de post-incidente en el formato que exige el comité de riesgos de la firma. Los ingenieros junior lo copian de forma imperfecta. Claude ha estado escribiendo los informes, pero produce clasificaciones de severidad inconsistentes. Patrón 1. Construye una Skill que codifique la rúbrica de severidad y los campos obligatorios. La inconsistencia se corta en el origen.

Situación 2 · Patrón 2. El equipo de cumplimiento de la firma tiene un checklist de seguridad de API de 90 páginas. Los desarrolladores validan cada endpoint nuevo contra él; quien revisa pega manualmente las secciones relevantes cada vez. Patrón 2. Empaqueta el checklist como archivo de referencia dentro de la Skill. Se carga cuando se le pide a Claude revisar un endpoint. Se acabó el pegado manual.

Situación 3 · Patrón 3. La firma usa XML ISO 20022 para los mensajes de pago. Cuando los desarrolladores piden a Claude escribir un manejador de pagos, inventa nombres de campos que fallan contra el esquema. Patrón 3. Construye una Skill que le dé a Claude el esquema, los campos obligatorios y un ejemplo resuelto. Claude no puede adivinar este formato: necesita la Skill para hacer el trabajo correctamente.

Comprueba tu comprensión

Verdadero o falso

1. Claude carga el SKILL.md completo de cada Skill instalada en cada tarea.

Verdadero / Falso

Ver respuesta

Falso. La carga progresiva significa que Claude lee solo la descripción al principio. Carga el SKILL.md completo únicamente cuando la Skill es relevante para la tarea actual. Una biblioteca de 20 Skills no añade overhead a cada sesión.

2. Una Skill puede incluir scripts ejecutables que Claude corre como parte del flujo de trabajo.

Verdadero / Falso

Ver respuesta

Verdadero. Las Skills pueden empaquetar scripts de Python, scripts de shell o cualquier otro ejecutable. El SKILL.md indica a Claude cuándo y cómo usarlos. Este es el mecanismo de las Skills de capacidad: generar documentos complejos, aplicar transformaciones propietarias y ejecutar validadores personalizados.

3. El campo description del frontmatter YAML es decorativo: Claude no lo usa para decidir si carga la Skill.

Verdadero / Falso

Ver respuesta

Falso. La descripción es el disparador. Claude lee las descripciones para decidir qué Skills son relevantes antes de cargar cualquier otra cosa. Una descripción vaga hace que Claude no cargue la Skill cuando debería. Escribir la descripción es la decisión de autoría más importante de cualquier Skill.

Las tres respuestas son correctas. El modelo de carga progresiva da forma a cada Skill que construyas y a cada biblioteca de Skills que diseñes para un cliente. La calidad de la descripción no es un paso de pulido: es el mecanismo que determina si una Skill llega a usarse.

Escenario: el catálogo que vive en el portapapeles

Durante el descubrimiento en un cliente de servicios financieros, observas que tres desarrolladores pegan el mismo catálogo interno de servicios de 60 páginas en sus sesiones de Claude. Cada uno mantiene su propia copia recortada, y las versiones empiezan a divergir.

¿Qué patrón de Skill representa esto?

• A · Patrón 1: el equipo escribe la documentación de servicios de forma inconsistente y necesita un formato estándar.
• B · Patrón 2: el material de referencia existe, pero no llega a Claude de forma fiable.
• C · Patrón 3: Claude no conoce la arquitectura de servicios del cliente y hay que construirla desde cero.

Ver respuesta

B es correcta. El catálogo existe y se usa; el problema es la fiabilidad. Los desarrolladores mantienen copias personales que se alejan unas de otras, y el paso de pegar se omite bajo presión de plazos. Una Skill que empaquete el catálogo canónico hace que se cargue bajo demanda, desde una única fuente.

A: El síntoma no es una escritura inconsistente, sino un acceso inconsistente a los materiales. El Patrón 1 se aplica cuando un estándar de calidad establecido no se aplica de forma uniforme. Aquí los materiales existen; simplemente no llegan a Claude de forma fiable.

C: Claude no necesita que le enseñen la arquitectura de servicios desde cero, porque el catálogo ya existe. El Patrón 3 se aplica cuando a Claude le falta un conocimiento que ningún documento existente recoge.

Escenario: el post-mortem que califica la severidad de forma distinta cada vez

Un ingeniero senior te llama aparte durante el piloto: «Claude escribe buenos post-mortems, pero las evaluaciones de severidad varían mucho. Dos ingenieros pasaron el mismo incidente por Claude la semana pasada y obtuvieron P2 y P4.» El equipo tiene una rúbrica de severidad en su runbook interno.

¿Qué patrón de Skill representa esto?

• A · Patrón 1: tarea repetida con un estándar de calidad establecido, pero salida inconsistente entre el equipo.
• B · Patrón 2: la rúbrica está en el runbook; empaquétala como archivo de referencia para que Claude pueda acceder a ella.
• C · Patrón 3: la evaluación de severidad requiere conocimiento de dominio sobre la infraestructura de este cliente que Claude no tiene.

Ver respuesta

A es correcta. Están presentes las tres señales del Patrón 1: el equipo ejecuta la tarea de forma repetida, existe un estándar establecido (la rúbrica de severidad) y la salida varía entre ingenieros. Una Skill que codifique la rúbrica hace que Claude aplique los mismos criterios siempre, sin importar quién la ejecute.

B: Empaquetar el runbook como archivo de referencia seguiría dejando a Claude interpretar la severidad a partir de prosa, y la variación continuaría. El Patrón 2 resuelve un problema de carga; el Patrón 1 resuelve un problema de consistencia. Aquí la solución es codificar la rúbrica como instrucciones, no solo hacerla accesible.

C: Claude sabe escribir post-mortems; el problema no es la falta de conocimiento de dominio. La variación indica que existe un estándar que no se aplica de forma consistente. Si Claude no pudiera escribir post-mortems en absoluto, eso sería el Patrón 3.

Escenario: el esquema que Claude nunca ha visto

Un cliente de servicios financieros quiere usar Claude para generar mensajes de pago XML ISO 20022. Los desarrolladores lo prueban durante el piloto. Claude produce XML bien estructurado, pero los nombres de los campos son incorrectos, faltan elementos anidados obligatorios y todas las pruebas fallan la validación del esquema.

¿Qué patrón de Skill representa esto?

• A · Patrón 1: el equipo genera mensajes de pago de forma inconsistente; un estándar compartido lo resolvería.
• B · Patrón 2: la especificación ISO 20022 existe; empaquétala como archivo de referencia para que Claude pueda consultarla.
• C · Patrón 3: Claude no conoce este formato y necesita que le expliquen el esquema, los campos obligatorios y un ejemplo resuelto.

Ver respuesta

C es correcta. Claude genera XML con apariencia plausible, pero falla contra el esquema, lo que significa que trabaja con conocimiento general de XML y no con la especificación real. ISO 20022 tiene cientos de tipos de mensaje con nombres de campos, reglas de cardinalidad y requisitos de namespace específicos que Claude no aprendió. Una Skill le da el esquema, los campos obligatorios y un ejemplo completo.

A: El problema no es la inconsistencia: el resultado es sistemáticamente incorrecto. El Patrón 1 se aplica cuando Claude puede hacer la tarea pero la calidad varía. Aquí todas las pruebas fallan, y eso es una brecha de capacidad, no un problema de consistencia.

B: Un archivo de referencia con la especificación ayudaría, pero el Patrón 2 por sí solo no basta. Claude no puede recorrer una especificación XML de 200 páginas para encontrar bajo demanda los campos correctos. Un Patrón 3 va más allá: da a Claude el esquema específico, requisitos de campo anotados y un ejemplo completo, el equivalente a poner al día a un ingeniero que nunca ha visto este formato.

Las oportunidades de Skill que identificaste aquí definen el contenido del directorio skills/ del plugin: una por patrón, con alcance del equipo del cliente. Cada una se escribe en la lección 5.5 (capítulo 23).

Ideas clave

Ya sabes qué es una Skill. Ahora aprende a escribir una que funcione. Una Skill solo es tan buena como su descripción. El modelo de carga progresiva evita que Claude cargue en cada sesión contenido que no necesita, pero solo si la descripción es lo bastante precisa para activarse en las tareas correctas.

• Una Skill es una carpeta con instrucciones, scripts y plantillas que Claude carga solo cuando es relevante para la tarea.
• Hay dos categorías: Skills de capacidad (lo que Claude no hace bien sin instrucciones especializadas) y Skills de conocimiento (flujos de trabajo y estándares de la organización).
• Claude escanea primero el nombre y la descripción; el campo description determina si la Skill se carga.
• Los tres patrones de oportunidad son: refinado con la experiencia (Patrón 1), la calidad depende de los materiales (Patrón 2) y brecha de capacidad (Patrón 3).

La mecánica es simple. El oficio está en la descripción y en la estructura de las instrucciones. La lección 5.5 (capítulo 23) recorre las decisiones de autoría que marcan la diferencia entre una Skill que Claude usa y una que ignora.

Siguiente: Escribir Skills efectivas