Especificación del Formato de Skills

El formato skills.md define cómo se estructuran, configuran y ejecutan las Skills. Esta especificación garantiza un comportamiento consistente en todas las Skills de Tajo.

Estructura del Archivo

Una skill se define en un único archivo markdown con frontmatter YAML:

---
name: customer-sync
version: 2.1.0
description: Sync customer data to Brevo contacts
category: data-sync
status: stable

triggers:
  - event: customer_created
  - event: customer_updated
  - event: customer_deleted

actions:
  - brevo/create-contact
  - brevo/update-contact
  - brevo/delete-contact

brevoEndpoints:
  - POST /v3/contacts
  - PUT /v3/contacts/{identifier}
  - DELETE /v3/contacts/{identifier}

permissions:
  - contacts:write
  - contacts:read
---

# Customer Sync

Automatically synchronize customer data from your platform to Brevo contacts.

## Overview

This skill listens for customer lifecycle events and mirrors changes to Brevo...

Campos del Frontmatter

Campos Obligatorios

Campo	Tipo	Descripción
`name`	string	Identificador único (kebab-case)
`version`	string	Versión semántica (p. ej., “2.1.0”)
`description`	string	Descripción corta (máximo 160 caracteres)
`category`	enum	Uno de: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	array	Eventos que activan esta skill
`actions`	array	Operaciones que esta skill puede realizar

Campos Opcionales

Campo	Tipo	Valor Predeterminado	Descripción
`status`	enum	`stable`	Uno de: `stable`, `beta`, `experimental`
`brevoEndpoints`	array	`[]`	Endpoints de la API de Brevo utilizados
`permissions`	array	`[]`	Permisos de API de Brevo requeridos
`relatedSkills`	array	`[]`	IDs de skills relacionadas
`featured`	boolean	`false`	Destacar en el catálogo de skills

Triggers

Los triggers definen qué eventos activan la skill.

Triggers de Evento

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Minimum cart value
      - items_count: ">= 1"       # At least one item
      - time_since_activity: "> 30m"  # 30 minutes of inactivity
    debounce: 5m                  # Wait 5 minutes before re-triggering

Triggers Programados

triggers:
  - schedule: "0 9 * * *"         # Cron expression (daily at 9am)
    timezone: "America/New_York"
  - schedule: every_hour
  - schedule: every_day

Triggers de Webhook

triggers:
  - webhook: /skills/customer-sync/trigger
    method: POST
    authentication: api_key

Operadores de Condición

Operador	Descripción	Ejemplo
`=`	Igual	`status: "active"`
`!=`	Distinto de	`status: "!= deleted"`
`>`	Mayor que	`cart_value: "> 50"`
`>=`	Mayor o igual	`items: ">= 1"`
`<`	Menor que	`age: "< 30"`
`<=`	Menor o igual	`quantity: "<= 10"`
`contains`	Cadena contiene	`email: "contains @gmail.com"`
`starts_with`	Prefijo de cadena	`name: "starts_with Dr."`
`in`	Valor en lista	`country: "in US,CA,UK"`

Acciones

Las acciones definen qué operaciones realiza la skill.

Definición de Acción

actions:
  - id: send_reminder_email
    type: brevo/send-email
    parameters:
      template_id: 12345
      to: "{{ contact.email }}"
      params:
        first_name: "{{ contact.firstName }}"
        cart_items: "{{ cart.items }}"
    retry:
      attempts: 3
      backoff: exponential
    on_error: continue  # or 'stop'

Tipos de Acción

Tipo	Descripción
`brevo/send-email`	Envía email transaccional
`brevo/send-sms`	Envía mensaje SMS
`brevo/send-whatsapp`	Envía mensaje de WhatsApp
`brevo/create-contact`	Crea un nuevo contacto
`brevo/update-contact`	Actualiza atributos de contacto
`brevo/delete-contact`	Elimina un contacto
`brevo/add-to-list`	Añade contacto a una lista
`brevo/remove-from-list`	Quita contacto de una lista
`brevo/track-event`	Rastrea un evento personalizado
`http/request`	Realiza una petición HTTP
`transform/map`	Transforma datos
`control/delay`	Espera antes de continuar
`control/condition`	Bifurca según una condición

