Becerileri Yönetme

Bu eğitimde bir beceri oluşturacak, rehberliğini taşıyan bir sürüm ekleyecek ve asistanın bulup yükleyebilmesi için yayınlayacaksınız.

Beceri bir kimliktir — ad, URL-uyumlu kısa ad, açıklama — ve rehberliği bir sürümde yaşar. İkisinin ayrılması, metnin başka her şeyin atıfta bulunduğu kimliği değiştirmeden düzeltilebilmesini sağlar.

Bir beceri yazmak üç çağrılık bir dizidir ve üçü de zorunludur. Birinci veya ikinci adımda duran bir beceri vardır ama asistana görünmez ve hiçbir yer hata bildirmez; çünkü bir şey ters gitmemiştir — dizi yalnızca tamamlanmamıştır.

Ön Koşullar

Geçerli bir erişim belirteci olan Chainabit hesabı
Becerinin ait olduğu çalışma alanında üyelik
Terminalinizde curl

bash

export BASE_URL="https://api.chainabit.com/api/v1"
export TOKEN="erisim-belirteciniz"
export WORKSPACE_ID="calisma-alani-kimliginiz"

Beceriler çalışma alanı kapsamlıdır. Aşağıdaki her uç nokta çalışma alanı altındadır ve beceri o çalışma alanında asistana görünür — tek bir ajana değil. Beceri yazmak için bir ajana ihtiyacınız yoktur.

Beceri Yapısı

Bir beceri birçok sürüm tutabilir. Katalog en son yayınlananı sunar; önceki sürümler kimlikleriyle sorgulanabilir kalır.

Adım 1: Beceriyi Oluşturun

Kimliği oluşturur. Henüz rehberlik içeriği yoktur.

cURLJavaScriptPython

bash

curl -s -X POST "$BASE_URL/workspaces/$WORKSPACE_ID/ai/skills" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Etkinlik Özetleyici",
    "slug": "etkinlik-ozetleyici",
    "description": "Etkinlik tamamlanma verisinden doğal dilde özetler üretir.",
    "visibility": "workspace"
  }'

javascript

const res = await fetch(
  `${BASE_URL}/workspaces/${WORKSPACE_ID}/ai/skills`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Etkinlik Özetleyici',
      slug: 'etkinlik-ozetleyici',
      description:
        'Etkinlik tamamlanma verisinden doğal dilde özetler üretir.',
      visibility: 'workspace',
    }),
  },
);
const { data } = await res.json();

python

import requests

res = requests.post(
    f"{BASE}/workspaces/{WORKSPACE_ID}/ai/skills",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "name": "Etkinlik Özetleyici",
        "slug": "etkinlik-ozetleyici",
        "description": "Etkinlik tamamlanma verisinden doğal dilde özetler üretir.",
        "visibility": "workspace",
    },
)
data = res.json()["data"]

slug küçük harf, rakam ve tireden oluşmalıdır (^[a-z0-9]+(?:-[a-z0-9]+)*$).

Yeni bir beceri status: "draft" olarak başlar. Taslak beceriler tasarım gereği asistana görünmez — bu, hâlâ yazmakta olduğunuz durumdur.

bash

export SKILL_ID="yukarida donen kimlik"

Adım 2: Rehberliği Taşıyan Sürümü Ekleyin

Sürüm, beceri gövdesini Markdown olarak taşır.

cURLJavaScriptPython

bash

curl -s -X POST \
  "$BASE_URL/workspaces/$WORKSPACE_ID/ai/skills/$SKILL_ID/versions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "versionTag": "1.0.0",
    "skillContent": "# Etkinlik Özetleyici\n\nTamamlanma verisini iki cümlede özetle..."
  }'

javascript

const res = await fetch(
  `${BASE_URL}/workspaces/${WORKSPACE_ID}/ai/skills/${SKILL_ID}/versions`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      versionTag: '1.0.0',
      skillContent:
        '# Etkinlik Özetleyici\n\nTamamlanma verisini iki cümlede özetle...',
    }),
  },
);
const { data } = await res.json();

python

res = requests.post(
    f"{BASE}/workspaces/{WORKSPACE_ID}/ai/skills/{SKILL_ID}/versions",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={
        "versionTag": "1.0.0",
        "skillContent": "# Etkinlik Özetleyici\n\nTamamlanma verisini iki cümlede özetle...",
    },
)
data = res.json()["data"]

İçerik temizlenir (HTML etiketleri kaldırılır) ve 8 KB ile sınırlanır; daha uzunu reddedilmek yerine kırpılır. versionTag beceri başına benzersiz olmalıdır — aynısını yeniden kullanmak 409 Conflict döndürür.

bash

export VERSION_ID="yukarida donen surum kimligi"

Adım 3: Sürümü Yayınlayın

