Specifikacija formata Skills

Format skills.md definiše kako su Skills strukturirani, konfigurisani i izvršavani. Ova specifikacija obezbeđuje konzistentno ponašanje svih Tajo Skills.

Struktura fajla

Skill je definisan u jednom markdown fajlu sa 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...

Polja frontmatter

Obavezna polja

Polje	Tip	Opis
`name`	string	Jedinstveni identifikator (kebab-case)
`version`	string	Semantička verzija (npr. „2.1.0”)
`description`	string	Kratak opis (maks. 160 znakova)
`category`	enum	Jedna od: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	niz	Događaji koji aktiviraju ovaj skill
`actions`	niz	Operacije koje ovaj skill može da izvrši

Opcionalna polja

Polje	Tip	Podrazumevano	Opis
`status`	enum	`stable`	Jedna od: `stable`, `beta`, `experimental`
`brevoEndpoints`	niz	`[]`	Korišćeni Brevo API endpointi
`permissions`	niz	`[]`	Potrebne dozvole Brevo API
`relatedSkills`	niz	`[]`	ID-jevi srodnih skills
`featured`	boolean	`false`	Istakni u katalogu skills

Okidači

Okidači definišu koji događaji aktiviraju skill.

Okidači događaja

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Minimalna vrednost korpe
      - items_count: ">= 1"       # Najmanje jedna stavka
      - time_since_activity: "> 30m"  # 30 minuta neaktivnosti
    debounce: 5m                  # Čekaj 5 minuta pre ponovnog aktiviranja

Zakazani okidači

triggers:
  - schedule: "0 9 * * *"         # Cron izraz (svaki dan u 9:00)
    timezone: "America/New_York"
  - schedule: every_hour
  - schedule: every_day

Webhook okidači

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

Operatori uslova

Operator	Opis	Primer
`=`	Jednako	`status: "active"`
`!=`	Nije jednako	`status: "!= deleted"`
`>`	Veće od	`cart_value: "> 50"`
`>=`	Veće ili jednako	`items: ">= 1"`
`<`	Manje od	`age: "< 30"`
`<=`	Manje ili jednako	`quantity: "<= 10"`
`contains`	String sadrži	`email: "contains @gmail.com"`
`starts_with`	Prefiks stringa	`name: "starts_with Dr."`
`in`	Vrednost na listi	`country: "in US,CA,UK"`

Akcije

Akcije definišu koje operacije skill izvršava.

Definicija akcije

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

Vrste akcija

Vrsta	Opis
`brevo/send-email`	Slanje transakcionog e-maila
`brevo/send-sms`	Slanje SMS poruke
`brevo/send-whatsapp`	Slanje WhatsApp poruke
`brevo/create-contact`	Kreiranje novog kontakta
`brevo/update-contact`	Ažuriranje atributa kontakta
`brevo/delete-contact`	Brisanje kontakta
`brevo/add-to-list`	Dodavanje kontakta na listu
`brevo/remove-from-list`	Uklanjanje kontakta sa liste
`brevo/track-event`	Praćenje prilagođenog događaja
`http/request`	Slanje HTTP zahteva
`transform/map`	Transformacija podataka
`control/delay`	Čekanje pre nastavka
`control/condition`	Grananje na osnovu uslova

Promenljive u predlošcima

Koristite sintaksu {{ }} za referenciranje podataka:

parameters:
  to: "{{ contact.email }}"
  subject: "Vaša porudžbina #{{ order.number }} je otpremljena"
  params:
    name: "{{ contact.firstName | default: 'Kupac' }}"
    items: "{{ cart.items | map: 'name' | join: ', ' }}"
    total: "{{ cart.total | currency: 'USD' }}"

Dostupni filteri

Filter	Opis	Primer
`default`	Podrazumevana vrednost	`{{ name \| default: 'Gost' }}`
`uppercase`	String velikim slovima	`{{ name \| uppercase }}`
`lowercase`	String malim slovima	`{{ email \| lowercase }}`
`capitalize`	Prvo slovo veliko	`{{ name \| capitalize }}`
`truncate`	Skratiti string	`{{ desc \| truncate: 100 }}`
`date`	Formatiranje datuma	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Formatiranje valute	`{{ price \| currency: 'EUR' }}`
`map`	Mapiranje svojstva niza	`{{ items \| map: 'name' }}`
`join`	Spajanje niza	`{{ tags \| join: ', ' }}`
`first`	Prva stavka niza	`{{ items \| first }}`
`last`	Poslednja stavka niza	`{{ items \| last }}`
`size`	Dužina niza/stringa	`{{ items \| size }}`

