​

08 — El sistema de skills de Ada

​

1. Qué es un skill de Ada

apps/api/src/luna/skills/<nombre>/
├── SKILL.md            # obligatorio: frontmatter + receta (≤ 2 500 caracteres de cuerpo)
└── references/         # opcional: profundidad que se carga solo si el turno la pide

​

Frontmatter (contrato)

---
name: quien-le-ha-vendido
description: Averigua quién le ha vendido un producto o servicio a un comprador público y con qué recurrencia. Úsalo cuando la persona pregunte "quién le vende a", "quién ganó", "quién es el proveedor de", "adjudicaciones de", o nombre a una dependencia y un producto. No lo uses para buscar proveedores en general (eso es buscar-empresas-y-proveedores).
metadata:
  version: 1.0.0
  reasoning: bajo            # bajo | medio — cuánto razonamiento pide el turno
  tools: [market_search_awards, market_get_supplier_history, market_aggregate_awards, market_search_suppliers]
  cierra_con: lista           # lista | conteo | pipeline | cuenta | secuencia | contexto | analisis | ninguna
---

• description lleva qué hace + cuándo dispara + cuándo no, con las frases que la gente dice en español mexicano. Es el nivel 1 de disclosure y lo único que el modelo ve de los skills que no abrió.
• tools es la lista blanca del turno: el cinturón se recorta a esas herramientas más las de sesión (board_read). Menos catálogo, menos tokens, menos herramienta equivocada.
• reasoning decide el esfuerzo de razonamiento del turno (§7.1).
• cierra_con declara la tarjeta que el turno debe producir cuando exista el doc 07; hasta entonces, la forma de la narración.

​

Cuerpo (plantilla fija)

# Quién le ha vendido

## Antes de empezar
Qué del estado del turno importa (tablero, resumen del workspace, criterio dicho).

## Pasos
1. Paso → herramienta y argumentos. Qué esperas ver.
2. Si el paso 1 trae 0 filas → plan B concreto (quitar estado, sinónimos, cambiar de dominio).
3. …
Cada paso dice qué hacer con cero filas. Un skill sin plan B no se acepta.

## Cómo cierras
Intent, forma de la respuesta, qué NO decir. Una frase de lectura y la tarjeta.

## Ejemplo
Pregunta → llamadas en orden → respuesta.

## Errores frecuentes
`query_not_selective` → causa → corrección. `Collection not found` → causa → corrección.

​

2. Los tres niveles de disclosure, en el presupuesto de Ada

​

3. El router: cómo se dispara un skill

1. Pre-router determinista (servidor, antes de la primera llamada al modelo). Lee el mensaje, la etapa y el tablero, igual que criterionFromMessage ya lee estado y giro. Reglas por skill: frases gatillo y frases de exclusión de la description, más señales de estado (hay selección → guardar-en-crm sube; hay decisión pendiente → nada nuevo). Devuelve hasta 2 candidatos con confianza. Cubre la mayoría de los turnos a costo cero.
2. Autoselección del modelo (con razonamiento encendido). El índice está en el manual; si el pre-router no eligió o eligió mal, el modelo llama skill_open { name } y recibe el cuerpo como resultado de herramienta. Si abre una reference, llama skill_reference { skill, ref }.

​

4. El catálogo v1 (diez recetas)

​

5. Cómo se prueba cada skill

1. Disparo. Por skill, 10 mensajes que deben dispararlo y 10 que no, escritos como habla la gente (con typos, sin nombrar el producto, casos vecinos: “cuántos” contra “búscame”). Medidor nuevo: skill_trigger = disparó el correcto / no disparó uno ajeno. Meta de la guía: 90 %.
2. Funcional. Los 20 briefs actuales más 2 por skill nuevo, con expect.skill y expect.must_deliver (“una lista con al menos una fila, o la cobertura consultada y por qué 0”). Medidor nuevo: utilidad, un juez modelo con rúbrica de tres puntos (respondió lo que se pidió / dio salidas concretas / no inventó). Es el medidor que hoy no existe y que hubiera atrapado “tu CRM no existe”.
3. Baseline. Cada brief corre con skill y sin skill (el manual ya tiene el brazo “sin skill” en luna-manual.ts:690). Se reporta delta de utilidad, herramientas por turno, costo y p50. Un skill que no mejora utilidad no se mergea.

​

6. Versionado y gobierno

• metadata.version en el frontmatter; se estampa en diagnostics.skills_used de cada turno, como hoy se estampa MARKET_INVESTIGATION_SKILL_VERSION en los reportes.
• Los skills son código: entran por PR con su bench. No se editan desde el dashboard en v1.
• Personalización por workspace sin tocar el skill: el skill lee el playbook del equipo por context_retrieve (ya existe el tema senales-de-compra y los criterios de colección). El skill es la receta; Cerebro pone los ingredientes del cliente.

​

7. Prerrequisitos (los otros cuatro puntos del diagnóstico)

