Skip to Content
IoT Uygulama GeliştirmeUygulama Skill'leri

Uygulama Skill’leri

Uygulama skill’i, uygulamanızın AI ajanlarından birinin talimatları her turda system_prompt içinde taşımak yerine istek üzerine yüklediği bir talimat kümesidir.

Ajan başlangıçta yalnızca her skill’in adını ve açıklamasını görür. Bir görev bir skill gerektirdiğinde ajan onun talimatlarını yükler. Bir skill, ajan onu yükleyene kadar hiçbir maliyet getirmez; böylece her sohbeti ağırlaştırmadan ajana uzun prosedürler ve referans malzemesi verebilirsiniz.

Uygulama skill’leri, uygulamanın kendi ajanları için yazılmış talimatlardır. Claude Code ile Geliştirme sayfasının kodlama ajanınız için kurduğu skill değildirler.

Skill mi, System Prompt mu?

system_prompt her turda okunur. Bir skill yalnızca ajan onu yüklemeye karar verdiğinde okunur.

system_prompt içine koyunSkill içine koyun
Ajanın rolüYalnızca bazı görevlerin ihtiyaç duyduğu bilgi
Her zaman geçerli olan kurallarUzun prosedürler, örneğin bir arıza teşhisi veya devreye alma kontrolü
Güvenlikle ilgili kurallar: ajanın asla yapmaması gerekenler veya önce onaylaması gerekenlerAlan referansı, örneğin arıza kodları veya bir makinenin parametreleri
Kısa bilgiler

Hiçbir skill yüklemeyen bir ajan da güvenlikle ilgili her kurala uymalıdır; bu yüzden bu kurallar her zaman system_prompt içinde kalır.

Skill Klasörü Biçimi

Skill’ler uygulamanızın deposunda, .ironflock/ içindeki diğer dosyaların yanında bulunur:

.ironflock/ ├── ai-template.yml └── skills/ └── machine-diagnosis/ ├── SKILL.md └── references/ └── codes-press.md
  • .ironflock/skills/<name>/SKILL.md zorunludur. YAML frontmatter ile başlar; ardından Markdown biçiminde talimatlar gelir.
  • .ironflock/skills/<name>/references/<file>.md isteğe bağlıdır. Referans dosyalarını yalnızca bazı görevlerin ihtiyaç duyduğu malzeme için kullanın. Ajan her birini yalnızca o dosyaya ihtiyaç duyduğunda yükler; bu yüzden her referans dosyası tek başına anlamlı olmalıdır. SKILL.md hangi dosyanın ne zaman okunacağını söyler.
  • Skill klasöründe başka hiçbir şey bulunamaz: betik, görsel ve sembolik bağlantı yok. Tüm dosyalar UTF-8 metindir.

Frontmatter iki alandan oluşur:

--- name: machine-diagnosis description: >- How to find out why a machine is TOO_HOT or shows NO_READING. Load it before you answer such a question. ---
AlanAçıklama
nameKlasör adıyla aynı olmalıdır.
descriptionDüz metin. Ajan skill’i yükleyene kadar gördüğü tek şey budur.

Bir Skill’i Ajana Listeleme

Bir skill, bir ajan onu listelemedikçe hiçbir şey yapmaz. .ironflock/ai-template.yml içinde ajana skills anahtarını ekleyin ve her skill’i klasör adıyla yazın:

machines: main: true skills: [machine-diagnosis]

Yalnızca klasör adını yazın. Hiçbir girdiyi app/ veya project/ ile başlatmayın.

Ajana skill app/<name> biçiminde sunulur; burada app/machine-diagnosis. system_prompt veya tool_description içinde bir skill’den söz eden metin bu biçimi kullanır.

Her skill klasörü en az bir ajan tarafından listelenmelidir ve her ajan bir skill’i yalnızca bir kez listeler.

Platform Skill’leri

platform/<name> biçimindeki girdi, platformun uygulamalara sağladığı skill’ler için ayrılmıştır. Henüz hiçbir platform skill’i yoktur; bu yüzden böyle bir girdi bugün sürüm derlemesini başarısız kılar.

Sınırlar

NeSınır
Skill adıKüçük harfler ve rakamlar, tek tire ile birleştirilmiş; en fazla 64 karakter
AçıklamaEn fazla 500 karakter
Talimatlar (SKILL.md)En fazla 20.000 karakter
Tek bir referans dosyasıEn fazla 40.000 karakter
Skill başına referans dosyasıEn fazla 20
Uygulama başına skillEn fazla 20
Bir uygulamanın tüm skill dosyaları birlikteEn fazla 2 MiB
Bir ajanın listelediği skill’lerEn fazla 20

Sürüm Derlemesi Neleri Kontrol Eder

Bir sürüm oluşturduğunuzda derleme, skill’leri ai-template.yml ile birlikte kontrol eder. Bir kontrol başarısız olursa sürüm derlenmez ve bulunan ilk sorun gösterilir. Sorunu düzeltin ve sürümü yeniden oluşturun.

Derleme şu durumlarda başarısız olur:

  • bir ajan, klasörü olmayan bir skill listelediğinde;
  • bir skill klasörü hiçbir ajan tarafından listelenmediğinde;
  • uygulamanın bir skill klasörü olduğu hâlde ai-template.yml dosyası olmadığında;
  • skills içindeki bir girdi app/ veya project/ ile başladığında;
  • bir girdi platform/ ile başladığında (henüz hiçbir platform skill’i yoktur);
  • skill klasöründeki bir dosya UTF-8 metin değilse, sembolik bağlantıysa veya SKILL.md ya da bir references/<file>.md dosyası değilse;
  • yukarıdaki tablodaki bir sınır aşıldığında;
  • bir ajanın load_skill adında bir aracı olduğunda. Ad, skill’leri yüklemek için tüm uygulamalarda ayrılmıştır.

