Orquestador de Agentes
Resumen
Meta-skill que orquesta todos los agentes del ecosistema. Escaneo automático de skills, coincidencia por capacidades, coordinación de flujos de trabajo multi-skill y gestión del registro.
Cuándo Usar Este Skill
- Cuando necesites asistencia especializada en este dominio
No Usar Este Skill Cuando
- La tarea no está relacionada con el orquestador de agentes
- Una herramienta más simple y específica puede manejar la solicitud
- El usuario necesita asistencia de propósito general sin experiencia en el dominio
Cómo Funciona
Meta-skill que funciona como capa central de decisión y coordinación para todo el ecosistema de skills. Realiza un escaneo automático, identifica agentes relevantes y orquesta múltiples skills para tareas complejas.
Principio: Intervención Manual Cero
- SIEMPRE escanea antes de procesar cualquier solicitud
- Las nuevas skills se auto-detectan e incluyen al crear SKILL.md en cualquier subcarpeta
- Las skills eliminadas se excluyen automáticamente del registro
- No se necesita ningún comando manual para registrar nuevas skills
Flujo de Trabajo Obligatorio (Toda Solicitud)
Ejecuta estos pasos ANTES de procesar cualquier solicitud del usuario. Los scripts usan rutas relativas automáticamente: funcionan desde cualquier directorio.
Paso 1: Auto-Descubrimiento (Escaneo)
python agent-orchestrator/scripts/scan_registry.py
Ultra-rápido (<100ms) mediante caché de hashes MD5. Solo reprocesa archivos modificados. Devuelve JSON con un resumen de todos los skills encontrados.
Paso 2: Coincidencia de Skills
python agent-orchestrator/scripts/match_skills.py "<solicitud del usuario>"
Devuelve JSON con skills clasificados por relevancia. Interpretar el resultado:
| Resultado | Acción |
|---|---|
matched: 0 | Ningún skill relevante. Operar normalmente sin skills. |
matched: 1 | Un skill relevante. Cargar su SKILL.md y seguir. |
matched: 2+ | Múltiples skills. Ejecutar Paso 3 (orquestación). |
Paso 3: Orquestación (Si Matched >= 2)
python agent-orchestrator/scripts/orchestrate.py --skills skill1,skill2 --query "<solicitud>"
Devuelve un plan de ejecución con patrón, orden de pasos y flujo de datos entre skills.
Paso Rápido (Atajo)
Para consultas simples, los pasos 1+2 se pueden combinar en secuencia:
python agent-orchestrator/scripts/scan_registry.py && python agent-orchestrator/scripts/match_skills.py "<solicitud>"
Registro de Skills
El registro reside en:
agent-orchestrator/data/registry.json
Ubicaciones de Búsqueda
El escáner busca SKILL.md en:
.claude/skills/*/(skills registradas en Claude Code)*/(skills independientes en el nivel superior)*/*\(skills en subcarpetas, hasta profundidad 3)
Metadatos por Skill
Cada entrada en el registro contiene:
| Campo | Descripción |
|---|---|
| name | Nombre del skill (del frontmatter YAML) |
| description | Descripción completa (incluye triggers) |
| location | Ruta absoluta del directorio |
| skill_md | Ruta absoluta del SKILL.md |
| registered | Si está en .claude/skills/ (verdadero/falso) |
| capabilities | Etiquetas de capacidad (autoextraídas + explícitas) |
| triggers | Keywords de activación extraídas de la descripción |
| language | Lenguaje principal (python/nodejs/bash/none) |
| status | active / incomplete / missing |
Comandos del Registro
## Escaneo Rápido (Usa Caché de Hashes)
python agent-orchestrator/scripts/scan_registry.py
## Tabla de Estado Detallada
python agent-orchestrator/scripts/scan_registry.py --status
## Re-Escaneo Completo (Ignora Caché)
python agent-orchestrator/scripts/scan_registry.py --force
Algoritmo de Coincidencia
Para cada solicitud, el emparejador puntúa skills usando:
| Criterio | Puntos | Ejemplo |
|---|---|---|
| Nombre del skill en la consulta | +15 | "use web-scraper" -> web-scraper |
| Keyword trigger exacta | +10 | "scrape" -> web-scraper |
| Categoría de capacidad | +5 | data-extraction -> web-scraper |
| Superposición de palabras | +1 | Palabras de la consulta en la descripción |
| Impulso de proyecto | +20 | Skill atribuido al proyecto activo |
Umbral mínimo: 5 puntos. Skills por debajo de esto se ignoran.
Coincidencia con Proyecto
python agent-orchestrator/scripts/match_skills.py --project mi-proyecto "consulta aquí"
Los skills atribuidos al proyecto reciben +20 de impulso automático.
Patrones de Orquestación
Cuando múltiples skills son relevantes, el orquestador clasifica el patrón:
1. Pipeline Secuencial
Los skills forman una cadena donde la salida de uno alimenta al siguiente.
Cuándo: Mezcla de skills "productores" (data-extraction, government-data) y "consumidores" (messaging, social-media).
Ejemplo: web-scraper recopila precios -> whatsapp-cloud-api envía alerta
user_query -> web-scraper -> whatsapp-cloud-api -> result
2. Ejecución Paralela
Los skills trabajan independientemente en diferentes aspectos de la solicitud.
Cuándo: Todos los skills tienen el mismo rol (todos productores o todos consumidores).
Ejemplo: instagram publica post + whatsapp envía notificación (ambos reciben el mismo contenido)
user_query -> [instagram, whatsapp-cloud-api] -> aggregated_result
3. Primario + Soporte
Un skill principal lidera; otros proporcionan datos de apoyo.
Cuándo: Un skill tiene una puntuación muy superior a las demás (>= 2x).
Ejemplo: whatsapp-cloud-api envía mensaje (primario) + web-scraper proporciona datos (soporte)
user_query -> whatsapp-cloud-api (primary) + web-scraper (support) -> result
Detalles en References/Orchestration-Patterns.Md
Gestión de Proyectos
Asignar skills a proyectos permite impulso de relevancia y contexto persistente.
Archivo de Proyectos
agent-orchestrator/data/projects.json
Operaciones
Crear proyecto: Añadir entrada al projects.json:
{
"name": "nombre-del-proyecto",
"created_at": "2026-02-25T12:00:00",
"skills": ["web-scraper", "whatsapp-cloud-api"],
"description": "Descripción del proyecto"
}
Añadir skill a proyecto: Actualizar el array skills del proyecto.
Eliminar skill de proyecto: Eliminar del array skills.
Consultar skills del proyecto: Leer el projects.json y listar skills asignados.
Añadiendo Nuevas Skills
Para añadir una nueva skill al ecosistema:
- Crear una carpeta en cualquier lugar bajo
skills root: - Crear un
SKILL.mdcon frontmatter YAML:
---
name: mi-nueva-skill
description: "Descripción con keywords de activación..."
---
## Documentación Del Skill
- ¡Listo! El auto-descubrimiento lo detecta automáticamente en la próxima solicitud.
Opcionalmente, para descubrimiento nativo de Claude Code:
4. Copiar el SKILL.md a .claude/skills/<nombre>/SKILL.md
Etiquetas de Capacidad Explícitas (Opcional)
Añadir al frontmatter para una coincidencia más precisa:
capabilities: [data-extraction, web-automation]
Ver Estado de Todas las Skills
python agent-orchestrator/scripts/scan_registry.py --status
Interpretar Estado
| Estado | Significado |
|---|---|
| active | SKILL.md con name + description presentes |
| incomplete | SKILL.md existe pero falta name o description |
| missing | El directorio existe pero sin SKILL.md |
Skills Actuales del Ecosistema
| Skill | Capacidades | Estado |
|---|---|---|
| web-scraper | data-extraction, web-automation | active |
| junta-leiloeiros | government-data, data-extraction | active |
| whatsapp-cloud-api | messaging, api-integration | active |
| social-media, api-integration | partial |
Esta tabla se actualiza automáticamente mediante scan_registry.py --status.
Mejores Prácticas
- Proporciona contexto claro y específico sobre tu proyecto y requisitos
- Revisa todas las sugerencias antes de aplicarlas al código de producción
- Combínalo con otros skills complementarios para un análisis exhaustivo
Errores Comunes
- Usar este skill para tareas fuera de su dominio de experiencia
- Aplicar recomendaciones sin entender tu contexto específico
- No proporcionar suficiente contexto del proyecto para un análisis preciso
Skills Relacionados
multi-advisor- Skill complementario para análisis mejoradotask-intelligence- Skill complementario para análisis mejorado
Limitaciones
- Usa este skill solo cuando la tarea coincida claramente con el alcance descrito anteriormente.
- No trates el resultado como un sustituto de la validación específica del entorno, las pruebas o la revisión por expertos.
- Detente y pide aclaraciones si faltan las entradas requeridas, los permisos, los límites de seguridad o los criterios de éxito.