Skip to Content
Tworzenie aplikacji IoTSkille aplikacji

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_promptUmieść w skillu
Rola agentaWiedza potrzebna tylko do niektórych zadań
Reguły, które obowiązują zawszeDł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.md jest wymagany. Zaczyna się od frontmattera YAML, po którym następują instrukcje w Markdownie.
  • .ironflock/skills/<name>/references/<file>.md jest 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.md mó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. ---
PoleOpis
nameMusi być równe nazwie folderu.
descriptionZwykł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

CoLimit
Nazwa skillaMałe litery i cyfry połączone pojedynczymi myślnikami; najwyżej 64 znaki
OpisNajwyżej 500 znaków
Instrukcje (SKILL.md)Najwyżej 20 000 znaków
Jeden plik referencyjnyNajwyżej 40 000 znaków
Pliki referencyjne na skillNajwyżej 20
Skille na aplikacjęNajwyżej 20
Wszystkie pliki skilli aplikacji razemNajwyżej 2 MiB
Skille wskazane przez jednego agentaNajwyż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 skills zaczyna się od app/ lub project/;
  • 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 plikiem references/<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_reading

Zdanie 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.yml i 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

Last updated on