1. Razonamiento encendido. mastra-model.adapter.ts:323 apaga el razonamiento siempre que el modelo lo permite. Cambio: el skill activo decide (metadata.reasoning), default bajo; medio para análisis y cierre. Medir p50 y costo antes y después en los 20 briefs.
2. El workspace en el prompt. Un párrafo compilado y cacheado (TTL 60 s) en luna-input.compiler.ts: colecciones con conteos por etapa, secuencias y su estado, buzón, saldo de contactos. ~300 caracteres. Adiós al redescubrimiento.
3. Intents reordenados. responder y cierre antes que limite; limite solo cuando un paso del skill lo declara. Hoy “el primero que aplica gana” y limite es el primero.
4. Payload limpio. Las tres advertencias fijas de mercado y el next_action salen del texto que ve el modelo (luna-mcp-tools.ts los quita al proyectar); vuelven como pie de tarjeta cuando exista el doc 07.
5. Argumentos persistidos. tool.finished guarda args; board.runs deja de estar vacío. Sin esto no hay “muéstramelos hereda filtros” ni depuración del 32 contra 13.

​

8. Orden de trabajo

• PR 1 (2 días): prerrequisitos 1, 2, 3, 5. Bench antes y después.
• PR 2 (3 días): el loader de skills, el router de dos etapas, skill_open / skill_reference, el índice en el manual, y tres skills: como-va-mi-pipeline, quien-le-ha-vendido, cuantos-hay + buscar-empresas-y-proveedores (van juntos). Con sus 20 mensajes de disparo cada uno y el medidor de utilidad.
• PR 3 (3 días): los otros seis skills. Payload limpio. TOOL_ROUTING y CRM_RULES salen del manual.
• Después: doc 07, tarjetas.

1. “¿Quién le ha vendido uniformes al IMSS en los últimos dos años?” → debe cerrar con una lista de proveedores con montos anclados, o con “0 en la cobertura consultada” y los candidatos por texto marcados como candidatos.
2. “Dame un análisis de mi CRM” → 40 registros, 3 etapas, las 5 más recientes, una recomendación. Nunca “no existe”.
3. “¿Cuántos proveedores de bombas hidráulicas hay? … Muéstramelos” → conteo con filtros visibles, lista con los mismos filtros.

​

9. Decisiones que necesita el fundador

1. Diez skills problem-first (por pregunta), no por familia de herramienta. Sí/no.
2. Router de dos etapas (determinista + autoselección del modelo). Sí/no, o solo una de las dos.
3. El medidor de utilidad con juez modelo como gate de merge para cada skill. Sí/no.
4. Orden: prerrequisitos primero (PR 1), luego tres skills (PR 2). O los tres skills primero para ver el efecto antes.

​

10. Orquestación: “50 personas de distintas empresas para una campaña”

1. Un Plan en el tablero. board.plan { objetivo, pasos[{skill, status, conteo, checkpoint?}], run_id }. Sobrevive turnos y sesiones. “Sigue con la campaña” retoma donde quedó. Hoy el tablero tiene selección, guardado y pendientes; no tiene proceso.
2. La tarjeta de proceso en el hilo. Los pasos con su estado (pendiente, corriendo, listo, esperando tu toque), los conteos (“38 de 50 cuentas con persona elegida”), y las tarjetas de decisión existentes incrustadas en el paso que las necesita. Es el componente más importante del chat, antes que las tarjetas de resultado del doc 07. Precedente: InvestigationLane ya pinta un trabajo largo con progreso.
3. Pasos en segundo plano. Un paso que excede el turno (los 50 people_search) corre como trabajo del servidor y emite run.progress (el evento ya existe en el contrato; la rama del cliente en lunaRuntime.ts:362 está vacía). El turno cierra con “lo estoy haciendo, te aviso”; el hilo se actualiza solo.
4. La receta orquestadora. campana no llama herramientas: compone recetas, escribe el plan, decide qué paso sigue, y sabe parar en cada checkpoint pagado. Es el único skill que abre otros skills.
5. Dos topes de producto que hay que subir: borradores de secuencia de 5 a 50 contactos (o lote), y paginación en company_search.

• PR 1 prerrequisitos (razonamiento, workspace en el prompt, intents, argumentos).
• PR 2 sistema de skills + tres recetas.
• PR 3 Plan + tarjeta de proceso + pasos en segundo plano + receta campana, y los dos topes. Aquí Ada ya arma la campaña de 50 de punta a punta, con la UI mostrando el avance.
• PR 4 las seis recetas restantes + tarjetas de resultado (doc 07), que ahora se incrustan en la tarjeta de proceso.

​

11. Conducta: proactiva, pregunta cuando hace falta, consciente del saldo y de sus límites

6. El validador distingue pregunta legítima de pregunta perezosa. Hoy la regla pregunta bloquea preguntar por un dato que ya está en el libro de hechos; eso se queda. Lo que cambia: cuando el skill activo declara un requerido ausente, preguntar por él no cuenta como defecto. Sin esto, cualquier receta que pida aclarar muere en el gate.
7. Los tres saldos entran al estado compilado y la escalera los usa: gratis se hace, con costo se propone con número, sin saldo se propone el lote que cabe. usage deja de ser algo que Ada tiene que recordar llamar.