Specifica del Formato Skill

Il formato skills.md definisce come le skill sono strutturate, configurate ed eseguite. Questa specifica garantisce un comportamento coerente tra tutte le skill di Tajo.

Struttura del file

Una skill è definita in un singolo file 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...

Campi del frontmatter

Campi obbligatori

Campo	Tipo	Descrizione
`name`	string	Identificatore univoco (kebab-case)
`version`	string	Versione semantica (es. “2.1.0”)
`description`	string	Breve descrizione (max 160 caratteri)
`category`	enum	Uno tra: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	array	Eventi che attivano questa skill
`actions`	array	Operazioni che questa skill può eseguire

Campi opzionali

Campo	Tipo	Default	Descrizione
`status`	enum	`stable`	Uno tra: `stable`, `beta`, `experimental`
`brevoEndpoints`	array	`[]`	Endpoint API Brevo utilizzati
`permissions`	array	`[]`	Permessi API Brevo richiesti
`relatedSkills`	array	`[]`	ID delle skill correlate
`featured`	boolean	`false`	Evidenzia nel catalogo delle skill

Trigger

I trigger definiscono quali eventi attivano la skill.

Trigger basati su eventi

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

Trigger pianificati

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

Trigger via webhook

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

Operatori di condizione

Operatore	Descrizione	Esempio
`=`	Uguale	`status: "active"`
`!=`	Diverso	`status: "!= deleted"`
`>`	Maggiore di	`cart_value: "> 50"`
`>=`	Maggiore o uguale	`items: ">= 1"`
`<`	Minore di	`age: "< 30"`
`<=`	Minore o uguale	`quantity: "<= 10"`
`contains`	La stringa contiene	`email: "contains @gmail.com"`
`starts_with`	Prefisso della stringa	`name: "starts_with Dr."`
`in`	Valore nella lista	`country: "in US,CA,UK"`

Azioni

Le azioni definiscono le operazioni che la skill esegue.

Definizione dell’azione

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'

Tipi di azione

Tipo	Descrizione
`brevo/send-email`	Invia email transazionale
`brevo/send-sms`	Invia messaggio SMS
`brevo/send-whatsapp`	Invia messaggio WhatsApp
`brevo/create-contact`	Crea nuovo contatto
`brevo/update-contact`	Aggiorna attributi del contatto
`brevo/delete-contact`	Elimina contatto
`brevo/add-to-list`	Aggiungi contatto alla lista
`brevo/remove-from-list`	Rimuovi contatto dalla lista
`brevo/track-event`	Traccia evento personalizzato
`http/request`	Esegui richiesta HTTP
`transform/map`	Trasforma dati
`control/delay`	Attendi prima di proseguire
`control/condition`	Ramifica in base a una condizione

Variabili di template

Usa la sintassi {{ }} per referenziare i dati:

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' }}"

Filtri disponibili

Filtro	Descrizione	Esempio
`default`	Valore di default	`{{ name \| default: 'Guest' }}`
`uppercase`	Stringa in maiuscolo	`{{ name \| uppercase }}`
`lowercase`	Stringa in minuscolo	`{{ email \| lowercase }}`
`capitalize`	Prima lettera maiuscola	`{{ name \| capitalize }}`
`truncate`	Tronca stringa	`{{ desc \| truncate: 100 }}`
`date`	Formatta data	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Formatta valuta	`{{ price \| currency: 'EUR' }}`
`map`	Mappa proprietà di array	`{{ items \| map: 'name' }}`
`join`	Unisci array	`{{ tags \| join: ', ' }}`
`first`	Primo elemento dell’array	`{{ items \| first }}`
`last`	Ultimo elemento dell’array	`{{ items \| last }}`
`size`	Lunghezza array/stringa	`{{ items \| size }}`

Permessi

Definisci i permessi API Brevo richiesti:

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

Esempio 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...

Esposizione come tool MCP

Le skill possono essere esposte come tool MCP, rendendole richiamabili da agenti AI. Aggiungi il campo mcp al tuo 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
---

Come funziona l’esposizione MCP

Quando una skill contiene un campo mcp, diventa un tool che gli agenti AI possono scoprire e invocare:

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

Campi MCP

Campo	Tipo	Descrizione
`mcp.tool_name`	string	Nome del tool MCP (formato: `tajo/skill-name`)
`mcp.description`	string	Descrizione mostrata agli agenti AI durante la discovery del tool
`mcp.inputSchema`	object	JSON Schema che definisce i parametri di input del tool
`mcp.brevo_servers`	array	Quali moduli del server MCP di Brevo servono a questa skill

Skill vs tool MCP diretti

Aspetto	Skill come tool MCP	MCP Brevo diretto
Astrazione	Alta - l’agente dice “recupera questo carrello”	Bassa - l’agente deve chiamare i singoli endpoint Brevo
Complessità	Incapsula logica multi-step	L’agente deve orchestrare ogni passaggio
Guardrail	Integrati nella skill (condizioni, debounce)	L’agente deve implementarli da sé
Ideale per	Flussi ripetibili	Operazioni ad hoc

Tip

Usa le Skill come tool MCP per flussi complessi multi-step che gli agenti non dovrebbero reinventare ogni volta. Usa i tool MCP Brevo diretti per operazioni semplici e occasionali, come cercare un contatto o inviare una singola email.

Comporre Skill e Agenti

Un agente può usare sia le Skill (come tool MCP) sia i moduli MCP Brevo diretti:

# 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
---

Questo offre agli agenti un’automazione di alto livello (Skill) per pattern comuni, mantenendo l’accesso di basso livello (MCP Brevo) per la logica personalizzata.

Vedi Formato di specifica dell’agente e Costruire agenti per tutti i dettagli.

Best practice

Tip

Versiona le tue skill usando il versionamento semantico. I breaking change richiedono un major version bump.

Mantieni le skill focalizzate - Una skill dovrebbe fare una cosa sola, fatta bene
Usa nomi descrittivi - abandoned-cart-recovery non acr
Documenta le condizioni - Spiega perché ogni condizione esiste
Gestisci gli errori con grazia - Usa on_error: continue per le azioni non critiche
Testa con audience ristrette - Usa status: experimental durante lo sviluppo
Aggiungi l’esposizione MCP per le skill che gli agenti dovrebbero poter invocare direttamente

Prossimi passi

Panoramica MCP e Agenti - Come le skill si inseriscono nell’architettura agentica
Formato di specifica dell’agente - Definisci agenti che usano le skill come tool
Costruire agenti - Crea il tuo primo agente di marketing
Skill di Data Sync - Esplora le skill di sincronizzazione dati