Skille aplikacji
Skill aplikacji to zestaw instrukcji, który jeden z agentów AI Twojej aplikacji ładuje na żądanie, zamiast nosić je w system_prompt w każdej turze.
Agent widzi najpierw tylko nazwę i opis każdego skilla. Gdy zadanie wymaga skilla, agent ładuje jego instrukcje. Skill nic nie kosztuje, dopóki agent go nie załaduje, więc możesz dać agentowi długie procedury i materiały referencyjne, nie obciążając każdej rozmowy.
Skille aplikacji to instrukcje dla agentów samej aplikacji. Nie są to skille, które Twórz z Claude Code instaluje dla Twojego agenta do programowania.
Skill czy prompt systemowy?
system_prompt jest czytany w każdej turze. Skill jest czytany dopiero wtedy, gdy agent zdecyduje się go załadować.
Umieść w system_prompt | Umieść w skillu |
|---|---|
| Rola agenta | Wiedza potrzebna tylko do niektórych zadań |
| Reguły, które obowiązują zawsze | Długie procedury, na przykład diagnoza lub kontrola uruchomienia |
| Reguły istotne dla bezpieczeństwa: czego agent nigdy nie może robić lub co musi najpierw potwierdzić | Materiały referencyjne dziedziny, na przykład kody usterek lub parametry maszyny |
| Krótkie fakty |
Agent, który nigdy nie ładuje skilla, nadal musi przestrzegać wszystkich reguł istotnych dla bezpieczeństwa, dlatego zawsze pozostają one w system_prompt.
Format folderu skilli
Skille znajdują się w repozytorium Twojej aplikacji, obok pozostałych plików w .ironflock/:
.ironflock/
├── ai-template.yml
└── skills/
└── machine-diagnosis/
├── SKILL.md
└── references/
└── codes-press.md.ironflock/skills/<name>/SKILL.mdjest wymagany. Zaczyna się od frontmattera YAML, po którym następują instrukcje w Markdownie..ironflock/skills/<name>/references/<file>.mdjest opcjonalny. Używaj plików referencyjnych dla materiału potrzebnego tylko do niektórych zadań. Agent ładuje każdy z nich dopiero wtedy, gdy potrzebuje tego pliku, więc każdy plik referencyjny musi być zrozumiały sam w sobie.SKILL.mdmówi, który plik przeczytać i kiedy.- W folderze skilli nie może być niczego innego: żadnych skryptów, obrazów ani dowiązań symbolicznych. Wszystkie pliki są tekstem UTF-8.
Frontmatter ma dwa pola:
---
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.
---| Pole | Opis |
|---|---|
name | Musi być równe nazwie folderu. |
description | Zwykły tekst. Tylko to widzi agent, dopóki nie załaduje skilla. |
Wskazywanie skilla w agencie
Skill nic nie robi, dopóki agent go nie wskaże. W .ironflock/ai-template.yml dodaj agentowi klucz skills i podaj każdy skill przez nazwę jego folderu:
machines:
main: true
skills: [machine-diagnosis]Zapisz tylko nazwę folderu. Nigdy nie zaczynaj wpisu od app/ ani project/.
Agent otrzymuje skill jako app/<name>, tutaj app/machine-diagnosis. Tekst w Twoim system_prompt lub tool_description, który wspomina skill, używa tej formy.
Każdy folder skilla musi być wskazany przez co najmniej jednego agenta, a każdy agent wskazuje dany skill tylko raz.
Skille platformy
Wpis w postaci platform/<name> jest zarezerwowany dla skilli, które platforma udostępnia aplikacjom. Żaden skill platformy nie jest jeszcze dostępny, więc taki wpis powoduje dziś błąd builda wydania.
Limity
| Co | Limit |
|---|---|
| Nazwa skilla | Małe litery i cyfry połączone pojedynczymi myślnikami; najwyżej 64 znaki |
| Opis | Najwyżej 500 znaków |
Instrukcje (SKILL.md) | Najwyżej 20 000 znaków |
| Jeden plik referencyjny | Najwyżej 40 000 znaków |
| Pliki referencyjne na skill | Najwyżej 20 |
| Skille na aplikację | Najwyżej 20 |
| Wszystkie pliki skilli aplikacji razem | Najwyżej 2 MiB |
| Skille wskazane przez jednego agenta | Najwyżej 20 |
Co sprawdza build wydania
Podczas tworzenia wydania build sprawdza skille razem z ai-template.yml. Jeśli kontrola się nie powiedzie, wydanie nie zostanie zbudowane i zostanie pokazany pierwszy znaleziony problem. Popraw go i utwórz wydanie ponownie.
Build kończy się błędem, gdy:
- agent wskazuje skill, który nie ma folderu;
- folder skilla nie jest wskazany przez żadnego agenta;
- aplikacja ma folder skilli, ale nie ma
ai-template.yml; - wpis w
skillszaczyna się odapp/lubproject/; - wpis zaczyna się od
platform/(żaden skill platformy nie jest jeszcze dostępny); - plik w folderze skilli nie jest tekstem UTF-8, jest dowiązaniem symbolicznym albo nie jest ani
SKILL.md, ani plikiemreferences/<file>.md; - przekroczony jest limit z powyższej tabeli;
- agent ma narzędzie o nazwie
load_skill. Nazwa jest zarezerwowana dla ładowania skilli, we wszystkich aplikacjach.
Przykład
Ten skill mówi agentowi, jak ustalić, dlaczego maszyna zgłasza usterkę. Tutaj jest skrócony. Nowa aplikacja zaczyna od trzech kompletnych skilli w .ironflock/skills/, które możesz przeczytać, zmienić lub usunąć.
.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.Agent, który go wskazuje, w .ironflock/ai-template.yml:
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_readingZdanie w system_prompt, które zaczyna się od “When a user asks”, odnosi się do skilla jako app/machine-diagnosis. Reguła bezpieczeństwa pozostaje w system_prompt, ponieważ agent, który nie ładuje skilla, nadal musi jej przestrzegać.
Wypróbuj skille bez wydania
Nie potrzebujesz wydania, aby wypróbować agenta lub skill. IDE w chmurze ma czat deweloperski, który działa na Twojej własnej kopii roboczej.
W panelu bocznym IDE w chmurze sekcja Agenci AI ma dwie akcje:
- Otwórz czat deweloperski stosuje Twoją kopię roboczą i otwiera czat, który jej używa.
- Zaktualizuj agentów AI stosuje dalsze zmiany w
ai-template.ymli w skillach.
Czat deweloperski:
- uruchamia Twoją kopię roboczą aplikacji, z deweloperskim backendem danych projektu;
- jest zwykłym asystentem projektu, z agentami, narzędziami i skillami tej aplikacji wziętymi z Twojej kopii roboczej;
- jest jedynym czatem, który je dostaje. Nikt inny i żaden inny czat nie otrzymuje Twojej kopii roboczej.
Działający czat deweloperski używa Twoich zmian od następnej wiadomości, więc możesz zmienić skill, kliknąć Zaktualizuj agentów AI i zapytać ponownie w tym samym czacie.
Jeśli szablon lub skill jest nieprawidłowy, pokazywany jest ten sam komunikat co przy buildzie wydania, a poprzednia wersja pozostaje w użyciu.
Czat deweloperski wymaga deweloperskiego backendu danych aplikacji w projekcie wybranego urządzenia.
Gdzie użytkownicy widzą skille
W Studio zakładka Wtyczka AI aplikacji wyświetla każdego agenta wraz z jego skillami, pokazując nazwę i opis każdego skilla. Tekst skilla nigdy nie jest tam pokazywany.
Starsze instalacje
Appliance, który nie został jeszcze zaktualizowany, instaluje aplikację i ją uruchamia. Jej agenci działają bez skilli i informują o tym użytkownika, gdy zadanie ich wymaga. Po zaktualizowaniu appliance skille docierają przy następnej synchronizacji aplikacji.
Pisanie dobrych skilli
- Opis mówi, do czego służy skill i kiedy go załadować. Dopóki agent nie załaduje skilla, opis jest wszystkim, co widzi. Używaj słów, których używają użytkownicy i Twoje dane, takich jak wartości stanu, objawy i zadania, a na końcu napisz, kiedy załadować skill: “Load it before you answer why a machine is TOO_HOT.” Opis w rodzaju “Information about machines” nigdy nie zostanie załadowany w odpowiednim momencie.
- Pisz instrukcje samowystarczalne. Agent czyta je w środku zadania, gdy użytkownik czeka. Podawaj dokładne nazwy tabel, kolumn i narzędzi Twojej aplikacji zamiast polegać na
system_prompt. - Pisz kroki w trybie rozkazującym, w kolejności, w jakiej mają być wykonane. Napisz, kiedy przestać i co powiedzieć użytkownikowi.
- Napisz, czego nie robić.
Następne kroki
- Definiowanie agentów i narzędzi — Dokumentacja
ai-template.yml - Wydania — Opublikuj swoją aplikację