Variables de Plantilla

Usa la sintaxis {{ }} para referenciar datos:

parameters:
  to: "{{ contact.email }}"
  subject: "Your order #{{ order.number }} has shipped"
  params:
    name: "{{ contact.firstName | default: 'Customer' }}"
    items: "{{ cart.items | map: 'name' | join: ', ' }}"
    total: "{{ cart.total | currency: 'USD' }}"

Filtros Disponibles

Filtro	Descripción	Ejemplo
`default`	Valor predeterminado	`{{ name \| default: 'Guest' }}`
`uppercase`	Cadena en mayúsculas	`{{ name \| uppercase }}`
`lowercase`	Cadena en minúsculas	`{{ email \| lowercase }}`
`capitalize`	Primera letra en mayúscula	`{{ name \| capitalize }}`
`truncate`	Trunca la cadena	`{{ desc \| truncate: 100 }}`
`date`	Formatea fecha	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Formatea moneda	`{{ price \| currency: 'EUR' }}`
`map`	Mapea propiedad del arreglo	`{{ items \| map: 'name' }}`
`join`	Une un arreglo	`{{ tags \| join: ', ' }}`
`first`	Primer elemento del arreglo	`{{ items \| first }}`
`last`	Último elemento del arreglo	`{{ items \| last }}`
`size`	Longitud de arreglo/cadena	`{{ items \| size }}`

Permisos

Define los permisos de API de Brevo requeridos:

permissions:
  - contacts:read        # Read contact data
  - contacts:write       # Create/update contacts
  - email:send           # Send transactional emails
  - sms:send             # Send SMS messages
  - lists:write          # Manage contact lists
  - events:write         # Track events

Ejemplo Completo

---
name: abandoned-cart-recovery
version: 3.0.0
description: Recover abandoned shopping carts with a multi-step email sequence
category: email-marketing
status: stable

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 25"
      - customer_email: "exists"
      - items_count: ">= 1"
    debounce: 30m

actions:
  - id: wait_1h
    type: control/delay
    parameters:
      duration: 1h

  - id: check_purchase
    type: control/condition
    parameters:
      condition: "{{ cart.converted }} = false"
      then: send_first_email
      else: stop

  - id: send_first_email
    type: brevo/send-email
    parameters:
      template_id: {{ env.ABANDONED_CART_TEMPLATE_1 }}
      to: "{{ contact.email }}"
      params:
        first_name: "{{ contact.firstName }}"
        cart_url: "{{ cart.recovery_url }}"
        items: "{{ cart.items }}"
        total: "{{ cart.total | currency }}"

  - id: wait_24h
    type: control/delay
    parameters:
      duration: 24h

  - id: check_purchase_2
    type: control/condition
    parameters:
      condition: "{{ cart.converted }} = false"
      then: send_second_email
      else: stop

  - id: send_second_email
    type: brevo/send-email
    parameters:
      template_id: {{ env.ABANDONED_CART_TEMPLATE_2 }}
      to: "{{ contact.email }}"
      params:
        first_name: "{{ contact.firstName }}"
        cart_url: "{{ cart.recovery_url }}"
        discount_code: "{{ generate_discount(10, 'percent') }}"

brevoEndpoints:
  - POST /v3/smtp/email
  - GET /v3/contacts/{identifier}

permissions:
  - contacts:read
  - email:send

relatedSkills:
  - customer-sync
  - order-events
  - browse-abandonment
---

# Abandoned Cart Recovery

Recover lost sales with a proven multi-step email sequence...

Exposición como Herramienta MCP

Las skills pueden exponerse como herramientas MCP, para que los agentes de IA puedan invocarlas. Añade el campo mcp a tu frontmatter:

---
name: abandoned-cart-recovery
version: 3.0.0
description: Recover abandoned shopping carts with a multi-step email sequence
category: email-marketing

