Escribir skills efectivas

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

Al terminar esta lección podrás crear una skill que Claude invoca correctamente, que no sobrecarga el contexto y que el equipo del cliente puede mantener cuando termina el proyecto.

Un desarrollador creó una skill. Claude nunca la carga.

La descripción es el disparador. Todo lo demás es secundario

El escenario es común: un desarrollador construye una skill bien estructurada, la sube al repositorio y Claude nunca la carga. Las instrucciones están bien. La descripción no.

Claude lee el campo description del frontmatter de SKILL.md para decidir si una skill es relevante para la tarea actual, antes de cargar cualquier instrucción. Una descripción vaga hace que Claude no sepa cuándo cargar la skill. Una descripción demasiado amplia hace que Claude la cargue en todas las tareas y genere sobrecarga de contexto.

flowchart LR
    A["Tarea del usuario"] --> B["Claude lee el campo description del frontmatter de SKILL.md"]
    B --> C{"¿La skill es relevante?"}
    C -->|"No"| D["No carga la skill"]
    C -->|"Sí"| E["Carga las instrucciones de SKILL.md"]
    E --> F["Carga las referencias enlazadas cuando hacen falta"]

Vaga: no se activa de forma fiable

description: Apply PR format

Claude no sabe cuándo aplica «PR format». Esta skill no se cargará en tareas de creación de PR porque no hay una condición de activación explícita.

Precisa: se activa correctamente

description: Apply the client's internal PR description format when creating or reviewing pull request descriptions. Includes required fields: summary, testing plan, reviewer checklist, and linked ticket.

La condición de activación es explícita. Claude sabe cuándo cargar esta skill y qué encontrará al hacerlo.

Tres reglas para una descripción que funciona

1. Nombra la condición de activación. «Cuando se creen o revisen descripciones de pull request»: sé explícito, no implícito.
2. Nombra el resultado o el contexto. «Formato de descripción de PR»: ¿qué produce o aplica la skill? Claude necesita cotejarlo con la tarea.
3. Menciona los materiales clave. «Incluye los campos obligatorios: summary, testing plan, reviewer checklist». La distinción ayuda a Claude a elegir entre skills parecidas.

Prácticas que separan las skills duraderas de las que se abandonan

De Skills Workshop. No son pautas: son la diferencia entre una skill que el equipo mantiene y una que deja de usar en silencio.

Mantenla enfocada

Una skill por flujo de trabajo. No agrupes estándares de código, formato de PR y revisión de seguridad en un mismo archivo. Las skills enfocadas se cargan con precisión; las agrupadas se cargan aunque solo haga falta una de sus partes.

Empieza simple

Primero la guía básica. Amplíala según el uso real. Las lagunas que aparecen en la práctica son mejores guías que las que anticipas.

Usa ejemplos

Un ejemplo resuelto vale más que tres párrafos de reglas. Muéstrale a Claude cómo es una buena salida. No te limites a describirla.

Prueba de forma incremental

Prueba después de cada cambio. No construyas una skill compleja de varios archivos sin verificar antes la versión simple. Una skill que falla en silencio es peor que no tener skill.

Versiona tus skills

Los estándares del cliente cambian. Cuando cambia la plantilla de PR del cliente, la skill también debe cambiar. Trata las skills como código: deben estar en control de versiones con el mismo rigor que el código de producción.

Ejemplo trabajado: construir una skill de documentación de API en TypeScript desde cero

Un recorrido concreto del proceso de autoría en cinco pasos para una Knowledge Skill. Usarás este patrón en la mayoría de los proyectos de GSI.

Paso 1: identificar el disparador

¿Cuándo se activa esta skill? Sé específico: «Cuando se escriban o revisen firmas de funciones TypeScript, endpoints de API o documentación de interfaces de servicio».

Paso 2: escribir la descripción

description: Apply the client's TypeScript documentation standard when
writing or reviewing function signatures, API endpoints,
or service interfaces. Includes JSDoc format, required
fields, and example patterns.

Paso 3: escribir el núcleo de SKILL.md

Indica el formato. Muestra un ejemplo completo. Lista los campos obligatorios. Enlaza el archivo de referencia en lugar de incrustarlo.

Estructura de SKILL.md

---
name: TypeScript API Documentation Standard
description: Apply the client's TypeScript documentation standard...
---
## Format
All functions and endpoints must use JSDoc with the following
required fields: @param, @returns, @throws, @example.
## Example
[One complete compliant function signature with JSDoc block]
## Required fields
[List of fields and their formats]
Read ./spec-template.yaml for the full endpoint schema.

Paso 4: incluir el archivo de referencia

flowchart TD
    A["api-docs-skill/"] --> B["SKILL.md"]
    A --> C["spec-template.yaml ← esquema completo, cargado bajo demanda"]

Paso 5: probar

Pide «Documenta este endpoint» y verifica: ¿Claude cargó la skill? ¿El resultado coincide con el estándar? Corrige la descripción si Claude no cargó la skill. Corrige una instrucción si la cargó pero produjo un resultado incorrecto.

flowchart LR
    P1["1. Identificar el disparador"] --> P2["2. Escribir la description"]
    P2 --> P3["3. Escribir el núcleo de SKILL.md"]
    P3 --> P4["4. Incluir el archivo de referencia"]
    P4 --> P5["5. Probar: documentar un endpoint"]
    P5 --> Q{"¿Claude cargó la skill?"}
    Q -->|"No"| D["Corregir la description"]
    D --> P5
    Q -->|"Sí, pero el resultado es incorrecto"| I["Corregir una instrucción"]
    I --> P5

