Špecifikácia formátu Skills

Formát skills.md definuje, ako sú Skills štruktúrované, konfigurované a vykonávané. Táto špecifikácia zaručuje konzistentné správanie naprieč všetkými Tajo Skills.

Štruktúra súboru

Skill je definovaný v jednom markdown súbore s YAML frontmatter:

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

Polia frontmatter

Povinné polia

Pole	Typ	Popis
`name`	reťazec	Jedinečný identifikátor (kebab-case)
`version`	reťazec	Sémantická verzia (napr. „2.1.0”)
`description`	reťazec	Krátky popis (max. 160 znakov)
`category`	enum	Jedna z: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	pole	Udalosti, ktoré aktivujú tento skill
`actions`	pole	Operácie, ktoré tento skill môže vykonávať

Voliteľné polia

Pole	Typ	Predvolená hodnota	Popis
`status`	enum	`stable`	Jedna z: `stable`, `beta`, `experimental`
`brevoEndpoints`	pole	`[]`	Použité Brevo API endpointy
`permissions`	pole	`[]`	Požadované oprávnenia Brevo API
`relatedSkills`	pole	`[]`	ID súvisiacich skills
`featured`	boolean	`false`	Zvýrazniť v katalógu skills

Spúšťače

Spúšťače definujú, ktoré udalosti aktivujú skill.

Spúšťače udalostí

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Minimálna hodnota košíka
      - items_count: ">= 1"       # Aspoň jedna položka
      - time_since_activity: "> 30m"  # 30 minút nečinnosti
    debounce: 5m                  # Čakanie 5 minút pred opätovným spustením

Plánované spúšťače

triggers:
  - schedule: "0 9 * * *"         # Cron výraz (každý deň o 9:00)
    timezone: "America/New_York"
  - schedule: every_hour
  - schedule: every_day

Webhookové spúšťače

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

Operátory podmienok

Operátor	Popis	Príklad
`=`	Rovná sa	`status: "active"`
`!=`	Nerovná sa	`status: "!= deleted"`
`>`	Väčší ako	`cart_value: "> 50"`
`>=`	Väčší alebo rovný	`items: ">= 1"`
`<`	Menší ako	`age: "< 30"`
`<=`	Menší alebo rovný	`quantity: "<= 10"`
`contains`	Reťazec obsahuje	`email: "contains @gmail.com"`
`starts_with`	Prefix reťazca	`name: "starts_with Dr."`
`in`	Hodnota v zozname	`country: "in US,CA,UK"`

Akcie

Akcie definujú, aké operácie skill vykonáva.

Definícia akcie

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  # alebo 'stop'

Typy akcií

Typ	Popis
`brevo/send-email`	Odoslanie transakčného e-mailu
`brevo/send-sms`	Odoslanie SMS správy
`brevo/send-whatsapp`	Odoslanie WhatsApp správy
`brevo/create-contact`	Vytvorenie nového kontaktu
`brevo/update-contact`	Aktualizácia atribútov kontaktu
`brevo/delete-contact`	Vymazanie kontaktu
`brevo/add-to-list`	Pridanie kontaktu do zoznamu
`brevo/remove-from-list`	Odstránenie kontaktu zo zoznamu
`brevo/track-event`	Sledovanie vlastnej udalosti
`http/request`	Vykonanie HTTP požiadavky
`transform/map`	Transformácia dát
`control/delay`	Čakanie pred pokračovaním
`control/condition`	Vetvenie na základe podmienky

Premenné šablón

Použite syntax {{ }} na odkazovanie na dáta:

parameters:
  to: "{{ contact.email }}"
  subject: "Vaša objednávka #{{ order.number }} bola odoslaná"
  params:
    name: "{{ contact.firstName | default: 'Zákazník' }}"
    items: "{{ cart.items | map: 'name' | join: ', ' }}"
    total: "{{ cart.total | currency: 'USD' }}"

Dostupné filtre

Filter	Popis	Príklad
`default`	Predvolená hodnota	`{{ name \| default: 'Hosť' }}`
`uppercase`	Reťazec veľkými písmenami	`{{ name \| uppercase }}`
`lowercase`	Reťazec malými písmenami	`{{ email \| lowercase }}`
`capitalize`	Prvé písmeno veľké	`{{ name \| capitalize }}`
`truncate`	Skrátenie reťazca	`{{ desc \| truncate: 100 }}`
`date`	Formátovanie dátumu	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Formátovanie meny	`{{ price \| currency: 'EUR' }}`
`map`	Mapovanie vlastnosti poľa	`{{ items \| map: 'name' }}`
`join`	Spojenie poľa	`{{ tags \| join: ', ' }}`
`first`	Prvý prvok poľa	`{{ items \| first }}`
`last`	Posledný prvok poľa	`{{ items \| last }}`
`size`	Dĺžka poľa/reťazca	`{{ items \| size }}`

