Skill yazmak

İskeletle başlayın

ivralo skills create deploy-checks --agent coder

Bu komut local rafa, ilk hâliyle bile doğrulamadan geçen bir skill yazar ve aynı adımda onu coder preset'ine atar. --agent vermezseniz skill kendine ait bir uzmanla çalışır (bkz. Skill'ler nasıl çalışır).

Ad küçük harf, rakam ve tek tirelerden oluşur, en fazla 64 karakter olabilir ve iki rafta da daha önce kullanılmamış olmalıdır. --shipped ile --agent birlikte kullanılamaz: shipped bir skill'in sahibini roster'daki preset'in skills= listesi belirler; komut bu düzenlemeyi sizin için ekrana basar.

SKILL.md dosyası

SKILL.md, iki --- satırı arasındaki YAML frontmatter'dan ve onun ardından gelen markdown gövdeden oluşur. İskelet şunu yazar:

---
name: "deploy-checks"
description: "TODO: what this skill teaches and when to load it. State the trigger ('Load when the user ...') and draw the boundary: Do NOT load it for jobs another skill owns - name that skill instead."
metadata:
  ivralo:
    capabilities: []
---

# deploy-checks

TODO: the technique this skill teaches - when to use it, the hard rules,
worked code the agent can adapt.

## Steps

1. TODO

ivralo'nun tanıdığı frontmatter anahtarları şunlardır: name, description, metadata, license, compatibility ve allowed-tools. Bunların dışındaki her anahtar lint uyarısı verir. name, klasörün adıyla aynı olmalıdır.

Açıklamayı tırnak içine alın

Frontmatter YAML'dır. Açıklamalarda neredeyse her zaman iki nokta üst üste bulunur ve iki nokta üst üste içeren tırnaksız bir değer geçerli YAML değildir. Böyle olunca skill yüklenmez ve bunu size başka hiçbir şey söylemez. O yüzden açıklamayı her zaman çift tırnak içine alın.

Açıklamayı dizin için yazın

Ajan skill'i açana kadar yalnızca açıklamayı görür. Bu yüzden açıklama üç şeyi söylemelidir:

• skill'in ne öğrettiğini, hem de ilk cümlede (diğer uzmanlar yalnızca bu cümleyi görür);
• ne zaman yükleneceğini: "Load when the user asks ...";
• ne zaman yüklenmeyeceğini: "Do NOT load for ...", o işin sahibi olan skill'in adını vererek.

Açıklama 120 karakterden kısaysa ya da "yükleme" sınırı çizmiyorsa lint uyarı verir.

Gövde

Ajan, skill'in işe yarayacağına karar verdiğinde gövdeyi okur. Gövdeyi tekniğe ayırın: adımlar, kolayca yanlış uygulanan kurallar ve ajanın uyarlayabileceği kısa, çalışan kod. Tek başına modelin bağlam penceresinin dörtte birinden fazlasını kaplayan bir gövde lint uyarısı verir. Uzun içeriği references/'a taşıyın ve gövdede ne zaman okunması gerektiğini yazın.

Script'ler

Script, scripts/ içindeki bir Python dosyasıdır. Ajan onu kendi Python'undan, worker'ın içinde, ivralo.engine'deki run_skill_script ile çalıştırır:

from ivralo.engine import run_skill_script

run_skill_script("deploy-checks", "check_manifest.py", "deploy/manifest.yaml")

run_skill_script script'i, skill'in bulunduğu rafta bulur, çalışma ortamının yorumlayıcısıyla çalıştırır ve çıktısını ekrana basar; çıktı modele bu yolla ulaşır. Argümanlar script'in komut satırı argümanlarıdır; içlerindeki dosya adları çalışma alanına göredir. 120 saniyeden uzun süren script durdurulur. Sıfırdan farklı bir çıkış kodu ise, çıktı basıldıktan sonra hata fırlatır.

Bundan iki kural çıkar:

• çağıranın görmesi gereken her şeyi basın; geriye yalnızca basılan çıktı döner;
• ajana bir script'i göreli yolla çalıştırmasını hiçbir zaman söylemeyin; raf çalışma alanında değildir.

Script'ler ivralo'nun kendi sürecinde değil, worker'da ve yazma korumasının altında çalışır. Script içeren bir skill'i kurmadan önce script'leri okuyun.

Başvuru notları

references/ içindeki dosyalar, ajanın yalnızca gövde onu oraya yönlendirdiğinde okuduğu daha uzun belgelerdir. O ana kadar hiçbir maliyetleri yoktur.

Skill'in kendi uzmanı için yetkiler

metadata.ivralo.capabilities, skill kendine ait bir uzmanla çalıştığında istediği yetkileri listeler. İskelet bu listeyi boş bırakır, çünkü çoğu skill temel yetkilerden fazlasına ihtiyaç duymaz: worker'da Python, çalışma alanının dosyaları ve size soru sorabilmek. Adlar Yetenekler sayfasındaki listeden seçilir; bilinmeyen bir ad lint hatasıdır.

Lint

ivralo skills lint deploy-checks

Bu komut skill'leri, her biri bir zamanlar birine bir debug oturumuna mal olmuş hatalar için tarar. Ad vermezseniz iki rafı da tarar.

Bulgular hiçbir şeyi engellemez. Kurulum sırasında onay sorulmadan önce gösterilir, ivralo doctor da listeler; gerisini aşağıdaki seçeneklerle değiştirebilirsiniz:

Yüklendiğini kontrol edin

ivralo skills

Bu komut skill'i rafıyla ve doğrulamadan geçip geçmediğiyle birlikte gösterir. Yeni bir oturum başlatın ya da /new yazın; ekip skill'i kullanmaya başlar.