Guia de Skills para Claude - Parte 4

Claude // Agent Skills

Troubleshooting y Referencias

Parte 4: Solución de errores comunes, checklist y recursos oficiales

Incluso las skills mejor diseñadas pueden encontrar problemas. Esta sección cubre los errores más comunes y sus soluciones, además de proporcionar una checklist completa y enlaces a recursos oficiales de Anthropic.

MÓDULO_01

Errores de Subida

Los errores más frecuentes ocurren durante la subida de la skill a Claude.ai. La mayoría se relacionan con nomenclatura y formato.

Error: Could not find SKILL.md

Mensaje: "Could not find SKILL.md in uploaded folder"
Causa: El archivo no está nombrado exactamente SKILL.md

Solución: Renombrar a SKILL.md (case-sensitive). Verificar con ls -la.

Error: Invalid Frontmatter

Mensaje: "Invalid frontmatter"
Causa: Problema de formato YAML

errores comunes de YAML

# ❌ Incorrecto - faltan delimitadores
name: my-skill
description: Hace cosas

# ❌ Incorrecto - comillas sin cerrar
name: my-skill
description: "Hace cosas

# ✅ Correcto
---
name: my-skill
description: Hace cosas
---

Error: Invalid Skill Name

Mensaje: "Invalid skill name"
Causa: El nombre tiene espacios o mayúsculas

nomenclatura correcta

name: My Cool Skill    # ❌ Incorrecto
name: my_cool_skill    # ❌ Incorrecto
name: my-cool-skill    # ✅ Correcto (kebab-case)

MÓDULO_02

Problemas de Activación

Skill No Se Activa (Sub-triggering)

Síntoma: La skill nunca se carga automáticamente
Causa: Descripción demasiado vaga o sin activadores específicos

Solución: Añade más detalle a la descripción con frases que los usuarios realmente dirían. Incluye palabras clave técnicas específicas.

Debug tip: Pregunta a Claude: "¿Cuándo usarías la skill [nombre]?" — Claude citará la descripción y podrás ver qué falta.

Skill Se Activa Demasiado (Over-triggering)

Síntoma: La skill se carga para consultas no relacionadas
Causa: Descripción demasiado amplia

añadir activadores negativos

# ❌ Demasiado amplio
description: Procesa documentos

# ✅ Más específico con negativo
description: Análisis de datos avanzado para 
archivos CSV. Usar para modelado estadístico, 
regresión, clustering. NO usar para exploración 
de datos simple (usar skill data-viz en su lugar).

Problemas de Conexión MCP

Síntoma: La skill se carga pero las llamadas MCP fallan

• Verificar servidor MCP conectado en Configuración > Extensiones
• Confirmar API keys válidas y no expiradas
• Verificar permisos y scopes correctos
• Probar MCP independientemente sin la skill
• Verificar nombres de herramientas (case-sensitive)

MÓDULO_03

Checklist de Validación

Usa esta checklist antes y después de subir tu skill para asegurar que todo esté correcto.

Antes de Empezar

• Identificados 2-3 casos de uso concretos
• Herramientas identificadas (integradas o MCP)
• Revisada la guía y skills de ejemplo
• Estructura de carpetas planeada

Durante el Desarrollo

• Carpeta nombrada en kebab-case
• Archivo SKILL.md existe (ortografía exacta)
• Frontmatter tiene delimitadores ---
• Campo name: kebab-case, sin espacios
• Description incluye QUÉ y CUÁNDO
• Sin etiquetas XML en ningún lugar
• Instrucciones claras y accionables
• Manejo de errores incluido
• Ejemplos proporcionados

Antes de Subir

• Probada activación en tareas obvias
• Probada activación en solicitudes parafraseadas
• Verificado que no se activa en temas no relacionados
• Pruebas funcionales pasan
• Comprimido como archivo .zip

Después de Subir

• Probar en conversaciones reales
• Monitorear sub/sobre-activación
• Recopilar feedback de usuarios
• Iterar en descripción e instrucciones

MÓDULO_04

Recursos y Referencias

Documentación Oficial

Best Practices Guide

Guía oficial de mejores prácticas para skills

Skills Documentation

Documentación técnica completa

API Reference

Referencia del endpoint /v1/skills

MCP Documentation

Model Context Protocol docs

Skills de Ejemplo

Repositorio	Contenido
anthropics/skills	Skills oficiales de Anthropic
Document Skills	PDF, DOCX, PPTX, XLSX
Partner Skills	Asana, Atlassian, Canva, Figma, Sentry, Zapier

Herramientas

skill-creator

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

# Revisar una skill existente
"Revisa esta skill y sugiere mejoras"

Soporte

• Preguntas técnicas: Claude Developers Discord
• Bug reports: GitHub Issues en anthropics/skills
• Incluir: nombre de skill, mensaje de error, pasos para reproducir

Resumen de la Serie

Parte 1 // Fundamentos

Qué son las skills, componentes, principios de diseño, integración con MCP.

Parte 2 // Técnico

Estructura de archivos, YAML frontmatter, instrucciones efectivas, testing.

Parte 3 // Patrones

Distribución, 5 patrones de diseño: secuencial, multi-MCP, iterativo, contextual, dominio.

Parte 4 // Referencias

Troubleshooting, checklist de validación, recursos oficiales de Anthropic.

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

Serie Completa // 4 Partes // github.com/anthropics/skills