Specifikacija formata Skills

Format skills.md določa, kako so Skills strukturirani, konfigurirani in izvajani. Ta specifikacija zagotavlja dosledno delovanje vseh Tajo Skills.

Struktura datoteke

Skill je definiran v eni datoteki markdown z 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

Obvezna polja

Polje	Tip	Opis
`name`	niz	Edinstveni identifikator (kebab-case)
`version`	niz	Semantična verzija (npr. »2.1.0«)
`description`	niz	Kratek opis (največ 160 znakov)
`category`	enum	Ena od: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	polje	Dogodki, ki aktivirajo ta skill
`actions`	polje	Operacije, ki jih ta skill lahko izvaja

Neobvezna polja

Polje	Tip	Privzeto	Opis
`status`	enum	`stable`	Ena od: `stable`, `beta`, `experimental`
`brevoEndpoints`	polje	`[]`	Uporabljeni Brevo API-ji
`permissions`	polje	`[]`	Zahtevana dovoljenja Brevo API
`relatedSkills`	polje	`[]`	ID-ji sorodnih skills
`featured`	boolean	`false`	Izpostavi v katalogu skills

Sprožilci

Sprožilci določajo, kateri dogodki aktivirajo skill.

Sprožilci dogodkov

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Minimalna vrednost košarice
      - items_count: ">= 1"       # Vsaj en artikel
      - time_since_activity: "> 30m"  # 30 minut nedejavnosti
    debounce: 5m                  # Počakaj 5 minut pred ponovnim sprožitvijo

Načrtovani sprožilci

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

Sprožilci webhookov

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

Operatorji pogojev

Operator	Opis	Primer
`=`	Enako	`status: "active"`
`!=`	Ni enako	`status: "!= deleted"`
`>`	Večje kot	`cart_value: "> 50"`
`>=`	Večje ali enako	`items: ">= 1"`
`<`	Manjše kot	`age: "< 30"`
`<=`	Manjše ali enako	`quantity: "<= 10"`
`contains`	Niz vsebuje	`email: "contains @gmail.com"`
`starts_with`	Predpona niza	`name: "starts_with Dr."`
`in`	Vrednost na seznamu	`country: "in US,CA,UK"`

Dejanja

Dejanja določajo, katere operacije skill izvaja.

Definicija dejanja

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

Vrste dejanj

Vrsta	Opis
`brevo/send-email`	Pošljite transakcijsko e-pošto
`brevo/send-sms`	Pošljite SMS sporočilo
`brevo/send-whatsapp`	Pošljite sporočilo WhatsApp
`brevo/create-contact`	Ustvarite nov stik
`brevo/update-contact`	Posodobite atribute stika
`brevo/delete-contact`	Izbrišite stik
`brevo/add-to-list`	Dodajte stik na seznam
`brevo/remove-from-list`	Odstranite stik s seznama
`brevo/track-event`	Sledite lastnemu dogodku
`http/request`	Izvedite zahtevo HTTP
`transform/map`	Preoblikujte podatke
`control/delay`	Počakajte pred nadaljevanjem
`control/condition`	Razvejite glede na pogoj

Spremenljivke predlog

Uporabite sintakso {{ }} za sklicevanje na podatke:

parameters:
  to: "{{ contact.email }}"
  subject: "Vaše naročilo #{{ order.number }} je bilo odposlano"
  params:
    name: "{{ contact.firstName | default: 'Stranka' }}"
    items: "{{ cart.items | map: 'name' | join: ', ' }}"
    total: "{{ cart.total | currency: 'USD' }}"

Razpoložljivi filtri

