error-handling-patterns

Visión general de la skill error-handling-patterns

Qué hace la skill error-handling-patterns

La skill error-handling-patterns ayuda a un agente a diseñar un mejor comportamiento ante fallos, no solo a parchear bloques try/catch. Se centra en decisiones prácticas, como cuándo usar excepciones frente a retornos de tipo Result, cómo clasificar fallos recuperables frente a irrecuperables, cómo propagar contexto y cómo degradar el servicio con elegancia durante caídas parciales.

Quién debería usar esta skill

Esta skill encaja especialmente bien para desarrolladores, tech leads y equipos centrados en Reliability que trabajan con APIs, servicios, flujos asíncronos, integraciones o sistemas distribuidos. Resulta especialmente útil cuando necesitas semánticas de error consistentes en todo un código base, en lugar de arreglos puntuales.

Trabajo que resuelve

La mayoría de los usuarios no necesita una lección teórica sobre errores. Necesita ayuda para responder preguntas como: ¿Qué debería fallar rápido? ¿Qué conviene reintentar? ¿Qué debe devolver errores estructurados a quien llama? ¿Qué se debe registrar, exponer, envolver o suprimir? La skill error-handling-patterns aporta valor cuando esas decisiones afectan a la mantenibilidad, la velocidad de depuración o la disponibilidad.

Qué la diferencia de un prompt genérico

Un prompt genérico suele producir recomendaciones superficiales como “añade reintentos” o “usa try/catch”. Esta skill está más orientada a la toma de decisiones. Organiza el manejo de errores en torno a filosofía, categorías de error y patrones específicos por lenguaje, lo que la hace más útil para obtener guía de arquitectura e implementación alineada con Reliability.

Qué conviene saber antes de instalarla

Esta es una skill basada en documentación, con un único archivo SKILL.md y sin scripts auxiliares, referencias ni recursos de ejemplo. Eso simplifica la adopción, pero también significa que la calidad de la salida depende mucho de lo específico que sea tu prompt y del contexto de código que aportes.

Cómo usar la skill error-handling-patterns

Opciones de instalación de error-handling-patterns

Instálala desde el repositorio con:

npx skills add https://github.com/wshobson/agents --skill error-handling-patterns

Si tu entorno ya sincroniza skills desde ese repositorio, puede que solo necesites habilitar o invocar error-handling-patterns por nombre dentro del flujo de trabajo de tu agente.

Qué leer primero después de instalarla

Empieza por:

• plugins/developer-essentials/skills/error-handling-patterns/SKILL.md

Como esta skill se entrega como un único documento principal, no hay un proceso de onboarding largo. Lee primero las secciones “When to Use This Skill” y “Core Concepts”, y después salta a las partes específicas del lenguaje que correspondan a tu stack.

Qué información necesita la skill para funcionar bien

La skill error-handling-patterns rinde mejor cuando proporcionas:

• Lenguaje y framework
• Tipo de runtime: CLI, API, worker, UI, service, library
• Modos de fallo que te preocupan
• Si quien llama es user-facing, interno o machine-to-machine
• Restricciones existentes, como backward compatibility, latency budgets o logging standards

Input débil: “Improve error handling in this service.”

Input sólido: “Review this Go HTTP service. Separate validation errors from dependency failures, recommend retry boundaries, define what should be returned to clients vs logged internally, and suggest error wrapping patterns that preserve root cause.”

Convierte un objetivo difuso en un prompt sólido para error-handling-patterns

Usa una estructura de prompt como esta:

1. Indica el sistema y el lenguaje.
2. Nombra los escenarios de fallo.
3. Describe el comportamiento deseado para callers y operators.
4. Pide patrones concretos, no principios genéricos.
5. Solicita recomendaciones a nivel de código si puedes compartir el código fuente.

Ejemplo:

Use the error-handling-patterns skill for a Python background worker that calls a rate-limited API and writes to Postgres. I need recommendations for transient vs permanent error handling, retry policy boundaries, idempotency concerns, logging fields, and what errors should stop the job versus be skipped and reported.

Mejores flujos de trabajo para un uso práctico

Usa esta skill en uno de estos tres modos:

• Design mode: antes de implementar, para definir contratos de error y comportamiento de recuperación
• Refactor mode: cuando un código base tiene excepciones, valores de retorno o logging inconsistentes
• Incident mode: después de fallos en producción, para rediseñar el manejo a partir de clases de fallo reales

Para la mayoría de los equipos, el flujo de mayor valor es: clasificar errores -> elegir el modelo de propagación -> definir el comportamiento de cara a quien llama -> añadir observabilidad -> probar rutas de fallo.

Dónde esta skill destaca más

La skill es más fuerte cuando necesitas guía sobre:

• Excepciones frente a tipos Result
• Errores recuperables frente a irrecuperables
• Criterios de reintentos y circuit breaker
• Manejo de fallos asíncronos y concurrentes
• Mejor contexto para depuración y operación
• Degradación elegante en sistemas sensibles a la fiabilidad

Es más útil para decidir políticas y patrones que para generar boilerplate específico de un framework.

Ruta de lectura del repositorio para evaluarla más rápido

Si estás decidiendo si adoptar la error-handling-patterns skill, revisa el repositorio en este orden:

1. Lista de encabezados de SKILL.md
2. “When to Use This Skill”
3. “Core Concepts”
4. Secciones sobre patrones específicos por lenguaje
5. Cualquier ejemplo que muestre retries, propagation y graceful failure

Esto te permite ver rápido si encaja con tu stack y si aporta suficiente estructura más allá de un prompting normal.

Consejos prácticos que mejoran la calidad de la salida

