Guía de inicio para Agency Agents: convierte Claude Code en el “equipo soñado” con 100+ roles de expertos en IA

Todos sabemos que escribir prompts es un oficio. Con el mismo modelo de Claude, el resultado entre “Escríbeme un componente de React” y “Desde la perspectiva de un ingeniero frontend senior, sigue las especificaciones WCAG 2.1 AA y escribe una tabla virtualizable accesible usando TypeScript + React 18” puede ser abismal.

Agency Agents existe precisamente para resolver ese problema: organiza 16 departamentos y 100+ roles de expertos en IA (Frontend Developer, Backend Architect, Security Auditor, Reddit Community Ninja…) con sus identidades, flujos, entregables y métricas de evaluación ya definidos; solo necesitas activar el rol correspondiente y la IA entra automáticamente en “modo profesional”.

Además, el repositorio incluye convert.sh e install.sh, con los que puedes sincronizar en un clic la misma definición de roles hacia Claude Code, OpenClaw, Cursor, OpenCode, Codex, Gemini CLI y más de 10 herramientas, sin tener que mantener múltiples configuraciones.

En este artículo, lo haremos juntos desde cero: lo ponemos en marcha y mostramos cómo activar un rol en OpenClaw para completar una necesidad real.

Introducción al proyecto

msitarzewski/agency-agents nació de un debate en un post de Reddit sobre “si pudieras contratar un equipo de empleados de IA, ¿qué puestos elegirías?”. Tras meses de iteración, ha evolucionado hasta convertirse en un catálogo bastante completo de roles/estilo “agentes” de IA:

• 16 departamentos: engineering, design, marketing, finance, security, sales, testing… cubren prácticamente todos los puestos que necesitaría una empresa de software
• 100+ roles: desde Frontend Developer y Backend Architect, hasta Whimsy Injector y Reality Checker, roles con “temperatura” de personalidad
• Entregables medibles: cada rol incluye success metrics, deliverables y critical rules; no son prompts vacíos
• Multiherramienta: una misma fuente Markdown se puede convertir a formatos como Claude Code subagent, workspace de OpenClaw, reglas de Cursor (Cursor rule), agent de OpenCode, TOML de Codex, etc.

La diferencia clave frente a una plantilla de prompts tradicional es que aquí cada rol tiene una configuración totalmente humanizada (tono, estilo, mecanismo de memoria) + un flujo de negocio (mission / workflow / deliverables), mucho más parecido a “una descripción de puesto”.

Dificultad / duración / resultados

• Dificultad: ⭐⭐ (solo usar comandos en la terminal, sin ningún umbral de código)
• Duración: 15-30 minutos (primera instalación + activar un rol + completar un requerimiento real)
• Resultados: convertir Claude Code / OpenClaw en un equipo de IA multirrol “bajo demanda” y mantener a largo plazo una identidad profesional estable

Perfil de lectores objetivo

• Desarrolladores que quieren ganar productividad con IA, pero les resulta demasiado engorroso escribir prompts
• Ingenieros frontend / backend / full-stack / seguridad / testing con 1-5 años de experiencia
• Personas que ya están usando herramientas de programación con IA como Claude Code, Cursor, OpenClaw, Codex, etc.
• Tech Leads que quieren implantar en su equipo una “normativa de colaboración con IA”

Dependencias clave y entorno

Estructura completa del proyecto (árbol)

agency-agents/
├── academic/                       # Investigación académica
├── design/                         # Diseño UI/UX
├── engineering/                    # Desarrollo (el mayor departamento, 30+ roles)
├── finance/                        # Finanzas
├── game-development/               # Desarrollo de videojuegos
├── gis/                            # Información geográfica
├── marketing/                      # Marketing
├── paid-media/                     # Publicidad pagada
├── product/                        # Producto
├── project-management/           # Gestión de proyectos
├── sales/                          # Ventas
├── security/                       # Seguridad
├── spatial-computing/            # Computación espacial
├── specialized/                    # Especialistas
├── strategy/                       # Estrategia
├── support/                        # Soporte al cliente
├── testing/                        # Pruebas
├── integrations/                   # Productos de integración multiherramienta
│   ├── openclaw/                   # Workspace de OpenClaw (SOUL.md + AGENTS.md + IDENTITY.md)
│   ├── opencode/                   # Agent de OpenCode (.md + frontmatter YAML)
│   ├── claude-code/                # Subagent de Claude Code
│   ├── cursor/                     # Cursor rule (.mdc)
│   ├── codex/                      # Agent personalizado de Codex (TOML)
│   ├── gemini-cli/                 # Subagent de Gemini CLI
│   ├── github-copilot/             # GitHub Copilot
│   ├── aider/                      # Aider CONVENTIONS.md
│   ├── windsurf/                   # Windsurf .windsurfrules
│   ├── kimi/                       # Kimi Code CLI
│   ├── qwen/                       # Qwen Code SubAgent
│   └── mcp-memory/                 # Memoria persistente MCP
├── scripts/
│   ├── convert.sh                  # Convertidor: definición de roles → formato de herramienta
│   ├── install.sh                  # Instalación en un clic en local
│   ├── lib.sh                      # Funciones compartidas
│   └── lint-agents.sh              # Validación (lint) de definiciones de roles
├── README.md
└── CONTRIBUTING.md

