5 patrones de diseño de habilidades de agente que todo desarrollador de ADK debe conocer

Cuando se trata de 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍, los desarrolladores tienden a obsesionarse con el formato —configurar bien el YAML, estructurar los 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 ya es prácticamente obsoleto.

El verdadero 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 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 se vean idénticos por fuera.

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

Por @Saboo_Shubham_ y @lavinigam

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

• Envoltorio de Herramienta (Tool Wrapper): Convierte a tu agente en un experto instantáneo en cualquier librería
• Generador (Generator): Produce documentos estructurados a partir de una plantilla reutilizable
• Revisor (Reviewer): Evalúa código contra una lista de verificación por severidad
• Inversión (Inversion): El agente te entrevista antes de actuar
• Pipeline (Pipeline): Aplica un flujo de trabajo estricto de múltiples pasos con puntos de control

Patrón 1: El Envoltorio de Herramienta

Un Envoltorio de Herramienta le da a tu agente contexto bajo demanda para una librería específica. En lugar de codificar las convenciones de la 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 librería 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 guías de codificación internas de tu equipo o las mejores prácticas de frameworks específicos directamente en los flujos de trabajo de tus desarrolladores.

Aquí tienes un ejemplo de un Envoltorio de Herramienta que le enseña a un agente cómo 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 en 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 la referencia de convenciones
182. Verifica el código del usuario contra cada convención
193. Para cada infracción, cita la regla específica y sugiere la corrección
20
21## Al Escribir Código
221. Carga la referencia de convenciones
232. Sigue cada convención al pie de la letra
243. Añade anotaciones de tipo a todas las firmas de funciones
254. Usa el estilo Annotated para la inyección de dependencias

Patrón 2: El Generador

Mientras que el Envoltorio de Herramienta aplica conocimiento, el Generador impone una salida consistente. Si te cuesta que un agente genere estructuras de documento diferentes en cada ejecución, el Generador lo resuelve orquestando un proceso de llenar 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 proyecto. 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 arquitecturas 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 recursos 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 llenar la plantilla:
17- Tema o asunto
18- Hallazgos clave o puntos de datos
19- Audiencia objetivo (técnica, ejecutiva, general)
20
21Paso 4: Llena 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 solo documento Markdown.

Patrón 3: El Revisor

El patrón Revisor separa qué revisar de cómo revisarlo. En lugar de escribir un prompt de sistema largo detallando cada mal olor en el 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 propuesta, agrupando sus hallazgos por severidad. Si reemplazas una lista de verificación de estilo Python por una lista de seguridad OWASP, obtienes una auditoría completamente diferente y especializada usando la misma infraestructura de habilidad. Es una forma muy eficaz de automatizar revisiones de PR o detectar vulnerabilidades antes de que un humano revise 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 desde una lista de verificación externa y fuerza una salida estructurada basada en 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 revisión, pida retroalimentación 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 con atención. Comprende su propósito antes de criticarlo.
15
16Paso 3: Aplica cada regla de la lista de verificación al código. Por cada infracció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 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- **Puntaje**: Califica del 1 al 10 con una breve justificación
26- **Top 3 Recomendaciones**: Las mejoras de mayor impacto

Patrón 4: Inversión

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

La Inversión se apoya en instrucciones de control explícitas y no negociables (como "NO empieces a construir hasta que todas las fases estén completas") para obligar al agente a recopilar contexto primero. Hace preguntas estructuradas de forma secuencial y espera tus respuestas antes de pasar a la siguiente fase. El agente se niega a sintetizar una salida final hasta tener una imagen completa de tus requisitos y limitaciones de despliegue.

Para verlo en acción, observa esta habilidad de planificador de proyectos. El elemento crucial aquí es la estricta división en fases y el prompt de control explícito 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 a través de preguntas estructuradas antes de producir un plan. Úsalo cuando el usuario diga "quiero construir", "ayúdame a planificar", "diseña un sistema" o "iniciar un nuevo proyecto".
5metadata:
6  pattern: inversion
7  interaction: multi-turn
8---
9
10Estás realizando una entrevista de requisitos estructurada. 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 te saltes 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 despliegue 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 normativo, 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. Llena 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 según la retroalimentación hasta que el usuario confirme

Patrón 5: El Pipeline

Para tareas complejas, no puedes permitirte pasos saltados o instrucciones ignoradas. El patrón Pipeline impone un flujo de trabajo estricto y secuencial con puntos de control obligatorios.

Las propias instrucciones sirven como definición del flujo de trabajo. Al implementar condiciones de compuerta de diamante explícitas (como requerir la aprobación del usuario antes de pasar de la generación de docstrings al ensamblaje final), el Pipeline garantiza 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 limpia la ventana de contexto.

En este ejemplo de pipeline de documentación, observa las condiciones de compuerta explícitas. Se prohíbe explícitamente al agente 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 múltiples 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 te saltes pasos ni continúes si un paso falla.
11
12## Paso 1 — Análisis e Inventario
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: "¿Es esta 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 la guía de estilo exactamente
19- Presenta cada docstring generado para la aprobación del usuario
20No pases 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 solo 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 adecuado para tu caso de uso:

Y finalmente, los patrones se combinan

Estos patrones no son mutuamente excluyentes. Se combinan.

Una habilidad Pipeline puede incluir un paso de Revisor al final para verificar su propio trabajo. Un Generador puede apoyarse en la Inversión al principio para recopilar las variables necesarias antes de llenar su plantilla. Gracias a 𝚂𝚔𝚒𝚕𝚕𝚃𝚘𝚘𝚕𝚜𝚎𝚝 de ADK y la divulgación progresiva, 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 solo prompt del sistema. Divide tus flujos de trabajo, aplica el patrón estructural correcto y construye agentes confiables.

Comienza hoy

La especificación de Habilidades para Agentes 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 Google Agent Development Kit.