Skills

Resumen

Un skill es una capacidad externa que un modelo de lenguaje puede invocar durante la inferencia. No es texto generado. Es una llamada estructurada a una función real: consultar una base de datos, enviar un correo, crear un ticket, leer un archivo, llamar otra API. El modelo decide cuándo usar un skill, con qué argumentos, y luego recibe el resultado para continuar razonando.

Importa porque los LLMs no pueden actuar fuera de su ventana de contexto. Sin skills, toda interacción con el mundo exterior depende de código externo que decide por el modelo. Con skills, el modelo participa en la decisión: sabe qué herramientas tiene disponibles, elige cuál usar y procesa el resultado. Esto habilita agentes, asistentes operativos y flujos que combinan razonamiento con acción.

Alcance y supuestos

Este paquete cubre skills a nivel conceptual: definición de herramientas, esquemas, descripciones, flujo de invocación, procesamiento de resultados, manejo de errores y diseño de herramientas seguras y acotadas.

No cubre implementación específica de SDKs, protocolos de descubrimiento multi-agente, sandboxing de ejecución ni hardening de seguridad. Asume que entiendes LLMs, inferencia, prompts y cómo un agente orquesta múltiples llamadas al modelo.

Modelo mental

Piensa en un chef con un juego de cuchillos. El chef puede describir cómo cortar, pero no puede cortar sin un cuchillo. Un skill es ese cuchillo: una herramienta concreta que hace una cosa específica. El chef elige cuál usar según la tarea, lo agarra con cuidado, ejecuta el corte y vuelve a la tabla.

Un LLM sin skills es un chef sin utensilios. Puede hablar de cocina, pero no puede picar una cebolla ni verificar la temperatura del horno. Con skills, el modelo extiende sus capacidades más allá del texto. Pero cada skill debe ser pequeño, predecible y seguro: un cuchillo afilado de chef, no una navaja suiza con 50 funciones impredecibles.

El flujo típico es: el modelo recibe un prompt, evalúa si necesita datos o acciones externas, elige un skill, produce una llamada estructurada con argumentos, el sistema ejecuta esa llamada, el resultado se inyecta en el contexto, y el modelo continúa. Este ciclo puede repetirse varias veces en un agente.

La diferencia con RAG es importante: RAG recupera documentos antes de la generación; un skill se invoca durante la generación, cuando el modelo decide que necesita consultar o actuar.

Uso práctico

Usa skills cuando el LLM necesita interactuar con sistemas reales, no solo generar texto:

• ✅ Consultar estado de pedidos, disponibilidad de inventario o datos de cliente en tiempo real.
• ✅ Ejecutar acciones acotadas: crear ticket, enviar notificación, actualizar un campo, programar una tarea.
• ✅ Delegar cálculo determinístico: validar formato, aplicar reglas de negocio, transformar datos con lógica exacta.
• ✅ Encapsular operaciones peligrosas detrás de una interfaz controlada en vez de dar acceso crudo.
• ❌ No uses skills para reemplazar RAG cuando solo necesitas contexto estático; recuperar documentos es más simple y barato.
• ❌ No diseñes un skill que haga "lo que el modelo pida"; cada skill debe tener una firma y alcance fijo.

Ejemplo trabajado: definir y llamar skills para un asistente de pedidos

Supón que un asistente debe ayudar con pedidos: consultar estado, verificar disponibilidad y cancelar si aplica. Sin skills, cada acción la decide código externo adivinando la intención. Con skills, el modelo participa:

type Skill = {
  name: string;
  description: string;
  parameters: Record<string, { type: string; description: string; required?: boolean }>;
};

const skills: Skill[] = [
  {
    name: "getOrderStatus",
    description: "Devuelve el estado actual de un pedido por su ID.",
    parameters: {
      orderId: { type: "string", description: "ID del pedido", required: true },
    },
  },
  {
    name: "checkProductAvailability",
    description: "Verifica si un producto tiene stock disponible.",
    parameters: {
      productId: { type: "string", description: "ID del producto", required: true },
      quantity: { type: "number", description: "Cantidad deseada", required: true },
    },
  },
  {
    name: "cancelOrder",
    description: "Cancela un pedido si está en estado pendiente. No puede cancelar pedidos ya enviados.",
    parameters: {
      orderId: { type: "string", description: "ID del pedido", required: true },
      reason: { type: "string", description: "Motivo de cancelación", required: true },
    },
  },
];

Cada skill tiene nombre, descripción y parámetros tipados. La descripción es crucial: el modelo decide qué skill usar basándose en ella. Si escribes "hace cosas con pedidos", el modelo adivinará mal.

El flujo de llamada se modela así:

type SkillCall = {
  name: string;
  arguments: Record<string, unknown>;
};

type SkillResult = {
  name: string;
  output: unknown;
  error?: string;
};

async function executeSkill(call: SkillCall): Promise<SkillResult> {
  const impl = skillImplementations[call.name];
  if (!impl) return { name: call.name, output: null, error: `Unknown skill: ${call.name}` };

  try {
    const output = await impl(call.arguments);
    return { name: call.name, output };
  } catch (err) {
    return { name: call.name, output: null, error: String(err) };
  }
}

El ciclo inference → skill call → result → inference es lo que convierte un chatbot en un asistente operable.

Diseñar un buen skill requiere cinco decisiones:

1. ¿Qué hace exactamente este skill? Una acción, un dato, una validación — no una mezcla.
2. ¿Qué parámetros necesita y cuáles son obligatorios vs. opcionales?
3. ¿Qué descripción usará el modelo para decidir si este skill es el correcto?
4. ¿Qué pasa si el skill falla? ¿El modelo recibe el error y puede recuperarse?
5. ¿Qué permisos tiene este skill? ¿Puede cualquiera cancelar cualquier pedido?

Evidencia

• OpenAI API, Function calling describe tool calling como una conversación multi-paso entre la aplicación y el modelo, donde el modelo decide cuándo invocar funciones externas con argumentos estructurados.
• Anthropic Claude Platform Docs, Tool use with Claude presenta tool use como la capacidad de Claude para llamar funciones definidas por el usuario, decidiendo cuándo invocarlas según la solicitud y la descripción de la herramienta.