Pasos paso a paso

A continuación, usaremos OpenClaw como ejemplo para demostrar el flujo completo. Para otras herramientas solo tienes que cambiar --tool por el nombre correspondiente.

Paso 1: clonar el repositorio

git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

Si tu red está restringida, primero bifurca (fork) en Gitee / en tu propio GitHub y luego clona:

git clone https://github.com/<your-fork>/agency-agents.git
cd agency-agents

Paso 2: ver qué departamentos y roles se pueden instalar

install.sh ofrece un modo “lista” muy conveniente:

./scripts/install.sh --list teams

Verás una salida parecida a esta:

engineering          33 agents
design               12 agents
marketing            18 agents
security              9 agents
testing              11 agents
...

Si solo quieres instalar algunos departamentos (por ejemplo engineering + security), filtra con --division a continuación.

Paso 3: generar archivos de integración en formato OpenClaw

convert.sh divide el Markdown fuente en el set que espera OpenClaw: SOUL.md (personalidad) + AGENTS.md (proceso) + IDENTITY.md (identidad):

./scripts/convert.sh --tool openclaw

Si se ejecuta correctamente, en el directorio integrations/openclaw/ aparecerán más de 100 subdirectorios:

ls integrations/openclaw/ | head -20
# agency-frontend-developer
# agency-backend-architect
# agency-security-auditor
# agency-reddit-community-ninja
# agency-whimsy-injector
# ...

Cada subdirectorio luce así:

agency-frontend-developer/
├── SOUL.md        # Personalidad del rol: identidad, memoria, tono, estilo
├── AGENTS.md      # Proceso de negocio: mission, deliverables, workflow
└── IDENTITY.md    # Tarjeta de identidad: emoji + nombre + vibe

Paso 4: instalación en OpenClaw con un solo comando

# Instalación completa (aprox. 100+ roles)
./scripts/install.sh --tool openclaw

# Recomendado: elegir por departamentos (evita meter demasiados de golpe)
./scripts/install.sh --tool openclaw --division engineering,security

El script copiará automáticamente el workspace en ~/.openclaw/agency-agents/ y registrará los roles en el gateway de OpenClaw.

Paso 5: reiniciar el gateway de OpenClaw para que surtan efecto los nuevos roles

openclaw gateway restart

Paso 6: activar en OpenClaw el rol Frontend Developer

openclaw chat --agent agency-frontend-developer

O bien, en el archivo de configuración cambia el agent por defecto a agency-frontend-developer; así, al iniciar OpenClaw entrará automáticamente en ese rol.

Paso 7: ejecutar un requerimiento real

Hagamos que el recién activado Frontend Developer escriba un componente de tabla virtualizable accesible:

openclaw chat --agent agency-frontend-developer <<'EOF'
Ayúdame a escribir un componente DataTable usando React 18 + TypeScript con estos requisitos:
1. Usar @tanstack/react-virtual para virtualización
2. Cumplir la especificación de accesibilidad WCAG 2.1 AA
3. Las celdas deben soportar renderizado personalizado
4. El evento de click de fila debe ser configurable
5. Proporciona el código completo listo para ejecutarse
EOF

Te darás cuenta de que el código que produce tiene un estilo muy consistente: porque en la definición del rol ya quedan “fijadas” restricciones como “WCAG 2.1 AA”, “memo envuelve (memo wrapper)” y “optimización Core Web Vitals”. No necesitamos repetir cada vez esas exigencias en el prompt.

Paso 8: demostración entre herramientas (opcional)

Con la misma definición de rol, pasar a Cursor solo requiere una línea para convertir y otra para instalar:

./scripts/convert.sh --tool cursor
./scripts/install.sh --tool cursor --agent frontend-developer,backend-architect

Solución de problemas (FAQ)

Q1: install.sh falla con permission denied

Normalmente es porque install.sh no tiene permisos de ejecución. En macOS / Linux:

chmod +x scripts/install.sh scripts/convert.sh scripts/lib.sh
./scripts/install.sh --tool openclaw

En Windows, si usas Git Bash y te da este error, primero confirma que descargaste el repositorio con git clone (no descomprimas un zip) y ejecuta los scripts con Git Bash.

Q2: OpenClaw muestra “agent not found” o “no registrado”

En el 99% de los casos, después de instalar el rol no reiniciaste el gateway:

openclaw gateway restart
openclaw agent list | grep frontend-developer
# si ves salida, significa que el registro fue correcto

Si aún no funciona, revisa que exista el archivo agency-frontend-developer/SOUL.md dentro de ~/.openclaw/agency-agents/:

ls ~/.openclaw/agency-agents/agency-frontend-developer/
# deberías ver SOUL.md  AGENTS.md  IDENTITY.md