Beceriyi erişilebilir kılan adım yayınlamadır. Sürümü yayınlanmış olarak işaretler ve aynı işlemde üst beceriyi draft durumundan active durumuna taşır.

bash

curl -s -X POST \
  "$BASE_URL/workspaces/$WORKSPACE_ID/ai/skills/$SKILL_ID/versions/$VERSION_ID/publish" \
  -H "Authorization: Bearer $TOKEN"

Bu çağrıdan sonra beceri asistanın kataloğunda hemen görünür. Başka bir çağrı gerekmez — özellikle status ayarlamak için bir PATCH gerekmez.

Görünürlük Nasıl Belirlenir

Asistan becerileri iki sorgu üzerinden okur ve ikisi de aynı anda şu iki koşulu ister:

becerinin status değeri active, ve
becerinin is_published: true olan en az bir sürümü var

Biri diğeri olmadan hiçbir şey döndürmez. Yayınlamanın ikisini tek bir işlemde yazmasının nedeni budur: taslak bir beceri üzerindeki yayınlanmış sürüm ile yayınlanmış sürümü olmayan etkin bir beceri eşit derecede görünmezdir.

Sorgu	Döndürdüğü	Kullanım
Çalışma alanı kataloğu	Ad, kısa ad, açıklama — içerik yok	Her turda sunulan `[Available Skills]` bloğu
Ada göre beceri	İçerik dahil en son yayınlanmış sürümün tamamı	Talep üzerine tek bir beceriyi yükleme

Katalog beceri içeriğini bilinçli olarak dışarıda bırakır. Ad ve açıklamalar her turda sunulacak kadar ucuzdur; gövdeler değildir, bu yüzden yalnızca seçilen beceri için getirilir. Açıklamanın göründüğünden daha önemli olması bu yüzdendir — asistanın beceriyi yükleyip yüklemeyeceğine karar verirken okuduğu şey odur.

Beceri Yaşam Döngüsü

Durum	Anlamı	Asistana görünür mü
`draft`	Yazılıyor	Hayır
`active`	Yayınlandı ve kullanımda	Evet, yayınlanmış bir sürümle
`deprecated`	Yerini bıraktı, geçmiş için tutuluyor	Hayır
`archived`	Emekliye ayrıldı	Hayır

Bir sürümü yayınlamak draft durumunu active yapar. deprecated veya archived bir beceriyi geri getirmez — bunlar bilinçli kararlardır ve yeniden yayınlamak birini geri alma isteği değildir. Böyle bir beceriyi geri getirmek için durumunu açıkça PATCH edin.

Yeni Bir Sürüm Yayınlama

Adım 2 ve 3'ü yeni bir versionTag ile tekrarlayın. Beceri boyunca active kalır ve katalog en son yayınlanan sürümü sunar.

Marketplace'ten Gelen Beceriler

Eklenti marketplace'inden kurulan beceriler, yayınlanmış bir sürüm zaten ekliyken active olarak gelir; hemen kullanılabilirler ve yukarıdaki adımların hiçbirine ihtiyaç duymazlar. Bu sayfadaki dizi, kendi yazdığınız beceriler içindir.

Beceri Paketi Yükleme

Yukarıdaki üç çağrılık dizi, bir beceriyi sıfırdan yazmak içindir. Elinizde zaten bir paket varsa — bir SKILL.md ile ihtiyaç duyduğu betik ve referans dosyaları — POST .../skills/upload tamamını tek bir çağrıda, tek bir işlem (transaction) içinde yayımlar. Burada korunması gereken bir yarım durum yoktur: beceri, sürümü ve dosyaları ya birlikte yazılır ya da hiç yazılmaz.

Dosyalar arşiv olarak değil, metin olarak gönderilir. Bir paketin taşıyabileceği her dosya türü zaten bir metin biçimidir; dolayısıyla bir arşivin taşıyabileceği ve izin listesinin reddetmeyeceği hiçbir şey yoktur. Ayrıca arşivleri sunucu tarafında ayrıştırmak zip-slip ve zip-bomb yüzeyi açar; bu API bilinçli olarak bu yüzeye sahip değildir. Bir .zip ile başlıyorsanız istemci tarafında açıp girdilerini gönderin.

bash

curl -s -X POST "$BASE_URL/workspaces/$WORKSPACE_ID/ai/skills/upload" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      { "path": "SKILL.md", "content": "---\nname: PDF Builder\n---\n\nBir PDF oluştur..." },
      { "path": "scripts/build.py", "content": "print(1)" }
    ]
  }'

Yanıt, neyin oluşturulduğunu bildirir:

json

{
  "data": {
    "skillId": "…",
    "skillVersionId": "…",
    "name": "PDF Builder",
    "slug": "pdf-builder",
    "versionTag": "1.0.0",
    "fileCount": 2,
    "totalBytes": 184,
    "addedVersionToExisting": false
  }
}