Pide a la skill que haga explícitos los tradeoffs. Los buenos prompts incluyen preguntas como:

• ¿Qué fallos son resultados de negocio esperables y cuáles son verdaderas excepciones?
• ¿Dónde deberían vivir los retries para evitar trabajo duplicado?
• ¿Qué contexto debería adjuntarse antes de relanzar o devolver un error?
• ¿Qué errores deberían ser visibles para el usuario, sanitizados o solo internos?
• ¿Cuándo debería el sistema degradarse en lugar de abortar?

Estos detalles suelen importar más que pedir simplemente “best practices”.

Restricciones y casos en los que no encaja bien

No esperes que esta skill sustituya documentación profunda de frameworks, playbooks de SRE o referencias del runtime del lenguaje. No incluye tooling ejecutable ni reglas de lint. Si solo necesitas ayuda de sintaxis para una construcción concreta de un lenguaje, un prompt más específico puede ser más rápido. El caso de uso de error-handling-patterns usage es más sólido cuando tu problema real es la consistencia de diseño y la Reliability ante fallos.

Preguntas frecuentes sobre la skill error-handling-patterns

¿error-handling-patterns es buena para principiantes?

Sí, si ya entiendes el flujo de control básico y quieres una guía estructurada para manejar fallos. Es menos adecuada como primera introducción a los errores de programación, porque se centra en decisiones de diseño y no solo en sintaxis.

¿Cuándo debería usar esto en lugar de un prompt de código normal?

Usa error-handling-patterns cuando el comportamiento ante fallos sea el problema central. Si te importan los contratos de API, los retries, los modos degradados o la observabilidad durante fallos, esta skill ofrece un marco mejor que una petición genérica de “add error handling”.

¿La skill admite varios lenguajes?

Sí. La fuente cubre explícitamente filosofías transversales a distintos lenguajes, como excepciones, tipos Result y categorías de error, y después pasa a patrones específicos por lenguaje. Eso la hace útil para equipos con stacks mixtos, aunque sigue siendo necesario indicar el lenguaje en el prompt.

¿error-handling-patterns sirve para equipos de Reliability?

Sí. El encaje de error-handling-patterns for Reliability es fuerte porque ayuda a definir cómo se comportan los sistemas durante fallos de dependencias, caídas parciales y errores asíncronos. Es especialmente relevante para responsables de servicios que necesitan un comportamiento consistente tanto de cara a operadores como a callers.

¿Cuáles son los límites de la skill?

Esta skill ayuda con la toma de decisiones y con patrones de implementación alrededor de los fallos. No proporciona harnesses de pruebas, dashboards de producción ni automatización específica del repositorio. Aun así, debes validar las recomendaciones frente a tu arquitectura y tu historial de incidentes.

¿Cuándo encaja mal esta skill?

Evítala si tu necesidad es puramente mecánica, como corregir un único error del compilador o aprender la sintaxis exacta de un tipo de excepción concreto de un framework. También encaja peor cuando el problema real son reglas de dominio ausentes, y no una mala estructura de manejo de errores.

Cómo mejorar la skill error-handling-patterns

Dale a error-handling-patterns un mapa de fallos, no solo código

Los resultados mejoran cuando nombras el panorama de fallos:

• errores de validación
• timeouts de dependencias
• rate limits
• escrituras parciales
• solicitudes duplicadas
• fallos de deserialización
• bugs de programación

Esto permite que la skill recomiende rutas de manejo distintas, en lugar de forzar un único patrón para todos los errores.

Separa la experiencia de quien llama de la experiencia del operador

Un modo de fallo habitual es pedir “mejores errores” sin aclarar para quién. Dile a la skill qué deberían ver los usuarios finales, qué deberían recibir los clientes de API y qué necesitan los operadores en logs o trazas. Eso produce recomendaciones más útiles sobre sanitización, wrapping y propagación de contexto.

Pide una taxonomía de errores explícita

Si la primera respuesta te parece genérica, pide a la skill error-handling-patterns que genere:

• clases o categorías de error
• límites entre recuperable e irrecuperable
• reglas de retryable vs non-retryable
• mapeo de errores internos a respuestas externas

Esto suele convertir consejos vagos en guía lista para implementar.

Aporta restricciones reales que cambien la elección del patrón

Los patrones cambian cuando tienes SLOs de latencia estrictos, retries costosos, riesgos de idempotencia o contratos de API con backward compatibility. Menciona esas restricciones de forma explícita. A menudo determinan si conviene devolver un Result, lanzar una excepción, hacer short-circuit, encolar para más tarde o degradar el servicio con elegancia.

Pide una iteración después del primer borrador

Una segunda pasada sólida suele verse así:

Revise the recommendation for a high-throughput service. Minimize allocation-heavy exception paths, preserve root cause for debugging, and propose a small set of standard error types the whole team can adopt.

La iteración importa porque el mejor patrón depende de la escala, la audiencia y las consecuencias operativas.

Prompts débiles habituales que conviene evitar

Evita prompts como:

• "Handle errors better"
• "Add retries everywhere"
• "Make it production ready"

Estos ocultan los criterios de decisión. La skill es mucho más eficaz cuando se le pide elegir entre tradeoffs, no simplemente decorar el código con construcciones defensivas.

Cómo validar la salida

Después de usar la guía error-handling-patterns, comprueba si la recomendación:

• distingue los fallos esperables de los bugs
• evita tormentas de retries
• preserva suficiente contexto para depurar
• expone errores seguros y estables a quien llama
• admite degradación elegante cuando corresponde

Si no es así, ajusta el prompt con casos de fallo concretos y resultados deseados, en lugar de pedir más detalle de forma abstracta.