Skills: cómo inyectar expertise en agentes IA para empresas LATAM

Expertise requerido:
1. Reconocer clientes por razón social, NIT o apodo (no siempre vienen con nombre oficial)
2. Calcular deuda actual = saldo_inicial + intereses_UDVS - pagos_recibidos
3. Determinar si es "cliente moroso nivel 3" (>90 días) y aplicar protocolo especial
4. Sugerir estrategia de cobro por perfil (vía WhatsApp, email, teléfono, gestor legal)
5. Generar acta de negociación con firma y fecha (formato Cámara de Comercio)

{
  #43a047">"name": "calificar-cliente-moroso",
  #43a047">"description": "Determina nivel de morosidad (PAGADOR, MOROSO_15, MOROSO_60, MOROSO_90_PLUS) según saldo y días vencidos",
  #43a047">"inputs": {
    #43a047">"nombre_cliente": "string",
    #43a047">"saldo_deuda": "number (COP)",
    #43a047">"fecha_ultimo_pago": "ISO 8601 date",
    #43a047">"zona_horaria": "America/Bogota (enum)"
  },
  #43a047">"outputs": {
    #43a047">"nivel": "enum: PAGADOR | MOROSO_15 | MOROSO_60 | MOROSO_90_PLUS",
    #43a047">"dias_vencidos": "number",
    #43a047">"protocolo_sugerido": "string (WhatsApp/Email/Legal/Acuerdo)",
    #43a047">"reasoning": "string (por qué esta clasificación)"
  },
  #43a047">"examples": [
    {
      #43a047">"input": { "nombre_cliente": "Droguerías La Paz", "saldo_deuda": 5000000, "fecha_ultimo_pago": "2026-09-01", "zona_horaria": "America/Bogota" },
      #43a047">"output": { "nivel": "MOROSO_90_PLUS", "dias_vencidos": 51, "protocolo_sugerido": "Legal", "reasoning": "Supera 90 días en zona horaria oficial" }
    }
  ]
}

function calificarClienteMoroso(input: {
  nombre_cliente: string;
  saldo_deuda: number;
  fecha_ultimo_pago: string;
  zona_horaria: string;
}): object {
  const fechaUltimoPago = new Date(input.fecha_ultimo_pago);
  const hoy = new Date();
  const diasVencidos = Math.floor((hoy.getTime() - fechaUltimoPago.getTime()) / (1000 * 3600 * 24));

  let nivel, protocolo;
  
  if (diasVencidos <= 15) {
    nivel = #43a047">"MOROSO_15";
    protocolo = #43a047">"WhatsApp";
  } else if (diasVencidos <= 60) {
    nivel = #43a047">"MOROSO_60";
    protocolo = #43a047">"Email + WhatsApp";
  } else if (diasVencidos >= 90) {
    nivel = #43a047">"MOROSO_90_PLUS";
    protocolo = #43a047">"Legal";
  } else {
    nivel = #43a047">"PAGADOR";
    protocolo = #43a047">"Mantener";
  }

  return {
    nivel,
    dias_vencidos: diasVencidos,
    protocolo_sugerido: protocolo,
    reasoning: #43a047">`Cliente ${input.nombre_cliente} tiene ${diasVencidos} días vencidos con deuda de ${input.saldo_deuda} COP. Clasificado como ${nivel}.`
  };
}