Dozvole

Definišite potrebne dozvole Brevo API:

permissions:
  - contacts:read        # Čitanje podataka o kontaktima
  - contacts:write       # Kreiranje/ažuriranje kontakata
  - email:send           # Slanje transakcionih e-mailova
  - sms:send             # Slanje SMS poruka
  - lists:write          # Upravljanje listama kontakata
  - events:write         # Praćenje događaja

Potpun primer

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

Izlaganje putem MCP alata

Skills mogu biti izloženi kao MCP alati, što ih čini dostupnim za pozivanje od strane AI agenata. Dodajte polje mcp u vaš frontmatter:

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

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

Kako funkcioniše izlaganje putem MCP

Kada skill ima polje mcp, postaje alat koji AI agenti mogu da otkriju i pozovu:

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

Polja MCP

Polje	Tip	Opis
`mcp.tool_name`	string	Naziv MCP alata (format: `tajo/skill-name`)
`mcp.description`	string	Opis prikazan AI agentima tokom otkrivanja alata
`mcp.inputSchema`	objekat	JSON Schema koji definiše ulazne parametre alata
`mcp.brevo_servers`	niz	Moduli Brevo MCP servera koje ovaj skill zahteva

Skills vs. direktni MCP alati

Aspekt	Skill kao MCP alat	Direktni Brevo MCP
Apstrakcija	Visoka, agent kaže „oporavi ovu korpu”	Niska, agent mora pozivati pojedinačne Brevo endpointe
Složenost	Enkapsulira višestepenu logiku	Agent mora orkestrovati svaki korak
Zaštitne mere	Ugrađene u skill (uslovi, debounce)	Agent mora implementirati sopstvene
Najpogodnije za	Ponovljive tokove rada	Jednokratne operacije

Tip

Koristite Skills kao MCP alate za složene, višestepene tokove rada koje agenti ne bi trebalo svaki put iznova da izmišljaju. Koristite direktne Brevo MCP alate za jednostavne, jednokratne operacije poput traženja kontakta ili slanja jednog e-maila.

Kombinovanje Skills i agenata

Agent može koristiti i Skills (kao MCP alate) i direktne Brevo MCP module:

# Specifikacija agenta
---
name: retention-agent
tools:
  # Tajo Skills kao MCP alati
  - tajo/recover-abandoned-cart
  - tajo/customer-sync
  - tajo/win-back-sequence
  # Direktni Brevo MCP moduli
  - brevo_contacts
  - brevo_campaign_analytics
  - brevo_segments
---

Ovo daje agentima visokonivojsku automatizaciju (Skills) za uobičajene obrasce uz zadržavanje niskonivovskog pristupa (Brevo MCP) za prilagođenu logiku.

Pogledajte Format specifikacije agenta i Izgradnja agenata za potpune detalje.

Najbolje prakse

Tip

Verzionirajte svoje skills koristeći semantičko verzioniranje. Promene koje narušavaju kompatibilnost zahtevaju povećanje glavne verzije.

Održavajte skills fokusiranim – Jedan skill treba da radi jednu stvar dobro
Koristite opisna imena – abandoned-cart-recovery, ne acr
Dokumentujte uslove – Objasnite zašto svaki uslov postoji
Elegantno rukujte greškama – Koristite on_error: continue za nekritične akcije
Testirajte na malim grupama – Tokom razvoja koristite status: experimental
Dodajte izlaganje MCP za skills koje agenti treba da mogu direktno da pozivaju

Sledeći koraci

Pregled MCP i agenata – Kako se Skills uklapaju u agentnu arhitekturu
Format specifikacije agenta – Definišite agente koji koriste Skills kao alate
Izgradnja agenata – Izgradite svog prvog marketinškog agenta
Skills sinhronizacije podataka – Istražite skills za sinhronizaciju podataka