Specificația formatului Skills

Formatul skills.md definește modul în care Skills sunt structurate, configurate și executate. Această specificație asigură comportament consistent în toate Skills Tajo.

Structura fișierului

Un skill este definit într-un singur fișier markdown cu 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...

Câmpuri frontmatter

Câmpuri obligatorii

Câmp	Tip	Descriere
`name`	string	Identificator unic (kebab-case)
`version`	string	Versiune semantică (ex. „2.1.0”)
`description`	string	Descriere scurtă (max. 160 caractere)
`category`	enum	Una din: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	array	Evenimente care activează acest skill
`actions`	array	Operații pe care skill-ul le poate efectua

Câmpuri opționale

Câmp	Tip	Implicit	Descriere
`status`	enum	`stable`	Una din: `stable`, `beta`, `experimental`
`brevoEndpoints`	array	`[]`	Punctele finale API Brevo utilizate
`permissions`	array	`[]`	Permisiunile API Brevo necesare
`relatedSkills`	array	`[]`	Identificatorii skills-urilor conexe
`featured`	boolean	`false`	Evidențiere în catalogul de skills

Declanșatoare

Declanșatoarele definesc ce evenimente activează skill-ul.

Declanșatoare de evenimente

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Valoarea minimă a coșului
      - items_count: ">= 1"       # Cel puțin un produs
      - time_since_activity: "> 30m"  # 30 de minute de inactivitate
    debounce: 5m                  # Așteptați 5 minute înainte de redeclanșare

Declanșatoare programate

triggers:
  - schedule: "0 9 * * *"         # Expresie cron (zilnic la 9:00)
    timezone: "America/New_York"
  - schedule: every_hour
  - schedule: every_day

Declanșatoare webhook

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

Operatori de condiții

Operator	Descriere	Exemplu
`=`	Egal cu	`status: "active"`
`!=`	Diferit de	`status: "!= deleted"`
`>`	Mai mare decât	`cart_value: "> 50"`
`>=`	Mai mare sau egal cu	`items: ">= 1"`
`<`	Mai mic decât	`age: "< 30"`
`<=`	Mai mic sau egal cu	`quantity: "<= 10"`
`contains`	Conține șir	`email: "contains @gmail.com"`
`starts_with`	Prefix șir	`name: "starts_with Dr."`
`in`	Valoare în listă	`country: "in US,CA,UK"`

Acțiuni

Acțiunile definesc ce operații efectuează skill-ul.

Definiția acțiunii

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'

Tipuri de acțiuni

Tip	Descriere
`brevo/send-email`	Trimite e-mail tranzacțional
`brevo/send-sms`	Trimite mesaj SMS
`brevo/send-whatsapp`	Trimite mesaj WhatsApp
`brevo/create-contact`	Creează contact nou
`brevo/update-contact`	Actualizează atributele contactului
`brevo/delete-contact`	Șterge contact
`brevo/add-to-list`	Adaugă contact la listă
`brevo/remove-from-list`	Elimină contactul din listă
`brevo/track-event`	Urmărește eveniment personalizat
`http/request`	Efectuează cerere HTTP
`transform/map`	Transformă date
`control/delay`	Așteaptă înainte de continuare
`control/condition`	Ramifică pe baza unei condiții

Variabile de șablon

Utilizați sintaxa {{ }} pentru a referenția date:

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

Filtre disponibile

Filtru	Descriere	Exemplu
`default`	Valoare implicită	`{{ name \| default: 'Guest' }}`
`uppercase`	Majuscule	`{{ name \| uppercase }}`
`lowercase`	Minuscule	`{{ email \| lowercase }}`
`capitalize`	Prima literă majusculă	`{{ name \| capitalize }}`
`truncate`	Trunchiază șirul	`{{ desc \| truncate: 100 }}`
`date`	Formatează data	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Formatează moneda	`{{ price \| currency: 'EUR' }}`
`map`	Mapează proprietatea tabloului	`{{ items \| map: 'name' }}`
`join`	Concatenează tabloul	`{{ tags \| join: ', ' }}`
`first`	Primul element al tabloului	`{{ items \| first }}`
`last`	Ultimul element al tabloului	`{{ items \| last }}`
`size`	Lungimea tabloului/șirului	`{{ items \| size }}`

