Guia de Skills para Claude - Parte 2

Claude // Agent Skills

Requisitos Técnicos y Pruebas

Parte 2: Estructura de archivos, YAML Frontmatter y metodología de testing

El éxito de una skill depende de cumplir con los requisitos técnicos exactos y de realizar pruebas exhaustivas. En esta sección cubrimos la estructura de archivos, el formato YAML crítico, cómo escribir instrucciones efectivas y metodología de testing.

El YAML frontmatter es la parte más importante de tu skill — es cómo Claude decide si cargarla o no.

MÓDULO_01

Estructura de Archivos

La estructura de tu skill debe seguir reglas estrictas. Una estructura incorrecta impedirá que la skill se cargue.

Reglas Críticas de Nomenclatura

SKILL.md - reglas de nombre

SKILL.md     # ✅ Correcto - exactamente así
SKILL.MD     # ❌ Incorrecto - mayúsculas en extensión
skill.md     # ❌ Incorrecto - minúsculas en nombre
Skill.md     # ❌ Incorrecto - capitalización mixta

carpeta de skill - nomenclatura

notion-project-setup   # ✅ Correcto - kebab-case
Notion Project Setup   # ❌ Incorrecto - espacios
notion_project_setup   # ❌ Incorrecto - guiones bajos
NotionProjectSetup     # ❌ Incorrecto - PascalCase

Importante: No incluyas README.md dentro de tu carpeta de skill. Toda la documentación va en SKILL.md o references/.

MÓDULO_02

YAML Frontmatter

El frontmatter YAML es cómo Claude decide si cargar tu skill. Es la parte más crítica — errores aquí harán que tu skill no funcione.

Formato Mínimo Requerido

frontmatter mínimo

---
name: tu-nombre-de-skill
description: Qué hace. Usar cuando el usuario pide [frases específicas].
---

Requisitos de Campos

Campo	Requerido	Reglas
name	Sí	kebab-case, sin espacios, sin mayúsculas
description	Sí	QUÉ hace + CUÁNDO usarla, máx 1024 caracteres
license	No	MIT, Apache-2.0, etc.
compatibility	No	Requisitos del entorno (1-500 chars)
metadata	No	author, version, mcp-server, etc.

Ejemplos de Descripciones

Buena descripción:
"Analiza archivos de diseño de Figma y genera documentación de entrega para desarrolladores. Usar cuando el usuario sube archivos .fig, pide 'especificaciones de diseño', 'documentación de componentes', o 'entrega de diseño a código'."

Mala descripción:
"Ayuda con proyectos." — Demasiado vago, sin activadores específicos.

Restricciones de Seguridad

• Prohibido: Corchetes angulares XML (< >)
• Prohibido: Skills con "claude" o "anthropic" en el nombre
• El frontmatter aparece en el system prompt — contenido malicioso podría inyectar instrucciones

MÓDULO_03

Escribiendo Instrucciones Efectivas

Después del frontmatter, el cuerpo de SKILL.md contiene las instrucciones que Claude seguirá. La claridad y especificidad son clave.

Plantilla Recomendada

SKILL.md - estructura

---
name: mi-skill
description: Descripción con activadores...
---

# Nombre de la Skill

# Instrucciones

## Paso 1: [Primer Paso]
Explicación clara de qué sucede.

```bash
python scripts/fetch_data.py --project-id PROJECT_ID
```

Salida esperada: [describe el éxito]

# Ejemplos

## Ejemplo 1: [escenario común]
Usuario dice: "Configurar nueva campaña"
Acciones:
1. Obtener campañas existentes vía MCP
2. Crear nueva campaña
Resultado: Campaña creada

# Solución de Problemas

## Error: [Mensaje común]
Causa: [Por qué sucede]
Solución: [Cómo arreglarlo]

Mejores Prácticas

SÉ ESPECÍFICO

"Ejecuta python scripts/validate.py --input {file}" en lugar de "Valida los datos"

INCLUYE ERRORES

Documenta errores comunes y sus soluciones

USA REFERENCIAS

Mueve docs extensos a references/ y enlázalos

Técnica avanzada: Para validaciones críticas, empaqueta scripts que realicen verificaciones programáticamente. El código es determinístico; la interpretación de lenguaje no lo es.

MÓDULO_04

Pruebas e Iteración

Las skills pueden probarse con diferentes niveles de rigor: manual en Claude.ai, con scripts en Claude Code, o programáticamente vía API.

Tres Áreas de Testing

1. ACTIVACIÓN

¿Se carga la skill cuando debe? ¿No se carga cuando no debe?

2. FUNCIONAL

¿Produce salidas correctas? ¿Las APIs funcionan?

3. RENDIMIENTO

¿Mejora vs línea base? ¿Menos tokens/mensajes?

Suite de Pruebas de Activación

test_triggers.txt

DEBERÍA ACTIVARSE:
- "Ayúdame a configurar un nuevo espacio de ProjectHub"
- "Necesito crear un proyecto en ProjectHub"
- "Inicializa un proyecto de ProjectHub para Q4"

NO DEBERÍA ACTIVARSE:
- "¿Cuál es el clima en San Francisco?"
- "Ayúdame a escribir código Python"
- "Crea una hoja de cálculo"

Comparación de Rendimiento

Métrica	Sin Skill	Con Skill
Mensajes ida/vuelta	15 mensajes	2 preguntas
Llamadas API fallidas	3 reintentos	0 fallos
Tokens consumidos	12,000	6,000

Usando skill-creator

La skill skill-creator puede ayudarte a construir y revisar skills:

prompt para skill-creator

"Usa la skill skill-creator para ayudarme a construir 
una skill para [tu caso de uso]"

# Para revisar una skill existente:
"Revisa esta skill y sugiere mejoras"

Resumen del Módulo

01 // Estructura

SKILL.md exacto (case-sensitive), carpeta en kebab-case, sin README.md interno.

02 // Frontmatter

name + description obligatorios. Incluir QUÉ hace y CUÁNDO usarla.

03 // Instrucciones

Específicas, accionables, con ejemplos y manejo de errores documentado.

04 // Testing

Pruebas de activación, funcionales y de rendimiento. Usar skill-creator.

Basado en "The Complete Guide to Building Skills for Claude" // Anthropic

Parte 2 de 4 // Siguiente: Distribución y Patrones de Diseño