Tu Claude Agent Tiene Skills. Pero Probablemente los Está Usando Mal
Un skill genérico que hace «todo lo relacionado con el usuario» no es un skill. Es un monolito disfrazado de agente.
El problema real no está en Claude. Está en cómo defines las unidades de responsabilidad.
La mayoría de developers que construyen claude skills custom agents copian el ejemplo de la documentación, añaden tres tools más, y llaman al resultado «agente en producción».
Eso no es un agente. Es un prompt con switch/case.
Este artículo te muestra la arquitectura que separa los custom agents que escalan de los que explotan en la primera semana.
---
El Error Conceptual que Arruina el 90% de los Custom Agents
La creencia común: un skill es simplemente una función que Claude puede llamar.
La realidad: un skill es un contrato de comportamiento con inputs tipados, outputs predecibles, y manejo de errores explícito.
Si tu skill no tiene esas tres cosas, no tienes un skill. Tienes un callback.
❌ Enfoque habitual:
✅ Enfoque correcto — skill con contrato explícito:
La diferencia no es estética. Claude usa la descripción para decidir cuándo y cómo invocar el skill. Un contrato vago produce invocaciones incorrectas. Un contrato preciso produce comportamiento predecible.
---
Arquitectura de Skills en Capas: La Estructura que Funciona
Los claude skills custom agents bien construidos tienen tres capas:
→ Capa de interfaz: El tool definition que ve Claude
↳ Capa de ejecución: La función real que corre en tu servidor
↳ Capa de contrato: El schema de validación de inputs y outputs
Si fusionas las tres capas en una sola función, tienes un sistema que nadie puede depurar a las 2 de la mañana.
1. Define el Tool Definition Separado de la Lógica
2. Implementa la Ejecución con Error Handling Explícito
Este patrón tiene un beneficio crítico: Claude recibe siempre una respuesta estructurada, tanto en éxito como en error. Nunca recibe una excepción sin formato que interrumpe el flujo del agente.
---
Composición de Skills: El Patrón que Nadie Documenta
Un custom agent potente no tiene 20 skills independientes. Tiene skills orquestados en pipelines.
El truco: algunos skills son «primarios» (Claude los llama directamente) y otros son «internos» (solo los llaman otros skills).
Este patrón reduce el número de tool calls de Claude a la mitad. Menos tool calls significa menos latencia y menos tokens consumidos.
---
El Registro de Skills: Cómo Montar el Agente Final
Una vez tienes tus skills definidos y sus handlers separados, necesitas un registro centralizado.
Este registry hace que añadir un nuevo skill sea un cambio de tres líneas, no una refactorización.
---
El Loop del Agente: Conectando Todo con la API de Claude
Fíjate en is_error: !result.success. Ese campo le indica a Claude que el skill falló. Sin esa señal, Claude asume que el resultado es válido y construye respuestas incorrectas encima de datos rotos.
---
Lo que Más Falla en Producción: Tres Patrones Críticos
Skill descriptions demasiado ambiguas
Si dos skills tienen descripciones similares, Claude elegirá el incorrecto en el 30-40% de los casos. Especifica explícitamente cuándo NO usar cada skill.
No limitar el número de iteraciones del loop
Un agente sin límite de iteraciones puede entrar en un bucle infinito consumiendo tokens sin parar. Añade siempre un contador máximo:
Devolver objetos complejos sin serializar
Claude procesa el contenido del tool_result como texto. Un objeto anidado de 50 campos confunde al modelo. Devuelve solo los campos que el agente necesita para continuar.
---
Resumen: Los Principios que Separan los Skills que Escalan
→ Un skill = un contrato: inputs tipados, outputs predecibles, errores explícitos
↳ Separa la definición del handler: el tool definition es documentación para Claude, el handler es código para tu servidor
↳ Usa un registry centralizado: elimina los switch/case y hace el sistema extensible
↳ Señaliza los errores con `is_error`: Claude necesita saber cuándo un skill falló para replantear su estrategia
↳ Limita las iteraciones: un agente sin techo de iteraciones no está en producción, está en modo debug permanente
Los claude skills custom agents que sobreviven producción no son más complejos. Son más precisos en sus contratos y más honestos con sus errores.
El siguiente nivel es la orquestación multi-skill con memoria persistente entre sesiones. Pero eso solo funciona si primero tienes los skills bien construidos como unidades atómicas.
Artículos relacionados
- Supabase Edge Functions: El Pattern que el 95% de Developers No Implementa Correctamente
- Resend en Producción: Patrones Avanzados que el Tutorial Básico No Te Enseña
- Vercel en Producción: La Guía Definitiva de Deployment que Nadie Escribe
---
¿Quieres recibir contenido como este cada semana? Suscríbete a mi newsletter