Örnek

Bu skill, ajana bir makinenin neden arıza bildirdiğini nasıl bulacağını anlatır. Burada kısaltılmıştır. Yeni bir uygulama, .ironflock/skills/ içinde okuyabileceğiniz, değiştirebileceğiniz veya kaldırabileceğiniz üç eksiksiz skill ile başlar.

.ironflock/skills/machine-diagnosis/SKILL.md:

--- name: machine-diagnosis description: >- How to find out why a machine is TOO_HOT or shows NO_READING, or what is wrong with a machine a user asks about: which rows to read, when to read the machine now with current_reading, and what to tell the user. Load it before you answer such a question. --- # Diagnosing a machine A user asked why a machine is too hot, why it has no reading, or what is wrong with it. Find the cause in the app's tables and at the machine, then answer with the evidence. You only read: you cannot change the limit or a machine. ## 1. Find the device and its state Run with `execute_sql`: ```sql SELECT DISTINCT ON (device_id) device_id, device_name, state, tsp FROM devices ORDER BY device_id, tsp DESC ``` `state` is `OK`, `TOO_HOT` or `NO_READING`. When the user named no machine, take the devices whose state is not `OK`. ## 2. Check the machine now Call `current_reading` for the device and compare its values with the newest rows of `measurements`. When the call fails, the device is offline: say since when. Do not tell anyone that a machine running too hot is safe to keep running.

Onu listeleyen ajan, .ironflock/ai-template.yml içinde:

machines: main: true tool_description: | Delegate to this agent when the user asks about the state of a machine. system_prompt: | You answer questions about the machines this app watches. You only read. Never tell anyone that a machine running too hot is safe to keep running. When a user asks why a machine is too hot or has no reading, load the skill app/machine-diagnosis and follow it. data_access: true skills: [machine-diagnosis] tools: current_reading: description: Reads the machine at one device now. topic: current_reading

system_prompt içinde “When a user asks” ile başlayan cümle, skill’e app/machine-diagnosis olarak atıfta bulunur. Güvenlik kuralı system_prompt içinde kalır, çünkü skill’i yüklemeyen bir ajan da ona uymak zorundadır.

Skill’leri Sürüm Olmadan Deneyin

Bir ajanı veya skill’i denemek için sürüme ihtiyacınız yoktur. Bulut IDE’nin, kendi çalışma kopyanızı çalıştıran bir geliştirme sohbeti vardır.

Bulut IDE’nin yan panelinde Yapay zeka ajanları bölümünde iki eylem bulunur:

  • Geliştirme sohbetini aç, çalışma kopyanızı uygular ve onu kullanan bir sohbet açar.
  • Yapay zeka ajanlarını güncelle, ai-template.yml dosyasında ve skill’lerde yaptığınız sonraki düzenlemeleri uygular.

Geliştirme sohbeti:

  • uygulamanızın çalışma kopyasını, projenin geliştirme veri arka ucuyla çalıştırır;
  • projenin normal asistanıdır; bu uygulamanın ajanları, araçları ve skill’leri çalışma kopyanızdan alınır;
  • bunları alan tek sohbettir. Başka hiç kimseye ve başka hiçbir sohbete çalışma kopyanız sunulmaz.

Çalışan bir geliştirme sohbeti, bir sonraki mesajından itibaren düzenlemelerinizi kullanır; böylece bir skill’i değiştirebilir, Yapay zeka ajanlarını güncelle’ye tıklayabilir ve aynı sohbette yeniden sorabilirsiniz.

Şablon veya bir skill geçersizse, sürüm derlemesindeki mesajın aynısı gösterilir ve önceki sürüm kullanılmaya devam eder.

Geliştirme sohbeti, seçilen cihazın projesinde uygulamanın geliştirme veri arka ucuna ihtiyaç duyar.

Kullanıcılar Skill’leri Nerede Görür

Studio’da uygulamanın AI eklentisi sekmesi, her ajanı skill’leriyle birlikte listeler ve her skill’in adını ve açıklamasını gösterir. Skill metni orada hiçbir zaman gösterilmez.

Eski Kurulumlar

Henüz güncellenmemiş bir appliance uygulamayı kurar ve çalıştırır. Ajanları skill’ler olmadan çalışır ve bir görev skill gerektirdiğinde bunu kullanıcıya söyler. Appliance güncellendikten sonra skill’ler, uygulamanın bir sonraki eşitlemesiyle gelir.

İyi Skill Yazma

  • Açıklama, skill’in ne için olduğunu ve ne zaman yüklenmesi gerektiğini söyler. Ajan skill’i yükleyene kadar açıklama, gördüğü tek şeydir. Kullanıcıların ve verilerinizin kullandığı sözcükleri, örneğin durum değerlerini, belirtileri ve görevleri kullanın ve skill’in ne zaman yükleneceğini söyleyerek bitirin: “Load it before you answer why a machine is TOO_HOT.” “Information about machines” gibi bir açıklama hiçbir zaman doğru anda yüklenmez.
  • Talimatları kendi içinde yeterli yazın. Ajan onları bir görevin ortasında, bir kullanıcı beklerken okur. system_prompt’a güvenmek yerine uygulamanızın tablolarını, sütunlarını ve araçlarını tam olarak adlandırın.
  • İzlenecek sırayla, emir kipinde adımlar yazın. Ne zaman duracağını ve kullanıcıya ne söyleyeceğini yazın.
  • Neyin yapılmaması gerektiğini yazın.

Sonraki Adımlar

Last updated on