Paketin İçermesi Gerekenler

Kural	Sınır
Paket kökünde bir `SKILL.md`	Zorunlu
Dosya türleri	`.md` `.py` `.json` `.txt` `.css` `.csv`
Paket başına dosya	64
Dosya başına bayt	512 KB
Paket başına bayt	4 MB

Yollar göreli olmalı, eğik çizgi kullanmalı ve .. bileşeni içermemelidir. Ortak tek bir sarmalayıcı dizin ayıklanır; böylece bir my-skill/ klasörünün zip'i ile klasörün içinden alınan zip aynı paketi üretir.

Bunlar, eklenti pazar yeri içe aktarıcısının uyguladığı aynı üst sınırlar ve aynı izin listesidir — GitHub'dan kurulan bir paket makinenizden de kurulur, ve tersi.

Ad, Açıklama ve Sürüm

SKILL.md ön bilgisi (frontmatter) bildirdiğinde oradan alınır:

markdown

---
name: PDF Builder
description: Markdown'dan PDF üretir. Belge üretmesi istendiğinde kullanın.
version: 1.2.0
tags: [documents, pdf]
---

İstek gövdesindeki name ve description verildiğinde ön bilgiyi geçersiz kılar. Kısa ad (slug) her zaman sunucuda çözümlenen addan türetilir; istemciden asla kabul edilmez.

Var Olan Bir Beceriyi Yeniden Yükleme

Kısa adı zaten bulunan bir yükleme 409 Conflict döner. Paketi o becerinin yeni bir sürümü olarak yayımlamak için "overwrite": true gönderin — önceki sürüm, ona bağlı olan her şey için olduğu gibi kalır; üst kayıt kullanımdan kaldırılmış veya arşivlenmişse active durumuna döner.

Sürüm etiketi sunucuda seçilir: boştaysa ön bilgideki version, değilse bir sonraki kullanılmamış yama sürümü. Sürüm etiketi beceri başına benzersizdir ve indirdiğiniz dosyadaki etiketi siz seçmediniz; bu yüzden çakışma sizin hatanız sayılmaz.

Kaynak Bilgisi (Provenance)

Yüklenen bir beceri metadata.source: "upload" kaydeder ve hiçbir doğrulama belgesi (attestation) ile doğrulayıcı (validator) taşımaz. Buradaki hiçbir şey sabitlenmiş bir depodan çekilmedi, yayımlanmış bir manifestoya karşı karma (hash) ile doğrulanmadı veya imzalanmadı. Bir doğrulayıcı bildirimi, bir betiğin birinin çıktısı hakkında hüküm vermek üzere çalıştırılıp çalıştırılmayacağına karar verir; yükleyen kişinin kendi paketi hakkında böyle bir iddiada bulunması hiçbir şey kanıtlamaz — bu nedenle yüklemeler doğrulayıcı bildiremez. Pazar yeri içe aktarımları bildirebilir, çünkü paketleri doğrulanmıştır.

Bir Beceriyi ve Dosyalarını Okuma

GET .../skills/:id/detail beceriyi, en yeni sürümünün gövdesini ve paketin dosya ağacını tek bir yanıtta döndürür:

bash

curl -s "$BASE_URL/workspaces/$WORKSPACE_ID/ai/skills/$SKILL_ID/detail" \
  -H "Authorization: Bearer $TOKEN"

Katalog okumasının aksine bu uç nokta yayımlanmış sürümlere göre süzmez: taslak, üzerinde çalışmayı sürdürdüğünüz ve açabilmeniz gereken bir durumdur. Bir kişinin inceleyebileceği ile asistanın yükleyebileceği farklı sorulardır.

Dosya içeriği yanıta dahil edilmez — yalnızca tanımlayıcılar (yol, boyut, özet, tür). Bir paket megabaytlarca tutan onlarca dosya taşıyabilir ve okuyan kişi bunları teker teker açar. İstediğinizi ayrıca çekin:

bash

curl -s -G "$BASE_URL/workspaces/$WORKSPACE_ID/ai/skills/$SKILL_ID/versions/$VERSION_ID/file" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "path=scripts/build.py"

Dosya, bir depolama anahtarıyla değil pakete göreli yoluyla adreslenir ve anahtar sürüm kaydından bulunur. İstemcinin verdiği bir anahtar, yalnızca ona eşlik eden beceri kimliğiyle yetkilendirilmiş biçimde, paylaşımlı depodan rastgele bir nesneyi okuma isteği olurdu.

Yanıtlar 256 KB ile sınırlıdır ve erken kesildiğinde truncated: true döner; böylece kısa bir gösterim asla kısa bir dosya sanılmaz.

Kataloğu Süzme