# MCP Configuration
mcp:
  tool_name: tajo/recover-abandoned-cart
  description: Execute abandoned cart recovery sequence for a specific cart
  inputSchema:
    type: object
    properties:
      cart_id:
        type: string
        description: The abandoned cart identifier
      customer_email:
        type: string
        description: Customer email address
      min_cart_value:
        type: number
        description: Minimum cart value to trigger recovery
        default: 25
    required: [cart_id, customer_email]
  brevo_servers:
    - brevo_contacts
    - brevo_email_campaign_management
    - brevo_templates
---

Cómo Funciona la Exposición MCP

Cuando una skill tiene un campo mcp, se convierte en una herramienta que los agentes de IA pueden descubrir e invocar:

Agent: "Recover abandoned cart #4521 for [email protected]"
    ↓
MCP Tool Discovery: finds tajo/recover-abandoned-cart
    ↓
Tool Execution: runs the skill's action chain
    ↓
Brevo MCP Servers: contacts + email modules called
    ↓
Result: recovery sequence initiated

Campos MCP

Campo	Tipo	Descripción
`mcp.tool_name`	string	Nombre de la herramienta MCP (formato: `tajo/skill-name`)
`mcp.description`	string	Descripción mostrada a los agentes de IA durante el descubrimiento de herramientas
`mcp.inputSchema`	object	JSON Schema que define los parámetros de entrada de la herramienta
`mcp.brevo_servers`	array	Qué módulos del servidor MCP de Brevo necesita esta skill

Skills vs Herramientas MCP Directas

Aspecto	Skill como Herramienta MCP	MCP Directo de Brevo
Abstracción	Alta, el agente dice “recupera este carrito”	Baja, el agente debe llamar a endpoints individuales de Brevo
Complejidad	Encapsula lógica de varios pasos	El agente debe orquestar cada paso
Guardarraíles	Incorporados en la skill (condiciones, debounce)	El agente debe implementarlos por sí mismo
Ideal para	Flujos de trabajo repetibles	Operaciones ad-hoc

Tip

Usa Skills como herramientas MCP para flujos de trabajo complejos de varios pasos que los agentes no deberían reinventar cada vez. Usa herramientas MCP directas de Brevo para operaciones simples y puntuales como buscar un contacto o enviar un único email.

Componiendo Skills y Agentes

Un agente puede usar tanto Skills (como herramientas MCP) como módulos MCP directos de Brevo:

# Agent spec
---
name: retention-agent
tools:
  # Tajo Skills as MCP tools
  - tajo/recover-abandoned-cart
  - tajo/customer-sync
  - tajo/win-back-sequence
  # Direct Brevo MCP modules
  - brevo_contacts
  - brevo_campaign_analytics
  - brevo_segments
---

Esto les da a los agentes automatización de alto nivel (Skills) para patrones comunes, manteniendo el acceso de bajo nivel (MCP de Brevo) para lógica personalizada.

Consulta Formato de Especificación de Agentes y Construyendo Agentes para ver todos los detalles.

Buenas Prácticas

Tip

Versiona tus skills usando versionado semántico. Los cambios que rompan compatibilidad requieren un incremento de la versión mayor.

Mantén las skills enfocadas - Una skill debe hacer una sola cosa bien
Usa nombres descriptivos - abandoned-cart-recovery no acr
Documenta las condiciones - Explica por qué existe cada condición
Maneja los errores con elegancia - Usa on_error: continue para acciones no críticas
Prueba con audiencias pequeñas - Usa status: experimental durante el desarrollo
Agrega exposición MCP para skills que los agentes deberían poder invocar directamente

Próximos Pasos

Resumen de MCP y Agentes - Cómo encajan las Skills en la arquitectura agéntica
Formato de Especificación de Agentes - Define agentes que usen Skills como herramientas
Construyendo Agentes - Construye tu primer agente de marketing
Skills de Sincronización de Datos - Explora las skills de sincronización de datos