Spécification du format des Skills

Le format skills.md définit comment les Skills sont structurés, configurés et exécutés. Cette spécification garantit un comportement cohérent pour tous les Skills Tajo.

Structure du fichier

Un skill est défini dans un unique fichier markdown avec un 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...

Champs du frontmatter

Champs obligatoires

Champ	Type	Description
`name`	string	Identifiant unique (kebab-case)
`version`	string	Version sémantique (ex. « 2.1.0 »)
`description`	string	Description courte (160 caractères max)
`category`	enum	L’une des suivantes : `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	array	Événements qui activent ce skill
`actions`	array	Opérations que ce skill peut effectuer

Champs optionnels

Champ	Type	Par défaut	Description
`status`	enum	`stable`	L’une des suivantes : `stable`, `beta`, `experimental`
`brevoEndpoints`	array	`[]`	Endpoints API Brevo utilisés
`permissions`	array	`[]`	Permissions API Brevo requises
`relatedSkills`	array	`[]`	Identifiants des skills associés
`featured`	boolean	`false`	Mettre en avant dans le catalogue de skills

Déclencheurs

Les déclencheurs définissent les événements qui activent le skill.

Déclencheurs d’événement

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

Déclencheurs planifiés

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

Déclencheurs webhook

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

Opérateurs de condition

Opérateur	Description	Exemple
`=`	Égal	`status: "active"`
`!=`	Différent de	`status: "!= deleted"`
`>`	Supérieur à	`cart_value: "> 50"`
`>=`	Supérieur ou égal	`items: ">= 1"`
`<`	Inférieur à	`age: "< 30"`
`<=`	Inférieur ou égal	`quantity: "<= 10"`
`contains`	Chaîne contient	`email: "contains @gmail.com"`
`starts_with`	Préfixe de chaîne	`name: "starts_with Dr."`
`in`	Valeur dans une liste	`country: "in US,CA,UK"`

Actions

Les actions définissent les opérations effectuées par le skill.

Définition d’une action

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'

Types d’action

Type	Description
`brevo/send-email`	Envoyer un email transactionnel
`brevo/send-sms`	Envoyer un SMS
`brevo/send-whatsapp`	Envoyer un message WhatsApp
`brevo/create-contact`	Créer un nouveau contact
`brevo/update-contact`	Mettre à jour les attributs d’un contact
`brevo/delete-contact`	Supprimer un contact
`brevo/add-to-list`	Ajouter un contact à une liste
`brevo/remove-from-list`	Retirer un contact d’une liste
`brevo/track-event`	Suivre un événement personnalisé
`http/request`	Effectuer une requête HTTP
`transform/map`	Transformer des données
`control/delay`	Attendre avant de continuer
`control/condition`	Brancher selon une condition

Variables de modèle

Utilisez la syntaxe {{ }} pour référencer des données :

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

Filtres disponibles

Filtre	Description	Exemple
`default`	Valeur par défaut	`{{ name \| default: 'Guest' }}`
`uppercase`	Chaîne en majuscules	`{{ name \| uppercase }}`
`lowercase`	Chaîne en minuscules	`{{ email \| lowercase }}`
`capitalize`	Première lettre en majuscule	`{{ name \| capitalize }}`
`truncate`	Tronquer une chaîne	`{{ desc \| truncate: 100 }}`
`date`	Formater une date	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Formater en devise	`{{ price \| currency: 'EUR' }}`
`map`	Mapper une propriété de tableau	`{{ items \| map: 'name' }}`
`join`	Joindre un tableau	`{{ tags \| join: ', ' }}`
`first`	Premier élément du tableau	`{{ items \| first }}`
`last`	Dernier élément du tableau	`{{ items \| last }}`
`size`	Taille du tableau/de la chaîne	`{{ items \| size }}`

Permissions

Définissez les permissions API Brevo requises :

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

Exemple complet

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

Exposition en tant qu’outil MCP

Les Skills peuvent être exposés en tant qu’outils MCP, les rendant invocables par les agents IA. Ajoutez le champ mcp à votre 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
---

Fonctionnement de l’exposition MCP

Lorsqu’un skill possède un champ mcp, il devient un outil que les agents IA peuvent découvrir et invoquer :

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

Champs MCP

Champ	Type	Description
`mcp.tool_name`	string	Nom de l’outil MCP (format : `tajo/skill-name`)
`mcp.description`	string	Description présentée aux agents IA lors de la découverte d’outils
`mcp.inputSchema`	object	JSON Schema définissant les paramètres d’entrée de l’outil
`mcp.brevo_servers`	array	Modules de serveur MCP Brevo dont ce skill a besoin

Skills vs outils MCP directs

Aspect	Skill en tant qu’outil MCP	MCP Brevo direct
Abstraction	Élevée - l’agent dit « récupérer ce panier »	Faible - l’agent doit appeler chaque endpoint Brevo individuellement
Complexité	Encapsule une logique en plusieurs étapes	L’agent doit orchestrer chaque étape
Garde-fous	Intégrés au skill (conditions, debounce)	L’agent doit les implémenter lui-même
Idéal pour	Workflows répétables	Opérations ponctuelles

Tip

Utilisez les Skills comme outils MCP pour les workflows complexes en plusieurs étapes que les agents ne devraient pas réinventer à chaque fois. Utilisez les outils MCP Brevo directs pour les opérations simples et ponctuelles comme la recherche d’un contact ou l’envoi d’un seul email.

Composer Skills et Agents

Un agent peut utiliser à la fois des Skills (en tant qu’outils MCP) et des modules MCP Brevo directs :

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

Cela donne aux agents une automatisation de haut niveau (Skills) pour les schémas courants tout en conservant un accès bas niveau (MCP Brevo) pour la logique personnalisée.

Consultez Format de spécification d’agent et Construire des agents pour tous les détails.

Bonnes pratiques

Tip

Versionnez vos skills à l’aide du versionnage sémantique. Les changements cassants nécessitent une montée de version majeure.

Gardez les skills focalisés - Un skill doit faire une seule chose, et bien
Utilisez des noms descriptifs - abandoned-cart-recovery et non acr
Documentez les conditions - Expliquez pourquoi chaque condition existe
Gérez les erreurs avec élégance - Utilisez on_error: continue pour les actions non critiques
Testez avec de petites audiences - Utilisez status: experimental pendant le développement
Ajoutez une exposition MCP pour les skills que les agents devraient pouvoir invoquer directement

Étapes suivantes

Vue d’ensemble MCP et Agents - Comment les Skills s’intègrent dans l’architecture agentique
Format de spécification d’agent - Définir des agents qui utilisent les Skills comme outils
Construire des agents - Construisez votre premier agent marketing
Skills de synchronisation des données - Explorez les skills de synchronisation de données