5 patrones de diseño de habilidades de agente que todo desarrollador de ADK debería conocer

Cuando se trata de 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍, los desarrolladores tienden a obsesionarse con el formato: escribir bien el YAML, estructurar directorios y seguir la especificación. Pero con más de 30 herramientas de agentes (como Claude Code, Gemini CLI y Cursor) estandarizando el mismo diseño, el problema del formato está prácticamente superado.

El desafío ahora es el diseño del contenido. La especificación explica cómo empaquetar una habilidad, pero no ofrece ninguna guía sobre cómo estructurar la lógica interna. Por ejemplo, una habilidad que envuelve las convenciones de FastAPI funciona de manera completamente diferente a un pipeline de documentación de cuatro pasos, aunque sus archivos 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 parezcan idénticos desde fuera.

Al estudiar cómo se construyen las habilidades en todo el ecosistema —desde los repositorios de Anthropic hasta las pautas internas de Vercel y Google—, se identifican cinco patrones de diseño recurrentes que pueden ayudar a los desarrolladores a construir agentes.

De @Saboo_Shubham_ y @lavinigam

Este artículo cubre cada uno con código ADK funcional:

• Tool Wrapper: Haz que tu agente sea un experto instantáneo en cualquier biblioteca
• Generator: Produce documentos estructurados a partir de una plantilla reutilizable
• Reviewer: Evalúa código contra una lista de verificación por severidad
• Inversion: El agente te entrevista antes de actuar
• Pipeline: Impone un flujo de trabajo estricto de varios pasos con puntos de control

Patrón 1: El Tool Wrapper

Un Tool Wrapper le brinda a tu agente contexto bajo demanda para una biblioteca específica. En lugar de codificar las convenciones de una API en tu prompt del sistema, las empaquetas en una habilidad. Tu agente solo carga este contexto cuando realmente trabaja con esa tecnología.

Es el patrón más sencillo de implementar. El archivo 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 escucha palabras clave específicas de la biblioteca en el prompt del usuario, carga dinámicamente tu documentación interna desde el directorio 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ y aplica esas reglas como verdad absoluta. Este es el mecanismo exacto que usas para distribuir las pautas de codificación internas de tu equipo o las mejores prácticas específicas de un framework directamente en los flujos de trabajo de tus desarrolladores.

Aquí tienes un ejemplo de un Tool Wrapper que enseña a un agente a escribir código FastAPI. Observa cómo las instrucciones le indican explícitamente al agente que cargue el archivo 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 solo cuando comience a revisar o escribir código:

1# skills/api-expert/SKILL.md
2---
3name: api-expert
4description: Mejores prácticas y convenciones de desarrollo de FastAPI. Úsalo al construir, revisar o depurar aplicaciones FastAPI, APIs REST o modelos Pydantic.
5metadata:
6  pattern: tool-wrapper
7  domain: fastapi
8---
9
10Eres un experto en desarrollo FastAPI. Aplica estas convenciones al código o pregunta del usuario.
11
12## Convenciones Principales
13
14Carga 'references/conventions.md' para la lista completa de mejores prácticas de FastAPI.
15
16## Al Revisar Código
171. Carga las convenciones de referencia
182. Verifica el código del usuario contra cada convención
193. Por cada violación, cita la regla específica y sugiere la corrección
20
21## Al Escribir Código
221. Carga las convenciones de referencia
232. Sigue cada convención exactamente
243. Añade anotaciones de tipo a todas las firmas de funciones
254. Usa el estilo Annotated para inyección de dependencias

Patrón 2: El Generator

Mientras que el Tool Wrapper aplica conocimiento, el Generator impone una salida consistente. Si te cuesta que un agente genere diferentes estructuras de documentos en cada ejecución, el Generator resuelve esto orquestando un proceso de completar espacios en blanco.

Aprovecha dos directorios opcionales: 𝚊𝚜𝚜𝚎𝚝𝚜/ contiene tu plantilla de salida, y 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ contiene tu guía de estilo. Las instrucciones actúan como un gestor de proyectos. Le indican al agente que cargue la plantilla, lea la guía de estilo, pregunte al usuario por las variables faltantes y complete el documento. Esto es práctico para generar documentación de API predecible, estandarizar mensajes de commit o estructurar la arquitectura de proyectos.

En este ejemplo de generador de informes técnicos, el archivo de habilidad no contiene el diseño real ni las reglas gramaticales. Simplemente coordina la recuperación de esos activos y obliga al agente a ejecutarlos paso a paso:

1# skills/report-generator/SKILL.md
2---
3name: report-generator
4description: Genera informes técnicos estructurados en Markdown. Úsalo cuando el usuario pida escribir, crear o redactar un informe, resumen o documento de análisis.
5metadata:
6  pattern: generator
7  output-format: markdown
8---
9
10Eres un generador de informes técnicos. Sigue estos pasos exactamente:
11
12Paso 1: Carga 'references/style-guide.md' para las reglas de tono y formato.
13
14Paso 2: Carga 'assets/report-template.md' para la estructura de salida requerida.
15
16Paso 3: Pregunta al usuario por cualquier información faltante necesaria para completar la plantilla:
17- Tema o asunto
18- Hallazgos clave o puntos de datos
19- Audiencia objetivo (técnica, ejecutiva, general)
20
21Paso 4: Completa la plantilla siguiendo las reglas de la guía de estilo. Cada sección de la plantilla debe estar presente en la salida.
22
23Paso 5: Devuelve el informe completo como un único documento Markdown.

Patrón 3: El Reviewer

El patrón Reviewer separa qué revisar de cómo revisarlo. En lugar de escribir un prompt del sistema largo detallando cada olor a código, almacenas una rúbrica modular dentro de un archivo 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍.

Cuando un usuario envía código, el agente carga esta lista de verificación y puntúa metódicamente la entrega, agrupando sus hallazgos por severidad. Si cambias una lista de verificación de estilo Python por una lista de verificación de seguridad OWASP, obtienes una auditoría completamente diferente y especializada utilizando la misma infraestructura de habilidades. Es una forma muy efectiva de automatizar revisiones de PR o detectar vulnerabilidades antes de que un humano vea el código.

La siguiente habilidad de revisor de código demuestra esta separación. Las instrucciones permanecen estáticas, pero el agente carga dinámicamente los criterios de revisión específicos de una lista de verificación externa y fuerza una salida estructurada basada en la severidad:

1# skills/code-reviewer/SKILL.md
2---
3name: code-reviewer
4description: Revisa código Python en busca de calidad, estilo y errores comunes. Úsalo cuando el usuario envíe código para revisar, pida comentarios sobre su código o quiera una auditoría de código.
5metadata:
6  pattern: reviewer
7  severity-levels: error,warning,info
8---
9
10Eres un revisor de código Python. Sigue este protocolo de revisión exactamente:
11
12Paso 1: Carga 'references/review-checklist.md' para los criterios de revisión completos.
13
14Paso 2: Lee el código del usuario cuidadosamente. Comprende su propósito antes de criticar.
15
16Paso 3: Aplica cada regla de la lista de verificación al código. Por cada violación encontrada:
17- Anota el número de línea (o ubicación aproximada)
18- Clasifica la severidad: error (debe corregirse), warning (debería corregirse), info (considerar)
19- Explica POR QUÉ es un problema, no solo QUÉ está mal
20- Sugiere una corrección específica con el código corregido
21
22Paso 4: Produce una revisión estructurada con estas secciones:
23- **Resumen**: Qué hace el código, evaluación general de calidad
24- **Hallazgos**: Agrupados por severidad (errores primero, luego advertencias, luego información)
25- **Puntuación**: Califica del 1 al 10 con una breve justificación
26- **Top 3 Recomendaciones**: Las mejoras más impactantes

Patrón 4: Inversion

Los agentes tienden inherentemente a adivinar y generar de inmediato. El patrón Inversion invierte esta dinámica. En lugar de que el usuario impulse el prompt y el agente ejecute, el agente actúa como un entrevistador.

Inversion se basa en instrucciones de control explícitas e innegociables (como "NO empieces a construir hasta que todas las fases estén completas") para forzar al agente a recopilar contexto primero. Hace preguntas estructuradas secuencialmente y espera tus respuestas antes de pasar a la siguiente fase. El agente se niega a sintetizar una salida final hasta que tenga una imagen completa de tus requisitos y restricciones de implementación.

Para ver esto en acción, mira esta habilidad de planificador de proyectos. El elemento crucial aquí es la estricta división en fases y la instrucción explícita de control que impide que el agente sintetice el plan final hasta que se hayan recopilado todas las respuestas del usuario:

1# skills/project-planner/SKILL.md
2---
3name: project-planner
4description: Planifica un nuevo proyecto de software recopilando requisitos mediante preguntas estructuradas antes de producir un plan. Úsalo cuando el usuario diga "quiero construir", "ayúdame a planificar", "diseña un sistema" o "inicia un nuevo proyecto".
5metadata:
6  pattern: inversion
7  interaction: multi-turn
8---
9
10Estás realizando una entrevista estructurada de requisitos. NO empieces a construir o diseñar hasta que todas las fases estén completas.
11
12## Fase 1 — Descubrimiento del Problema (haz una pregunta a la vez, espera cada respuesta)
13
14Haz estas preguntas en orden. No omitas ninguna.
15
16- P1: "¿Qué problema resuelve este proyecto para sus usuarios?"
17- P2: "¿Quiénes son los usuarios principales? ¿Cuál es su nivel técnico?"
18- P3: "¿Cuál es la escala esperada? (usuarios por día, volumen de datos, tasa de solicitudes)"
19
20## Fase 2 — Restricciones Técnicas (solo después de que la Fase 1 esté completamente respondida)
21
22- P4: "¿Qué entorno de implementación usarás?"
23- P5: "¿Tienes algún requisito o preferencia de stack tecnológico?"
24- P6: "¿Cuáles son los requisitos no negociables? (latencia, tiempo de actividad, cumplimiento, presupuesto)"
25
26## Fase 3 — Síntesis (solo después de que todas las preguntas estén respondidas)
27
281. Carga 'assets/plan-template.md' para el formato de salida
292. Completa cada sección de la plantilla usando los requisitos recopilados
303. Presenta el plan completo al usuario
314. Pregunta: "¿Este plan captura con precisión tus requisitos? ¿Qué cambiarías?"
325. Itera sobre los comentarios hasta que el usuario confirme

Patrón 5: El Pipeline

Para tareas complejas, no puedes permitirte saltar pasos o ignorar instrucciones. El patrón Pipeline impone un flujo de trabajo secuencial estricto con puntos de control sólidos.

Las propias instrucciones sirven como definición del flujo de trabajo. Al implementar condiciones de puerta diamante explícitas (como requerir la aprobación del usuario antes de pasar de la generación de docstrings al ensamblaje final), el Pipeline asegura que un agente no pueda omitir una tarea compleja y presentar un resultado final no validado.

Este patrón utiliza todos los directorios opcionales, extrayendo diferentes archivos de referencia y plantillas solo en el paso específico donde se necesitan, manteniendo la ventana de contexto limpia.

En este ejemplo de pipeline de documentación, observa las condiciones de puerta explícitas. Al agente se le prohíbe explícitamente pasar a la fase de ensamblaje hasta que el usuario confirme los docstrings generados en el paso anterior:

1# skills/doc-pipeline/SKILL.md
2---
3name: doc-pipeline
4description: Genera documentación de API a partir de código fuente Python mediante un pipeline de varios pasos. Úsalo cuando el usuario pida documentar un módulo, generar documentación de API o crear documentación a partir de código.
5metadata:
6  pattern: pipeline
7  steps: "4"
8---
9
10Estás ejecutando un pipeline de generación de documentación. Ejecuta cada paso en orden. NO omitas pasos ni continúes si un paso falla.
11
12## Paso 1 — Analizar e Inventariar
13Analiza el código Python del usuario para extraer todas las clases, funciones y constantes públicas. Presenta el inventario como una lista de verificación. Pregunta: "¿Esta es la API pública completa que deseas documentar?"
14
15## Paso 2 — Generar Docstrings
16Para cada función que carezca de un docstring:
17- Carga 'references/docstring-style.md' para el formato requerido
18- Genera un docstring siguiendo exactamente la guía de estilo
19- Presenta cada docstring generado para aprobación del usuario
20NO continúes al Paso 3 hasta que el usuario confirme.
21
22## Paso 3 — Ensamblar Documentación
23Carga 'assets/api-doc-template.md' para la estructura de salida. Compila todas las clases, funciones y docstrings en un único documento de referencia de API.
24
25## Paso 4 — Control de Calidad
26Revisa contra 'references/quality-checklist.md':
27- Cada símbolo público documentado
28- Cada parámetro tiene un tipo y una descripción
29- Al menos un ejemplo de uso por función
30Informa los resultados. Corrige los problemas antes de presentar el documento final.

Cómo elegir el patrón de habilidad de agente adecuado

Cada patrón responde a una pregunta diferente. Usa este árbol de decisión para encontrar el patrón correcto para tu caso de uso:

Y, por último, los patrones se combinan

Estos patrones no son mutuamente excluyentes. Se combinan.

Una habilidad Pipeline puede incluir un paso Reviewer al final para verificar su propio trabajo. Un Generator puede apoyarse en Inversion al principio para recopilar las variables necesarias antes de completar su plantilla. Gracias a 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 y la divulgación progresiva de ADK, tu agente solo gasta tokens de contexto en los patrones exactos que necesita en tiempo de ejecución.

Deja de intentar meter instrucciones complejas y frágiles en un único prompt del sistema. Divide tus flujos de trabajo, aplica el patrón estructural correcto y construye agentes fiables.

Empieza hoy

La especificación de Agent Skills es de código abierto y compatible de forma nativa con ADK. Ya sabes cómo empaquetar el formato. Ahora sabes cómo diseñar el contenido. Ve y construye agentes más inteligentes con Kit de Desarrollo de Agentes de Google.