Filter	Opis	Primer
`default`	Privzeta vrednost	`{{ name \| default: 'Gost' }}`
`uppercase`	Niz z velikimi črkami	`{{ name \| uppercase }}`
`lowercase`	Niz z malimi črkami	`{{ email \| lowercase }}`
`capitalize`	Prva črka velika	`{{ name \| capitalize }}`
`truncate`	Skrajšaj niz	`{{ desc \| truncate: 100 }}`
`date`	Oblikuj datum	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Oblikuj valuto	`{{ price \| currency: 'EUR' }}`
`map`	Preslika lastnost polja	`{{ items \| map: 'name' }}`
`join`	Združi polje	`{{ tags \| join: ', ' }}`
`first`	Prvi element polja	`{{ items \| first }}`
`last`	Zadnji element polja	`{{ items \| last }}`
`size`	Dolžina polja/niza	`{{ items \| size }}`

Dovoljenja

Določite zahtevana dovoljenja Brevo API:

permissions:
  - contacts:read        # Branje podatkov o stikih
  - contacts:write       # Ustvarjanje/posodabljanje stikov
  - email:send           # Pošiljanje transakcijskih e-poštnih sporočil
  - sms:send             # Pošiljanje SMS sporočil
  - lists:write          # Upravljanje seznamov stikov
  - events:write         # Sledenje dogodkom

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

Izpostavljenost prek orodij MCP

Skills je mogoče izpostaviti kot orodja MCP, kar jih naredi dostopna za klicanje s strani AI agentov. Dodajte polje mcp v vaš frontmatter:

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

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

Kako deluje izpostavljenost prek MCP

Ko ima skill polje mcp, postane orodje, ki ga AI agenti lahko odkrijejo in pokličejo:

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`	niz	Ime orodja MCP (format: `tajo/skill-name`)
`mcp.description`	niz	Opis, prikazan AI agentom med odkrivanjem orodij
`mcp.inputSchema`	objekt	JSON Schema, ki določa vhodne parametre orodja
`mcp.brevo_servers`	polje	Moduli strežnika Brevo MCP, ki jih ta skill potrebuje

Skills vs. neposredna orodja MCP

Vidik	Skill kot orodje MCP	Neposredni Brevo MCP
Abstrakcija	Visoka, agent reče »povrni to košarico«	Nizka, agent mora klicati posamezne Brevo API-je
Kompleksnost	Zajema večstopenjsko logiko	Agent mora orkestrirati vsak korak
Varovala	Vgrajena v skill (pogoji, debounce)	Agent mora implementirati lastna
Primerno za	Ponavljajoče se delovne tokove	Enkratne operacije

Tip

Uporabite Skills kot orodja MCP za kompleksne, večstopenjske delovne tokove, ki jih agenti ne bi smeli vsakič znova iznajdevati. Uporabite neposredna orodja Brevo MCP za enostavne, enkratne operacije, kot je iskanje stika ali pošiljanje enega e-poštnega sporočila.

Kombiniranje Skills in agentov

Agent lahko uporablja tako Skills (kot orodja MCP) kot neposredne module Brevo MCP:

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

To agentom zagotavlja visokonivojsko avtomatizacijo (Skills) za pogoste vzorce, hkrati pa ohranja nizkonivojski dostop (Brevo MCP) za lastno logiko.

Glejte Format specifikacije agenta in Gradnja agentov za popolne podrobnosti.

Najboljše prakse

Tip

Verzionite svoje skills z uporabo semantičnega verzioniranja. Spremembe, ki kršijo združljivost, zahtevajo povečanje glavne verzije.

Ohranjajte skills osredotočene – En skill naj dela eno stvar dobro
Uporabite opisna imena – abandoned-cart-recovery, ne acr
Dokumentirajte pogoje – Pojasnite, zakaj vsak pogoj obstaja
Elegantno obravnavajte napake – Uporabite on_error: continue za nekritična dejanja
Testirajte na majhnih skupinah – Med razvojem uporabite status: experimental
Dodajte izpostavljenost MCP za skills, ki bi jih morali agenti neposredno klicati

Naslednji koraki

Pregled MCP in agentov – Kako se Skills vključijo v agentno arhitekturo
Format specifikacije agenta – Definirajte agente, ki uporabljajo Skills kot orodja
Gradnja agentov – Zgradite svojega prvega marketinškega agenta
Skills sinhronizacije podatkov – Raziščite skills za sinhronizacijo podatkov