GET .../skills şunları kabul eder:

Parametre	Değerler
`search`	Ad, kısa ad ve açıklamada büyük/küçük harf duyarsız alt dize
`status`	`draft` `active` `deprecated` `archived`
`source`	`all` `mine` `imported` `system`
`tag`	Birebir etiket eşleşmesi
`sort`	`updated` (varsayılan) `created` `name`
`limit`	1–100, varsayılan 20
`offset`	Varsayılan 0

bash

curl -s -G "$BASE_URL/workspaces/$WORKSPACE_ID/ai/skills" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "search=pdf" \
  --data-urlencode "source=mine" \
  --data-urlencode "sort=updated"

Her satır bir author nesnesi (name, is_you, is_system) ve bir latest_version taşır. is_you sunucuda sizin chainer kimliğinize karşı çözümlenir: istemci kendi görüntüleyenini bilir, becerinin hangi chainer altında yazıldığını değil; ve bir meslektaşınızın yazdığı hesap düzeyindeki bir beceri hesaptaki herkese "Siz" olarak görünmemelidir.

Uç Nokta Referansı

Yöntem	Yol	Amaç
GET	`/workspaces/:workspaceId/ai/skills`	Listeleme; search/status/source/tag/sort ile
GET	`/workspaces/:workspaceId/ai/skills/:id`	Tek beceri kaydı
GET	`/workspaces/:workspaceId/ai/skills/:id/detail`	Beceri + en yeni sürüm gövdesi + dosya ağacı
GET	`/workspaces/:workspaceId/ai/skills/:id/versions/:versionId/file?path=`	Tek bir paket dosyasının metni
POST	`/workspaces/:workspaceId/ai/skills`	Kimliği oluşturma
POST	`/workspaces/:workspaceId/ai/skills/upload`	Tüm paketi tek çağrıda yayımlama
PATCH	`/workspaces/:workspaceId/ai/skills/:id`	Üst veri veya durum güncelleme
DELETE	`/workspaces/:workspaceId/ai/skills/:id`	Silme
GET	`/workspaces/:workspaceId/ai/skills/:skillId/versions`	Sürümleri listeleme
GET	`/workspaces/:workspaceId/ai/skills/:skillId/versions/:versionId`	Tek sürüm
POST	`/workspaces/:workspaceId/ai/skills/:skillId/versions`	Sürüm ekleme
POST	`/workspaces/:workspaceId/ai/skills/:skillId/versions/:versionId/publish`	Yayımlama

Özet

Şunları yaptınız:

Bir beceri oluşturdunuz — adı, kısa adı ve açıklaması
Rehberliği taşıyan bir sürüm eklediniz
Onu yayınladınız; bu beceriyi active ve asistana görünür yaptı

Bir beceriyi bu yolla yazdığınızda üç adım da zorunludur. Birinci veya ikinci adımda bırakılan bir beceri bozuk değildir — taslaktır ve taslaklar bilerek görünmezdir.

Elinizde hazır bir paket varsa, POST .../skills/upload bunun yerine üçünü de tek bir işlemsel çağrıda yapar.

Becerileri Yönetme ​

Ön Koşullar ​

Beceri Yapısı ​

Adım 1: Beceriyi Oluşturun ​

Adım 2: Rehberliği Taşıyan Sürümü Ekleyin ​

Adım 3: Sürümü Yayınlayın ​

Görünürlük Nasıl Belirlenir ​

Beceri Yaşam Döngüsü ​

Yeni Bir Sürüm Yayınlama ​

Marketplace'ten Gelen Beceriler ​

Beceri Paketi Yükleme ​

Paketin İçermesi Gerekenler ​

Ad, Açıklama ve Sürüm ​

Var Olan Bir Beceriyi Yeniden Yükleme ​

Kaynak Bilgisi (Provenance) ​

Bir Beceriyi ve Dosyalarını Okuma ​

Kataloğu Süzme ​

Uç Nokta Referansı ​

Özet ​

Sonraki Adımlar ​

Becerileri Yönetme

Ön Koşullar

Beceri Yapısı

Adım 1: Beceriyi Oluşturun

Adım 2: Rehberliği Taşıyan Sürümü Ekleyin

Adım 3: Sürümü Yayınlayın

Görünürlük Nasıl Belirlenir

Beceri Yaşam Döngüsü

Yeni Bir Sürüm Yayınlama

Marketplace'ten Gelen Beceriler

Beceri Paketi Yükleme

Paketin İçermesi Gerekenler

Ad, Açıklama ve Sürüm

Var Olan Bir Beceriyi Yeniden Yükleme

Kaynak Bilgisi (Provenance)

Bir Beceriyi ve Dosyalarını Okuma

Kataloğu Süzme

Uç Nokta Referansı

Özet

Sonraki Adımlar