async function sugerirEstrategiaCobranza(input: {
  cliente_json: string; // JSON con histórico del cliente
  intento_anterior: string; // qué pasó la última vez
}) {
  const prompt = #43a047">`
Eres experto en cobranza LATAM. Analiza este cliente:
${input.cliente_json}

Último intento: ${input.intento_anterior}

Basándote en:
- Perfil del cliente (sector, tamaño, historial de pagos)
- Protocolos de nuestra empresa (ver: /docs/protocolos-cobranza.md)
- Mejores prácticas LATAM (relaciones, sensibilidad cultural, legal)

Sugiere:
1. Próximo canal de contacto (WhatsApp, email, teléfono, abogado)
2. Mensaje inicial (en tono profesional, sin amenaza)
3. Oferta de arreglo si es viable (plazo sugerido, descuento %)
4. Riesgo legal (sí/no, breve explicación)

Responde en JSON.
  `;

  const response = await anthropic.messages.create({
    model: #43a047">"claude-3-5-sonnet-20241022",
    max_tokens: 500,
    messages: [{ role: #43a047">"user", content: prompt }]
  });

  return JSON.parse(response.content[0].text);
}

async function consultarClienteEnCRM(input: { nit: string }) {
  const query = #43a047">`
    SELECT 
      nombre, sector, saldo_actual, fecha_ultimo_pago, intentos_contacto,
      notas_especiales
    FROM clientes
    WHERE nit = $1;
  `;
  
  const result = await db.query(query, [input.nit]);
  
  if (result.rows.length === 0) {
    return { existe: false, razon: #43a047">"NIT no encontrado" };
  }
  
  const cliente = result.rows[0];
  return {
    existe: true,
    cliente: {
      nombre: cliente.nombre,
      sector: cliente.sector,
      saldo: cliente.saldo_actual,
      dias_sin_pago: Math.floor((Date.now() - new Date(cliente.fecha_ultimo_pago)) / (1000 * 86400)),
      notas: cliente.notas_especiales
    }
  };
}

{
  #43a047">"agent": {
    #43a047">"name": "Agente Cobranza LATAM",
    #43a047">"model": "claude-3-5-sonnet",
    #43a047">"skills": [
      {
        #43a047">"name": "calificar-cliente-moroso",
        #43a047">"endpoint": "POST https://api.tu-empresa.com/skills/calificar-moroso",
        #43a047">"timeout_ms": 1000,
        #43a047">"retry": 2
      },
      {
        #43a047">"name": "consultar-crm",
        #43a047">"endpoint": "POST https://api.tu-empresa.com/skills/consultar-crm",
        #43a047">"timeout_ms": 2000
      },
      {
        #43a047">"name": "sugerir-estrategia",
        #43a047">"endpoint": "POST https://api.tu-empresa.com/skills/estrategia",
        #43a047">"timeout_ms": 8000
      }
    ]
  }
}

# Test 1: Cliente pagador (caso feliz)
curl -X POST https://api.tu-empresa.com/skills/calificar-moroso \
  -d '{
    #43a047">"nombre_cliente": "Tech Solutions SAS",
    #43a047">"saldo_deuda": 0,
    #43a047">"fecha_ultimo_pago": "2026-10-20",
    #43a047">"zona_horaria": "America/Bogota"
  }'

# Response esperado: nivel=PAGADOR, protocolo=Mantener

# Test 2: Cliente moroso 90+ (caso crítico)
curl -X POST https://api.tu-empresa.com/skills/calificar-moroso \
  -d '{
    #43a047">"nombre_cliente": "Distribuidora Antigua",
    #43a047">"saldo_deuda": 50000000,
    #43a047">"fecha_ultimo_pago": "2026-07-01",
    #43a047">"zona_horaria": "America/Lima"
  }'

# Response esperado: nivel=MOROSO_90_PLUS, protocolo=Legal

# Skill: Calificar Cliente Moroso

## Qué hace
Clasifica clientes por nivel de morosidad según días vencidos.

## Cuándo usarlo
En el agente de cobranza, antes de elegir estrategia de contacto.

## Inputs y outputs
[aquí el contrato JSON del Paso 2]

## Casos de prueba
[aquí los 5+ tests del Paso 5]

## Mantenimiento
- Última actualización: 2026-10-22
- Propietario: Demian Olmedo
- En producción desde: 2026-10-15
- Cambios conocidos: Se agregó validación de zona horaria (2026-10-20)

Usuario (WhatsApp/email/dashboard)
         |
         v
      Agente (Claude Sonnet)
         |
    +----+----+----+
    |    |    |    |
   Skill1 Skill2 Skill3 ... SkillN
    |    |    |    |
    v    v    v    v
  BD   APIs  Logs  Webhooks (tu empresa)