Oprávnenia

Definujte požadované oprávnenia Brevo API:

permissions:
  - contacts:read        # Čítanie kontaktných dát
  - contacts:write       # Vytváranie/aktualizácia kontaktov
  - email:send           # Odosielanie transakčných e-mailov
  - sms:send             # Odosielanie SMS správ
  - lists:write          # Správa zoznamov kontaktov
  - events:write         # Sledovanie udalostí

Úplný príklad

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

Expozícia cez MCP nástroje

Skills môžu byť sprístupnené ako MCP nástroje, čo ich sprístupňuje pre volanie AI agentmi. Pridajte pole mcp do vášho frontmatter:

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

# Konfigurácia 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
---

Ako funguje expozícia cez MCP

Keď má skill pole mcp, stane sa nástrojom, ktorý môžu AI agenti objavovať a volať:

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

Polia MCP

Pole	Typ	Popis
`mcp.tool_name`	reťazec	Názov MCP nástroja (formát: `tajo/skill-name`)
`mcp.description`	reťazec	Popis zobrazený AI agentom počas objavovania nástrojov
`mcp.inputSchema`	objekt	JSON Schema definujúce vstupné parametre nástroja
`mcp.brevo_servers`	pole	Moduly Brevo MCP servera, ktoré tento skill potrebuje

Skills vs. priame MCP nástroje

Aspekt	Skill ako MCP nástroj	Priamy Brevo MCP
Abstrakcia	Vysoká, agent hovorí „zotav tento košík”	Nízka, agent musí volať jednotlivé Brevo endpointy
Zložitosť	Zapuzdruje viacstupňovú logiku	Agent musí orchestrovať každý krok
Ochranné prvky	Zabudované v skille (podmienky, debounce)	Agent si musí implementovať vlastné
Vhodné pre	Opakovateľné pracovné postupy	Jednorazové operácie

Tip

Používajte Skills ako MCP nástroje pre komplexné, viacstupňové pracovné postupy, ktoré by agenti nemali zakaždým znovu vymýšľať. Používajte priame Brevo MCP nástroje pre jednoduché, jednorazové operácie, ako je vyhľadanie kontaktu alebo odoslanie jedného e-mailu.

Kombinovanie Skills a agentov

Agent môže používať Skills (ako MCP nástroje) aj priame Brevo MCP moduly:

# Špecifikácia agenta
---
name: retention-agent
tools:
  # Tajo Skills ako MCP nástroje
  - tajo/recover-abandoned-cart
  - tajo/customer-sync
  - tajo/win-back-sequence
  # Priame Brevo MCP moduly
  - brevo_contacts
  - brevo_campaign_analytics
  - brevo_segments
---

Toto poskytuje agentom vysokoúrovňovú automatizáciu (Skills) pre bežné vzory, pričom si zachováva nízkoúrovňový prístup (Brevo MCP) pre vlastnú logiku.

Pozrite si Formát špecifikácie agenta a Tvorba agentov pre úplné podrobnosti.

Najlepšie postupy

Tip

Verzujte svoje skills pomocou sémantického verzovania. Zmeny, ktoré porušujú spätnú kompatibilitu, vyžadujú zvýšenie hlavnej verzie.

Udržujte skills sústredené – Jeden skill by mal robiť jednu vec dobre
Používajte opisné názvy – abandoned-cart-recovery, nie acr
Dokumentujte podmienky – Vysvetlite, prečo každá podmienka existuje
Elegantne zvládajte chyby – Používajte on_error: continue pre nekritické akcie
Testujte na malých skupinách – Počas vývoja používajte status: experimental
Pridajte expozíciu MCP pre skills, ktoré by mali byť priamo volateľné agentmi

Ďalšie kroky

Prehľad MCP a agentov – Ako sa Skills zapájajú do agentickej architektúry
Formát špecifikácie agenta – Definujte agentov, ktorí používajú Skills ako nástroje
Tvorba agentov – Vytvorte svojho prvého marketingového agenta
Skills synchronizácie dát – Preskúmajte skills synchronizácie dát