Data Analytics Agents

El punto de entrada unificado para OpenCode, Claude Code, Codex, Antigravity CLI (Agy), Pi Coding Agent (pi) y MiniMax Code (mcode). Este archivo se auto-descubre en la raíz del proyecto, así que cualquier CLI que se lance desde este directorio toma las personas de abajo como contexto.

Inicio rápido — para registrar las 5 personas como agentes reales en OpenCode (y como agentes/skills project-local en Claude Code, Codex, Agy, Pi y mcode), corré estos dos pasos desde el directorio del proyecto de data analytics destino:

# 1. Instalá el toolkit como dev dependency (deja el paquete en node_modules/):
npm install --save-dev data-analytics-agents

# 2. Corré el instalador (registra agents + skills en los 5 CLIs):
npx data-analytics-agents install --all

Alternativas:

# Vía skills.sh (solo skills, sin agents):
npx skills add berriosb/data-analytics-agents

# Vía clone directo (alternativa sin npm):
git clone https://github.com/berriosb/data-analytics-agents.git
cd data-analytics-agents && make install-all

Por qué dos pasos en el flujo npm: npm install deja el toolkit en node_modules/data-analytics-agents/ (persistente). El instalador crea los symlinks hacia ahí, así no se rompen cuando npm limpia el cache de npx. Un solo comando, idempotente, usa symlinks así que agents/*.md y skills/*/ siguen siendo la única fuente de verdad. Destinos:

CLI	Qué se instala
OpenCode	.opencode/agents/<name>.md + .opencode/skills/<name>
Claude Code	.claude/agents/<name>.md + .claude/skills/<name>
Codex	.agents/skills/<name> (Codex lee los agentes desde AGENTS.md)
Antigravity	.agents/agents/<name>.md + .agents/skills/<name> (o global en ~/.gemini/config/)
Pi	.pi/agents/<name>.md + .pi/skills/<name> (y auto-descubre .agents/skills/)
MiniMax Code	.agents/skills/<name> (mcode lee los agentes desde AGENTS.md)

Mapa de la arquitectura

Para el mapa mental de cómo se conectan las 5 personas y las 24 skills, el flujo de triaje y los handoffs entre especialistas, ver docs/architecture.md. Leelo si es tu primera vez en el repo o si vas a proponer un cambio que toca más de una skill — el resto de la documentación (ADRs, PRDs, este archivo) asume que entendés ese mapa.

Por qué este archivo solo no alcanza

AGENTS.md se carga como contexto por cada CLI desde el cwd — así que el patrón "act as <persona>" funciona en todos lados. Pero OpenCode, Claude Code y Codex también mantienen un registro separado de agentes que se pueden invocar con --agent <name>. Esos registros buscan archivos en rutas específicas por CLI (.opencode/agents/, .claude/agents/, etc.), y no leen AGENTS.md.

bin/install.js cierra esa brecha haciendo symlinks de agents/*.md y skills/*/ a la ubicación esperada por cada CLI. Sin él:

• OpenCode: solo los 7 agentes default están registrados; las 5 personas son invisibles para opencode agent list y --agent <name>.
• Claude Code: los agentes se cargan desde AGENTS.md pero solo como contexto; el .claude/agents/ project-local queda vacío.
• Codex: igual que Claude — los agentes vienen solo de AGENTS.md.

La arquitectura anterior basada en instalación (symlinks a ~/.config/opencode/agent/, ~/.claude/agents/, etc.) fue abandonada en favor de este diseño más simple: un AGENTS.md por proyecto, un bin/install.js para registrar agentes project-local, un ~/.agents/skills/ por usuario para skills globales.

Arquitectura (por qué las skills viven arriba, no dentro de los agentes)

Las skills son top-level (skills/<name>/SKILL.md) y referenciadas por los agentes por nombre, no anidadas dentro de cada agente. Cada agente declara qué skills carga en el paso 1 de su Flujo de trabajo:

Esto es intencional, no un descuido:

• Reusabilidad: csv-profiler podría ser cargada legítimamente por un futuro agente sin arrastrar pandas-cleaning. Skills top-level evitan el acoplamiento accidental.
• Fuente única de verdad: editar skills/csv-profiler/SKILL.md actualiza el archivo usado por todos los agentes y cualquier script futuro (make test-csv) sin recorrer carpetas de agentes.
• Un archivo = un trabajo: el archivo de un agente se queda enfocado en persona y workflow; el de una skill se queda enfocado en las recetas. Mezclarlos tiende a hinchar ambos.

Si necesitás notas privadas por agente (p. ej. un data-explorer.notes.md que no sea parte del registro público de skills), ponelas al lado del archivo del agente — no contamines el namespace compartido de skills/.

Personas disponibles

Invocá cualquier persona con act as <name> (funciona en los cuatro CLIs). Los prompts detallados viven en agents/<name>.md — la mayoría de los CLIs leen el archivo relevante cuando les pedís actuar como esa persona.

Cuándo usar cuál

