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 koyun | Skill içine koyun |
|---|---|
| Ajanın rolü | Yalnızca bazı görevlerin ihtiyaç duyduğu bilgi |
| Her zaman geçerli olan kurallar | Uzun 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ı gerekenler | Alan 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.mdzorunludur. YAML frontmatter ile başlar; ardından Markdown biçiminde talimatlar gelir..ironflock/skills/<name>/references/<file>.mdisteğ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.mdhangi 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.
---| Alan | Açıklama |
|---|---|
name | Klasör adıyla aynı olmalıdır. |
description | Dü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
| Ne | Sınır |
|---|---|
| Skill adı | Küçük harfler ve rakamlar, tek tire ile birleştirilmiş; en fazla 64 karakter |
| Açıklama | En 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 skill | En fazla 20 |
| Bir uygulamanın tüm skill dosyaları birlikte | En fazla 2 MiB |
| Bir ajanın listelediği skill’ler | En 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.ymldosyası olmadığında; skillsiçindeki bir girdiapp/veyaproject/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.mdya da birreferences/<file>.mddosyası değilse; - yukarıdaki tablodaki bir sınır aşıldığında;
- bir ajanın
load_skilladı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_readingsystem_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.ymldosyası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
- Ajan ve Araç Tanımlama —
ai-template.ymlbaşvurusu - Sürümler — Uygulamanızı yayımlayın