Permisiuni

Definiți permisiunile API Brevo necesare:

permissions:
  - contacts:read        # Citire date contacte
  - contacts:write       # Creare/actualizare contacte
  - email:send           # Trimitere e-mailuri tranzacționale
  - sms:send             # Trimitere mesaje SMS
  - lists:write          # Gestionare liste de contacte
  - events:write         # Urmărire evenimente

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

Expunerea ca instrument MCP

Skills pot fi expuse ca instrumente MCP, permițând agenților AI să le descopere și să le invoce. Adăugați câmpul mcp în frontmatter:

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

# Configurație MCP
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
---

Cum funcționează expunerea MCP

Când un skill are un câmp mcp, devine un instrument pe care agenții AI îl pot descoperi și invoca:

Agent: „Recover abandoned cart #4521 for [email protected]"
    ↓
Descoperire instrument MCP: găsește tajo/recover-abandoned-cart
    ↓
Execuție instrument: rulează lanțul de acțiuni al skill-ului
    ↓
Servere MCP Brevo: modulele contacte + e-mail sunt apelate
    ↓
Rezultat: secvența de recuperare inițiată

Câmpuri MCP

Câmp	Tip	Descriere
`mcp.tool_name`	string	Numele instrumentului MCP (format: `tajo/skill-name`)
`mcp.description`	string	Descriere afișată agenților AI la descoperirea instrumentului
`mcp.inputSchema`	object	JSON Schema ce definește parametrii de intrare ai instrumentului
`mcp.brevo_servers`	array	Modulele serverului MCP Brevo necesare acestui skill

Skills vs. instrumente MCP directe

Aspect	Skill ca instrument MCP	MCP Brevo direct
Abstractizare	Ridicată – agentul spune „recuperează coșul”	Scăzută – agentul trebuie să apeleze individual punctele finale Brevo
Complexitate	Încapsulează logica în mai mulți pași	Agentul trebuie să orchestreze fiecare pas
Restricții	Încorporate în skill (condiții, debounce)	Agentul trebuie să-și implementeze propriile
Potrivit pentru	Fluxuri de lucru repetabile	Operații ad-hoc

Tip

Utilizați Skills ca instrumente MCP pentru fluxuri de lucru complexe, cu mai mulți pași, pe care agenții nu ar trebui să le recreeze de fiecare dată. Utilizați instrumente MCP Brevo directe pentru operații simple, cum ar fi căutarea unui contact sau trimiterea unui singur e-mail.

Compunerea Skills și Agenților

Un agent poate folosi atât Skills (ca instrumente MCP), cât și module MCP Brevo directe:

# Specificația agentului
---
name: retention-agent
tools:
  # Skills Tajo ca instrumente MCP
  - tajo/recover-abandoned-cart
  - tajo/customer-sync
  - tajo/win-back-sequence
  # Module MCP Brevo directe
  - brevo_contacts
  - brevo_campaign_analytics
  - brevo_segments
---

Aceasta oferă agenților automatizare la nivel înalt (Skills) pentru tipare comune, păstrând totodată accesul la nivel scăzut (MCP Brevo) pentru logică personalizată.

Consultați Formatul specificației agentului și Construirea agenților pentru detalii complete.

Bune practici

Tip

Versionați skills-urile folosind versionare semantică. Modificările care rup compatibilitatea necesită incrementarea versiunii majore.

Mențineți skills-urile focalizate – Un skill ar trebui să facă un singur lucru bine
Utilizați nume descriptive – abandoned-cart-recovery, nu acr
Documentați condițiile – Explicați de ce există fiecare condiție
Gestionați erorile elegant – Utilizați on_error: continue pentru acțiuni non-critice
Testați cu audiențe mici – Utilizați status: experimental în timpul dezvoltării
Adăugați expunere MCP pentru skills-urile pe care agenții ar trebui să le poată invoca direct

Pași următori

Prezentare generală MCP și Agenți – Cum se încadrează Skills în arhitectura agentică
Formatul specificației agentului – Definiți agenți care folosesc Skills ca instrumente
Construirea agenților – Construiți primul dvs. agent de marketing
Skills sincronizare date – Explorați skills-urile de sincronizare a datelor