• Pedido nuevo, ambiguo: arrancar con using-data-analytics-agents para enrutamiento.
• Hay un CSV / Parquet / Excel sin DB: data-explorer.
• Hay una SQLite / SQL DB / archivo SQL: sql-analyst.
• Ya hay números agregados o un dataframe limpio: reporting-analyst.
• Hay features + target definido, quiere predecir: ml-modeler.

Skills

Cada skill vive en skills/<name>/SKILL.md con frontmatter name + description. Una vez que la skill está symlinkeada a ~/.agents/skills/<name>/ (setup único, ver "Instalación opcional" abajo), los cuatro CLIs la auto-descubren y la cargan a demanda según las palabras trigger de la description.

schema-mapper se carga antes de sql-query-helper (que provee idiomas para escribir consultas); schema-mapper cubre el paso de descubrimiento que produce el diccionario de datos y los join paths sobre los que se apoya el escritor. query-validation se carga después de sql-query-helper para cubrir el pase de revisión antes de que la consulta salga. Por último, insight-synthesis se carga después de viz-patterns para conectar gráficos → insights priorizados.

statistical-testing es opcional en ambos flujos (no es siempre necesaria). En data-explorer se carga después de pandas-cleaning porque presupone datos limpios; en reporting-analyst se carga entre viz-patterns y insight-synthesis cuando un hallazgo visual necesita un número de p-value / tamaño de efecto para no quedar como "se ve más alto". data-explorer también la puede cargar para responder preguntas analíticas del estilo "¿es la diferencia significativa?" antes de pasar el control a reporting-analyst.

time-series-patterns sigue el mismo patrón: opcional, se carga después de pandas-cleaning cuando hay una dimensión temporal explícita en el dataset y la pregunta es de tendencia / estacionalidad / forecast a corto plazo. En reporting-analyst se usa para producir descomposiciones y overlays de rolling stats antes de la narrativa. Cubre el hueco que statistical-testing deja fuera explícitamente (autocorrelación: los tests paramétricos asumen independencia y dan p-values falsos sobre series con autocorrelación).

feature-engineering → ml-modeling → model-evaluation forman la cadena de ML v2 para ml-modeler. El orden importa: el split es sagrado (primero, antes de cualquier fit), después encoding y escalado (fit solo en train), después modelos, después evaluación sobre el test set sagrado una sola vez. insight-synthesis se aplica al final si el modelo genera decisiones; reporting-analyst se invoca después para producir los gráficos (matriz de confusión, ROC, learning curve, feature importances).

Ejemplos de invocación por CLI

Todos los CLIs son agnósticos al modelo. Elegí el modelo al momento de la invocación. Corré make install-all antes así cada CLI ve a las personas como agentes registrados reales (no solo contexto vía AGENTS.md).

Codex

cd ~/Proyectos/data-analytics
make install-all   # única vez, registra las personas para OpenCode + Claude + Codex + Agy

# Flag --agent (después de instalar)
codex -m gpt-5.5 --agent data-explorer exec "Profileá examples/ventas_sample.csv y pará."

# o vía act-as en el prompt (funciona sin instalar también)
codex -m gpt-5.5 exec "act as data-explorer. Profileá examples/ventas_sample.csv y pará."
codex -m gpt-5.5 exec "act as sql-analyst. En examples/notes_example.sqlite, dame el top 5 de clientes por revenue."
codex -m gpt-5.5 exec "act as reporting-analyst. Tendencia mensual de revenue, últimos 90 días, salida a ./reports/."

OpenCode

cd ~/Proyectos/data-analytics
make install-all

# Flag --agent (después de instalar) — registra la persona de forma nativa
opencode -m minimax-coding-plan/MiniMax-M3 --agent data-explorer "Profileá examples/ventas_sample.csv y pará."
opencode -m gemini-3.6-flash --agent sql-analyst "Top 5 de clientes por revenue desde examples/notes_example.sqlite."
opencode -m minimax-coding-plan/MiniMax-M3 --agent reporting-analyst "Tendencia mensual de revenue, salida a ./reports/."

# o vía act-as en el prompt
opencode -m minimax-coding-plan/MiniMax-M3 "act as data-explorer. Profileá examples/ventas_sample.csv y pará."

Verificar con: opencode agent list — debería incluir data-explorer, sql-analyst, reporting-analyst, using-data-analytics-agents.

Claude Code

cd ~/Proyectos/data-analytics
make install-all

claude -m opus --agent data-explorer "Profileá examples/ventas_sample.csv y pará."
claude -m opus --agent sql-analyst "Top 5 de clientes por revenue desde examples/notes_example.sqlite."
claude -m opus --agent reporting-analyst "Tendencia mensual de revenue, salida a ./reports/."

Antigravity CLI (agy)

cd ~/Proyectos/data-analytics
make install-all   # registra personas y skills para los 5 CLIs (incluyendo Antigravity y Pi)

agy -m gemini-3.6-flash --agent data-explorer "Profileá examples/ventas_sample.csv y pará."
agy -m "Claude Opus 4.6 (Thinking)" --agent sql-analyst "Top 5 de clientes por revenue."
agy -m gemini-3.6-flash --agent reporting-analyst "Tendencia mensual de revenue, salida a ./reports/."

