Beceri Format Spesifikasyonu
skills.md formatı, Becerilerin nasıl yapılandırıldığını, yapılandırıldığını ve yürütüldüğünü tanımlar. Bu spesifikasyon tüm Tajo Becerilerinde tutarlı davranışı sağlar.
Dosya Yapısı
Bir beceri, YAML frontmatter içeren tek bir markdown dosyasında tanımlanır:
---name: customer-syncversion: 2.1.0description: Sync customer data to Brevo contactscategory: data-syncstatus: 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...Frontmatter Alanları
Zorunlu Alanlar
| Alan | Tür | Açıklama |
|---|---|---|
name | string | Benzersiz tanımlayıcı (kebab-case) |
version | string | Anlamsal sürüm (ör. “2.1.0”) |
description | string | Kısa açıklama (maks 160 karakter) |
category | enum | Şunlardan biri: data-sync, email-marketing, sms-whatsapp, loyalty, analytics, integrations |
triggers | array | Bu beceriyi etkinleştiren olaylar |
actions | array | Bu becerinin gerçekleştirebileceği işlemler |
Opsiyonel Alanlar
| Alan | Tür | Varsayılan | Açıklama |
|---|---|---|---|
status | enum | stable | Şunlardan biri: stable, beta, experimental |
brevoEndpoints | array | [] | Kullanılan Brevo API uç noktaları |
permissions | array | [] | Gerekli Brevo API izinleri |
relatedSkills | array | [] | İlgili becerilerin kimlikleri |
featured | boolean | false | Beceri kataloğunda öne çıkar |
Tetikleyiciler
Tetikleyiciler, beceriyi hangi olayların etkinleştireceğini tanımlar.
Olay Tetikleyicileri
triggers: - event: cart_abandoned conditions: - cart_value: "> 50" # Minimum cart value - items_count: ">= 1" # At least one item - time_since_activity: "> 30m" # 30 minutes of inactivity debounce: 5m # Wait 5 minutes before re-triggeringZamanlama Tetikleyicileri
triggers: - schedule: "0 9 * * *" # Cron expression (daily at 9am) timezone: "America/New_York" - schedule: every_hour - schedule: every_dayWebhook Tetikleyicileri
triggers: - webhook: /skills/customer-sync/trigger method: POST authentication: api_keyKoşul Operatörleri
| Operatör | Açıklama | Örnek |
|---|---|---|
= | Eşittir | status: "active" |
!= | Eşit değildir | status: "!= deleted" |
> | Büyüktür | cart_value: "> 50" |
>= | Büyük eşittir | items: ">= 1" |
< | Küçüktür | age: "< 30" |
<= | Küçük eşittir | quantity: "<= 10" |
contains | Dize içerir | email: "contains @gmail.com" |
starts_with | Dize öneki | name: "starts_with Dr." |
in | Değer listede | country: "in US,CA,UK" |
Eylemler
Eylemler, becerinin gerçekleştirdiği işlemleri tanımlar.
Eylem Tanımı
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'Eylem Türleri
| Tür | Açıklama |
|---|---|
brevo/send-email | İşlemsel e-posta gönder |
brevo/send-sms | SMS mesajı gönder |
brevo/send-whatsapp | WhatsApp mesajı gönder |
brevo/create-contact | Yeni kişi oluştur |
brevo/update-contact | Kişi özelliklerini güncelle |
brevo/delete-contact | Kişiyi sil |
brevo/add-to-list | Kişiyi listeye ekle |
brevo/remove-from-list | Kişiyi listeden kaldır |
brevo/track-event | Özel olay takip et |
http/request | HTTP isteği yap |
transform/map | Veriyi dönüştür |
control/delay | Devam etmeden önce bekle |
control/condition | Koşula göre dallan |
Şablon Değişkenleri
Verilere başvurmak için {{ }} sözdizimini kullanın:
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' }}"Kullanılabilir Filtreler
| Filtre | Açıklama | Örnek |
|---|---|---|
default | Varsayılan değer | {{ name | default: 'Guest' }} |
uppercase | Dizeyi büyük harfe çevir | {{ name | uppercase }} |
lowercase | Dizeyi küçük harfe çevir | {{ email | lowercase }} |
capitalize | İlk harfi büyüt | {{ name | capitalize }} |
truncate | Dizeyi kes | {{ desc | truncate: 100 }} |
date | Tarihi biçimlendir | {{ date | date: 'YYYY-MM-DD' }} |
currency | Para birimini biçimlendir | {{ price | currency: 'EUR' }} |
map | Dizi özelliğini eşle | {{ items | map: 'name' }} |
join | Diziyi birleştir | {{ tags | join: ', ' }} |
first | İlk dizi öğesi | {{ items | first }} |
last | Son dizi öğesi | {{ items | last }} |
size | Dizi/dize uzunluğu | {{ items | size }} |
İzinler
Gerekli Brevo API izinlerini tanımlayın:
permissions: - contacts:read # Read contact data - contacts:write # Create/update contacts - email:send # Send transactional emails - sms:send # Send SMS messages - lists:write # Manage contact lists - events:write # Track eventsTam Örnek
---name: abandoned-cart-recoveryversion: 3.0.0description: Recover abandoned shopping carts with a multi-step email sequencecategory: email-marketingstatus: 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...MCP Araç Sunumu
Beceriler, yapay zeka ajanları tarafından çağrılabilen MCP araçları olarak sunulabilir. Frontmatter’ınıza mcp alanını ekleyin:
---name: abandoned-cart-recoveryversion: 3.0.0description: Recover abandoned shopping carts with a multi-step email sequencecategory: email-marketing
# MCP Configurationmcp: 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---MCP Sunumu Nasıl Çalışır
Bir becerinin mcp alanı varsa, yapay zeka ajanlarının keşfedebileceği ve çağırabileceği bir araç haline gelir:
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 initiatedMCP Alanları
| Alan | Tür | Açıklama |
|---|---|---|
mcp.tool_name | string | MCP araç adı (format: tajo/skill-name) |
mcp.description | string | Araç keşfi sırasında yapay zeka ajanlarına gösterilen açıklama |
mcp.inputSchema | object | Aracın girdi parametrelerini tanımlayan JSON Schema |
mcp.brevo_servers | array | Bu becerinin hangi Brevo MCP sunucu modüllerine ihtiyacı olduğu |
Beceriler ve Doğrudan MCP Araçları Karşılaştırması
| Unsur | MCP Aracı Olarak Beceri | Doğrudan Brevo MCP |
|---|---|---|
| Soyutlama | Yüksek, ajan “bu sepeti kurtar” der | Düşük, ajan her Brevo uç noktasını ayrı ayrı çağırmalı |
| Karmaşıklık | Çok adımlı mantığı kapsar | Ajan her adımı koordine etmeli |
| Güvenlikler | Beceriye yerleşiktir (koşullar, debounce) | Ajan kendi güvenliklerini uygulamalı |
| En İyi Kullanım | Tekrarlanabilir iş akışları | Anlık işlemler |
Tip
Ajanların her seferinde yeniden icat etmemesi gereken karmaşık, çok adımlı iş akışları için Becerileri MCP araçları olarak kullanın. Bir kişiyi aramak veya tek bir e-posta göndermek gibi basit, tek seferlik işlemler için doğrudan Brevo MCP araçlarını kullanın.
Becerileri ve Ajanları Birleştirme
Bir ajan hem Becerileri (MCP araçları olarak) hem de doğrudan Brevo MCP modüllerini kullanabilir:
# Agent spec---name: retention-agenttools: # 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---Bu, ajanlara ortak desenler için yüksek seviyeli otomasyon (Beceriler) sağlarken özel mantık için düşük seviyeli erişimi (Brevo MCP) korur.
Tam ayrıntılar için Ajan Spesifikasyon Formatı ve Ajanlar Oluşturma bölümlerine bakın.
En İyi Uygulamalar
Tip
Semantik sürümleme kullanarak becerilerinizi sürümleyin. Kırıcı değişiklikler büyük sürüm artışı gerektirir.
- Becerileri odaklı tutun - Bir beceri bir şeyi iyi yapmalıdır
- Açıklayıcı adlar kullanın -
acrdeğilabandoned-cart-recovery - Koşulları belgeleyin - Her koşulun neden var olduğunu açıklayın
- Hataları zarifçe yönetin - Kritik olmayan eylemler için
on_error: continuekullanın - Küçük kitlelerle test edin - Geliştirme sırasında
status: experimentalkullanın - Ajanların doğrudan çağırabilmesi gereken beceriler için MCP sunumu ekleyin
Sonraki Adımlar
- MCP ve Ajanlar Genel Bakışı - Becerilerin ajansal mimariye nasıl uyduğu
- Ajan Spesifikasyon Formatı - Becerileri araç olarak kullanan ajanları tanımlayın
- Ajanlar Oluşturma - İlk pazarlama ajanınızı oluşturun
- Veri Senkronizasyonu Becerileri - Veri senkronizasyonu becerilerini keşfedin