Specifikace formátu Skills

Formát skills.md definuje, jak jsou Skills strukturovány, konfigurovány a spouštěny. Tato specifikace zajišťuje konzistentní chování napříč všemi Tajo Skills.

Struktura souboru

Skill je definován v jediném souboru markdown 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...

Pole frontmatter

Povinná pole

Pole	Typ	Popis
`name`	string	Jedinečný identifikátor (kebab-case)
`version`	string	Sémantická verze (např. „2.1.0”)
`description`	string	Krátký popis (max. 160 znaků)
`category`	enum	Jedna z: `data-sync`, `email-marketing`, `sms-whatsapp`, `loyalty`, `analytics`, `integrations`
`triggers`	array	Události, které aktivují tento skill
`actions`	array	Operace, které tento skill může provádět

Volitelná pole

Pole	Typ	Výchozí	Popis
`status`	enum	`stable`	Jedna z: `stable`, `beta`, `experimental`
`brevoEndpoints`	array	`[]`	Používané API endpointy Brevo
`permissions`	array	`[]`	Požadovaná oprávnění Brevo API
`relatedSkills`	array	`[]`	ID souvisejících skills
`featured`	boolean	`false`	Zvýraznění v katalogu skills

Spouštěče

Spouštěče definují, které události aktivují skill.

Spouštěče událostí

triggers:
  - event: cart_abandoned
    conditions:
      - cart_value: "> 50"        # Minimální hodnota košíku
      - items_count: ">= 1"       # Alespoň jedna položka
      - time_since_activity: "> 30m"  # 30 minut nečinnosti
    debounce: 5m                  # Čekání 5 minut před opětovným spuštěním

Plánované spouštěče

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

Webhookové spouštěče

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

Operátory podmínek

Operátor	Popis	Příklad
`=`	Rovná se	`status: "active"`
`!=`	Nerovná se	`status: "!= deleted"`
`>`	Větší než	`cart_value: "> 50"`
`>=`	Větší než nebo rovno	`items: ">= 1"`
`<`	Menší než	`age: "< 30"`
`<=`	Menší než nebo rovno	`quantity: "<= 10"`
`contains`	Řetězec obsahuje	`email: "contains @gmail.com"`
`starts_with`	Předpona řetězce	`name: "starts_with Dr."`
`in`	Hodnota v seznamu	`country: "in US,CA,UK"`

Akce

Akce definují, které operace skill provádí.

Definice akce

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'

Typy akcí

Typ	Popis
`brevo/send-email`	Odeslání transakčního emailu
`brevo/send-sms`	Odeslání SMS zprávy
`brevo/send-whatsapp`	Odeslání zprávy WhatsApp
`brevo/create-contact`	Vytvoření nového kontaktu
`brevo/update-contact`	Aktualizace atributů kontaktu
`brevo/delete-contact`	Smazání kontaktu
`brevo/add-to-list`	Přidání kontaktu do seznamu
`brevo/remove-from-list`	Odebrání kontaktu ze seznamu
`brevo/track-event`	Sledování vlastní události
`http/request`	Provedení HTTP požadavku
`transform/map`	Transformace dat
`control/delay`	Čekání před pokračováním
`control/condition`	Větvení na základě podmínky

Šablonové proměnné

Pro odkazování na data použijte syntaxi {{ }}:

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

Dostupné filtry

Filtr	Popis	Příklad
`default`	Výchozí hodnota	`{{ name \| default: 'Guest' }}`
`uppercase`	Velká písmena	`{{ name \| uppercase }}`
`lowercase`	Malá písmena	`{{ email \| lowercase }}`
`capitalize`	Velké první písmeno	`{{ name \| capitalize }}`
`truncate`	Zkrácení řetězce	`{{ desc \| truncate: 100 }}`
`date`	Formátování data	`{{ date \| date: 'YYYY-MM-DD' }}`
`currency`	Formátování měny	`{{ price \| currency: 'EUR' }}`
`map`	Vlastnost pole	`{{ items \| map: 'name' }}`
`join`	Spojení pole	`{{ tags \| join: ', ' }}`
`first`	První prvek pole	`{{ items \| first }}`
`last`	Poslední prvek pole	`{{ items \| last }}`
`size`	Délka pole/řetězce	`{{ items \| size }}`

Oprávnění

Definujte požadovaná oprávnění Brevo API:

permissions:
  - contacts:read        # Čtení dat kontaktů
  - contacts:write       # Vytváření/aktualizace kontaktů
  - email:send           # Odesílání transakčních emailů
  - sms:send             # Odesílání SMS zpráv
  - lists:write          # Správa seznamů kontaktů
  - events:write         # Sledování událostí

Úplný pří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...

Zpřístupnění jako MCP nástroje

Skills lze zpřístupnit jako MCP nástroje, čímž je lze volat AI agenty. Přidejte pole mcp do vašeho 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
---

Jak funguje zpřístupnění MCP

Když má skill pole mcp, stane se nástrojem, který mohou AI agenti objevit a vyvolat:

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

Pole MCP

Pole	Typ	Popis
`mcp.tool_name`	string	Název MCP nástroje (formát: `tajo/skill-name`)
`mcp.description`	string	Popis zobrazený AI agentům při nalezení nástroje
`mcp.inputSchema`	object	JSON Schema definující vstupní parametry nástroje
`mcp.brevo_servers`	array	Moduly Brevo MCP serveru, které tento skill potřebuje

Skills vs. přímé MCP nástroje

Aspekt	Skill jako MCP nástroj	Přímé Brevo MCP
Abstrakce	Vysoká – agent říká „obnov tento košík”	Nízká – agent musí volat jednotlivé endpointy Brevo
Složitost	Zapouzdřuje vícekrokovou logiku	Agent musí orchestrovat každý krok
Ochrany	Zabudované ve skillu (podmínky, debounce)	Agent si musí implementovat vlastní
Nejlepší pro	Opakující se pracovní postupy	Jednorázové operace

Tip

Používejte Skills jako MCP nástroje pro komplexní, vícekrokové pracovní postupy, které by agenti neměli pokaždé znovu vymýšlet. Přímé Brevo MCP nástroje používejte pro jednoduché, jednorázové operace jako vyhledání kontaktu nebo odeslání jednoho emailu.

Skládání Skills a Agentů

Agent může používat jak Skills (jako MCP nástroje), tak přímé moduly Brevo MCP:

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

To dává agentům vysokoúrovňovou automatizaci (Skills) pro běžné vzory a zároveň zachovává nízkoúrovňový přístup (Brevo MCP) pro vlastní logiku.

Podrobnosti viz Formát specifikace agenta a Vytváření agentů.

Osvědčené postupy

Tip

Verzujte své skills pomocí sémantického verzování. Zpětně nekompatibilní změny vyžadují zvýšení hlavní verze.

Udržujte skills zaměřené – jeden skill by měl dělat jednu věc dobře
Používejte popisné názvy – abandoned-cart-recovery místo acr
Dokumentujte podmínky – vysvětlete, proč každá podmínka existuje
Ošetřujte chyby elegantně – používejte on_error: continue pro nekritické akce
Testujte na malém vzorku – při vývoji používejte status: experimental
Přidejte zpřístupnění MCP pro skills, které by agenti měli být schopni přímo vyvolat

Další kroky

MCP a Agenti – přehled – jak Skills zapadají do agentní architektury
Formát specifikace agenta – definujte agenty, kteří používají Skills jako nástroje
Vytváření agentů – vytvořte svého prvního marketingového agenta
Skills pro synchronizaci dat – prozkoumejte skills pro synchronizaci dat