Atajo: el creador de skills

Pídele a Claude: “Build a Skill for [task]. Here are 5 examples.” Claude genera la estructura de carpetas, SKILL.md y los archivos de ejemplo. Empieza por aquí para las Knowledge Skills. Es más rápido que escribir desde cero, y la descripción reflejará cómo Claude interpreta realmente la tarea.

Comprueba tu comprensión

¿Qué descripción activa realmente la skill?

Un desarrollador le pide a Claude «documenta este endpoint». La skill debería cargarse, pero solo si la descripción le indica a Claude cuándo usarla.

Decisión · Diseño de la descripción

¿Qué descripción es más probable que active la skill correcta cuando un desarrollador dice «documenta este endpoint»?

A

description: Documents API endpoints and function signatures using JSDoc format with required fields and example patterns. Use when a developer asks Claude to document code.

B

description: Help with API documentation

C

description: Apply the client's TypeScript documentation standard when writing or reviewing function signatures, API endpoints, or service interfaces. Includes JSDoc format, required fields, and example patterns.

Ver respuesta

C es correcta. Tres elementos hacen que esta descripción sea eficaz: la condición de activación («cuando se escriban o revisen firmas de funciones, endpoints de API o interfaces de servicio»), el formato de salida («formato JSDoc, campos obligatorios») y un marcador distintivo («el estándar de documentación TypeScript del cliente»). Claude usa los tres para determinar la relevancia antes de cargar el SKILL.md completo.

A tiene la estructura correcta (condición de activación, formato, ejemplos), pero no tiene un marcador distintivo. Si el cliente tiene dos skills de documentación (una para TypeScript y otra para OpenAPI), Claude no puede distinguirlas. La descripción debe nombrar lo que diferencia a esta skill de otras que cubren terreno parecido.

B es demasiado vaga para activarse de forma fiable. Podría coincidir con casi cualquier petición de documentación y no le da a Claude una base para elegir esta skill en lugar de una general.

Una skill que funciona en general, pero falla siempre en una cosa

El equipo lleva dos semanas usando la skill. Los comentarios son específicos y accionables.

Decisión · Autoría de skills

Has creado una skill para el formato de post-mortem de incidentes del cliente. El equipo la ha usado durante dos semanas. Comentario: «Claude sigue añadiendo una sección de lecciones aprendidas incluso en incidentes menores. Solo usamos eso para P1 y P2.» ¿Qué corrección es la adecuada?

• A · Añadir una regla específica en SKILL.md: «Incluye la sección de lecciones aprendidas solo en incidentes de severidad P1 y P2.»
• B · Eliminar la skill y volver al prompting manual: el equipo tiene un proceso que funciona sin ella; la skill causa más problemas que los que resuelve.
• C · Añadir más ejemplos de post-mortems de incidentes menores: más ejemplos deberían ayudar a Claude a entender cómo son los incidentes menores y dejar de añadir la sección.

Ver respuesta

A es correcta. Las skills se comportan como el personal: siguen las instrucciones que se les han dado. La solución para un comportamiento incorrecto y consistente es una regla específica y explícita: «Incluye la sección de lecciones aprendidas solo en incidentes P1 y P2». Una frase cierra la brecha.

B: eliminar la skill descarta dos semanas de adopción por un problema que una sola frase resuelve. La skill funciona; falta una instrucción.

C: añadir ejemplos de incidentes menores le da a Claude más ejemplos de algo que ya hace mal. Claude aplica primero las restricciones escritas explícitas: no deduce reglas de comportamiento solo a partir de patrones de ejemplos. Nombra la restricción directamente.

Artefacto del curso · Contribución de la lección 5

Plugin de activación

Skill de ejemplo

1. Escribe un SKILL.md para un patrón que tu equipo del cliente use de forma consistente: revisión de código, generación de tests o documentación. Sigue la estructura description-first de esta lección.
2. Pruébalo localmente: abre una sesión de Claude en el repositorio y verifica que la skill se carga. La descripción debe activarla en las tareas correctas sin activarse en tareas no relacionadas.
3. Este archivo se convierte en el componente skills/ del plugin de activación que empaquetarás en la lección 5.8.

La skill que creaste aquí: SKILL.md y cualquier archivo de referencia incluido. Es el componente skills/ del plugin de activación que empaquetarás en la lección 5.8.

Ideas clave

• Una skill bien escrita tiene una descripción precisa que se activa exactamente en las tareas correctas, instrucciones enfocadas con un ejemplo trabajado y archivos de referencia enlazados para el detalle que Claude solo necesita de vez en cuando.
• Claude lee la description antes de cargar la skill. Si la descripción es vaga, no se activa; si es demasiado amplia, se carga en tareas que no le corresponden.
• Una descripción eficaz nombra la condición de activación, el formato o resultado, y un marcador distintivo frente a skills parecidas.
• Mantén cada skill enfocada en un solo flujo de trabajo, empieza simple, usa un ejemplo trabajado y prueba cada cambio.
• Ante un comportamiento incorrecto y consistente, añade una regla explícita en SKILL.md en lugar de más ejemplos.
• Versiona las skills como código: el equipo del cliente debe poder mantenerlas después del proyecto.

Siguiente: Hooks: pre-tarea, post-edición, ante fallos, al completar