Pi Coding Agent (pi)

cd ~/Proyectos/data-analytics
make install-all   # registra personas y skills para los 5 CLIs (incluyendo Pi)

pi "act as data-explorer. Profileá examples/ventas_sample.csv y pará."
pi "act as sql-analyst. En examples/notes_example.sqlite, dame el top 5 de clientes por revenue."
pi "act as reporting-analyst. Tendencia mensual de revenue, salida a ./reports/."

MiniMax Code (mcode)

cd ~/Proyectos/data-analytics
make install-all   # skills disponibles en .agents/skills/

# En TUI o headless vía exec:
mcode "act as data-explorer. Profileá examples/ventas_sample.csv y pará."
mcode "act as sql-analyst. En examples/notes_example.sqlite, dame el top 5 de clientes por revenue."
mcode "act as reporting-analyst. Tendencia mensual de revenue, salida a ./reports/."

Por qué "act as" funciona en cada CLI

Cada CLI soportado auto-descubre un AGENTS.md a nivel de proyecto (o CLAUDE.md / GEMINI.md) y lo agrega al system prompt. Entonces cuando escribís "act as data-explorer", el agente tiene la definición de la persona en contexto y se auto-organiza alrededor de ella. Los archivos markdown detallados de las personas en agents/<name>.md son la fuente de verdad para ese rol; si algún agente se siente poco instruido, pedile al CLI que @agents/data-explorer.md (o directamente que lea el archivo con sus tools).

Instalación: Project-local vs Global

Por defecto, la instalación es 100% project-local:

make install-all   # o: npx data-analytics-agents install --all

Esto crea los symlinks exclusivamente dentro de la raíz del proyecto destino (.opencode/, .claude/, .agents/, .pi/). Tus otros proyectos (desarrollo web, APIs, scripts de sistema) no ven ni cargan agentes ni skills de data analytics.

Solo si explícitamente quisieras tener las skills de data analytics disponibles en todos tus proyectos a nivel de usuario, podés instalar a nivel global:

make install-skills   # global: symlinks a ~/.agents/skills/

Soporte de Antigravity (Agy)

Antigravity auto-descubre las skills en .agents/skills/ y los agentes en .agents/agents/*.md a nivel project-local (o en ~/.gemini/config/agents/ si se instala con --global). bin/install.js install --agy (o make install-agy / make install-all) crea los symlinks en .agents/agents/ y .agents/skills/.

Después de esto:

• agy agent lista las 5 personas disponibles.
• agy --agent <name> permite correr sesiones directamente con cualquier persona.
• Ambos estilos ("act as" en el prompt y --agent <name>) funcionan en simultáneo.

Soporte de Pi (pi)

Pi auto-descubre AGENTS.md en la raíz del proyecto para contexto de personas y las 24 skills en .agents/skills/ o ~/.agents/skills/ (conforme a la especificación Agent Skills).

Para entornos con la extensión de subagentes (gentle-pi), bin/install.js install --pi (o make install-pi / make install-all) genera además los symlinks en .pi/agents/*.md y .pi/skills/.

Qué hace bin/install.js

bin/install.js (también expuesto como el bin data-analytics-agents vía package.json) es el instalador project-local. Solo crea symlinks — nunca copia — así que agents/*.md y skills/*/ siguen siendo la fuente única de verdad.

node ./bin/install.js install --opencode   # → .opencode/agents/ + .opencode/skills/
node ./bin/install.js install --claude     # → .claude/agents/ + .claude/skills/
node ./bin/install.js install --codex      # → .agents/skills/
node ./bin/install.js install --agy        # → .agents/agents/ + .agents/skills/
node ./bin/install.js install --pi         # → .pi/agents/ + .pi/skills/
node ./bin/install.js install --all        # los 5 CLIs a la vez
node ./bin/install.js install --auto       # solo para CLIs cuyo binario esté en PATH
node ./bin/install.js list                 # muestra el estado actual
node ./bin/install.js uninstall --all     # elimina todo lo que enlazamos

Tras publicar el paquete a npm, los mismos comandos funcionan como npx data-analytics-agents install --opencode desde cualquier proyecto.

Qué reemplaza esto

Las revisiones anteriores de este proyecto symlinkeaban las personas al directorio de configuración privado de cada CLI (~/.config/opencode/agent/, ~/.claude/agents/, plugins de Agy). Eso hacía make install obligatorio y editar agents/<name>.md requería un make refresh.

El diseño actual mantiene el enfoque de symlinks (así las ediciones son live) pero reemplaza la instalación manual per-CLI por un único CLI bin/install.js que maneja los 4 CLIs (make install-all). Editar agents/<name>.md o skills/<name>/SKILL.md sigue tomándose de inmediato — sin re-instalar.

Para limpiar los symlinks legacy (si existen de instalaciones aún más viejas):

make cleanup-legacy   # elimina los symlinks viejos por CLI, deja ~/.agents/skills/ intacto