Q3: En OpenCode, tras instalar demasiados roles, solo se muestran los primeros 119

Esto es un bug conocido aguas arriba en OpenCode (issue #27988). En tiempo de ejecución solo se registran alrededor de 119 subagents; los restantes se descartan silenciosamente.

Solución: divide la instalación con --division para mantener el total de roles dentro de 119:

./scripts/install.sh --tool opencode --division engineering
./scripts/install.sh --tool opencode --division marketing --out ~/.opencode-extra/

El script emitirá un warning al detectar que se supera el umbral; también puedes hacer un dry-run primero:

./scripts/install.sh --tool opencode --division engineering --dry-run

Q4: El frontmatter de un rol no tiene campos requeridos y convert.sh lo salta

convert.sh omitirá los archivos fuente que no incluyan el campo name. Si tú hiciste fork de un rol y notas que no aparece en integrations/openclaw/:

# 1. Revisa el frontmatter del archivo fuente
head -10 engineering/your-custom-agent.md

# 2. Debe incluir al menos:
#    ---
#    name: Your Agent Name
#    description: One-line description
#    ---

# 3. Reconvertir
./scripts/convert.sh --tool openclaw

Q5: En Windows, los scripts de bash fallan por los saltos de línea

Si copiaste los scripts desde un zip y los descomprimiste en Windows, los archivos podrían tener saltos de línea CRLF; bash fallará con \r: command not found:

# Opción A: usa git clone en lugar de descargar un zip
git clone https://github.com/msitarzewski/agency-agents.git

# Opción B: convertir manualmente saltos de línea (Git Bash)
dos2unix scripts/*.sh

Q6: Conflictos de personalidad entre roles / “contaminación” de contexto

Si en una misma sesión activas primero Frontend Developer y luego Security Auditor, podrías notar que en el contexto queda el tono del rol anterior. Esto ocurre porque la mayoría de las herramientas CLI inyectan el prompt a nivel “system prompt”: al cambiar de agent, el historial de la conversación no se limpia automáticamente.

Solución:

# antes de cambiar de agent, abre una sesión nueva
openclaw chat --new-session --agent agency-security-auditor

O habilita en la configuración de OpenClaw la opción “archivar automáticamente la conversación anterior al cambiar de agent”.

Lecturas adicionales / direcciones avanzadas

1. Personalizar plantillas de roles

engineering/engineering-frontend-developer.md es un excelente modelo. Intenta bifurcarlo y crear una variante como engineering-frontend-developer-chinese.md:

---
name: Ingeniero frontend (versión en español)
description: Experto en React/Vue, implementación de UI y optimización de rendimiento; entrega comentarios en español
color: cyan
emoji: 🖥️
vibe: Entrega en español, siguiendo la normativa de frontend de ByteDance
---

# Ingeniero frontend (versión en español)

Eres**un ingeniero frontend**, enfocado en tecnologías web modernas……

## 🧠 Tu identidad y tu memoria
- Rol: Experto en aplicaciones web modernas e implementación de UI
- Personalidad: atento al detalle, sensible al rendimiento, prioriza al usuario
- Memoria: recuerda patrones comunes de UI y mejores prácticas de accesibilidad

Luego ejecuta ./scripts/convert.sh --tool openclaw y el nuevo rol aparecerá en integrations/openclaw/.

2. Añadir memoria persistente a los roles usando MCP-Memory

En integrations/mcp-memory/ hay una colección de configuraciones para un servidor MCP memory; al activarlo, los roles pueden conservar preferencias a través de distintas sesiones (por ejemplo: “este equipo prefiere usar pnpm en lugar de npm”). La forma de configurarlo se describe en el mcp-memory/README.md dentro del repositorio.

3. Flujos de trabajo de colaboración con múltiples agentes

Un rol ya es potente, pero lo más emocionante es orquestarlos como una cadena colaborativa. Por ejemplo:

Necesidad → [Product Manager] divide tareas
          → [Frontend Developer] + [Backend Architect] implementan en paralelo
          → [Code Reviewer] hace revisión automática
          → [QA Test Engineer] ejecuta pruebas
          → [Technical Writer] genera la descripción del PR

La función “workflow” incorporada en OpenClaw puede encadenar estos roles; consulta la documentación oficial de OpenClaw para más detalles.

4. Reducir el coste de las llamadas

Antes mencionamos que los roles expertos de Agency Agents funcionan sobre modelos de primer nivel, así que a la larga el coste no es bajo. Si quieres ejecutar los mismos modelos con el precio oficial a mitad de coste, puedes integrar directamente Defapi (la sección “Dependencias clave” anterior tiene explicaciones detalladas): sin cambios de código.

---

Este artículo se ha escrito en base al msitarzewski/agency-agents en su rama main actual (commit a 2026-06-13). Más adelante, el repositorio puede añadir departamentos o ajustar las interfaces de los scripts; se recomienda ejecutar git pull antes de empezar para sincronizar la versión más reciente.