App-Skills
Ein App-Skill ist eine Sammlung von Anweisungen, die einer der KI-Agenten Ihrer App bei Bedarf lädt, statt sie in jedem Zug im system_prompt mitzuführen.
Der Agent sieht zunächst nur den Namen und die Beschreibung jedes Skills. Braucht eine Aufgabe einen Skill, lädt der Agent dessen Anweisungen. Ein Skill kostet nichts, bis der Agent ihn lädt. So können Sie dem Agenten lange Abläufe und Referenzmaterial mitgeben, ohne jede Unterhaltung schwerer zu machen.
App-Skills sind Anweisungen für die eigenen Agenten Ihrer App. Sie sind nicht der Skill, den Mit Claude Code entwickeln für Ihren Coding-Agenten installiert.
Skill oder System-Prompt?
Der system_prompt wird in jedem Zug gelesen. Ein Skill wird nur gelesen, wenn der Agent entscheidet, ihn zu laden.
In den system_prompt | In einen Skill |
|---|---|
| Die Rolle des Agenten | Wissen, das nur manche Aufgaben brauchen |
| Regeln, die immer gelten | Lange Abläufe, etwa eine Diagnose oder eine Inbetriebnahmeprüfung |
| Sicherheitsrelevante Regeln: was der Agent nie tun darf oder erst bestätigen lassen muss | Fachliches Referenzmaterial, etwa Fehlercodes oder die Parameter einer Maschine |
| Kurze Fakten |
Ein Agent, der nie einen Skill lädt, muss trotzdem jede sicherheitsrelevante Regel einhalten. Diese Regeln bleiben deshalb immer im system_prompt.
Format des Skill-Ordners
Skills liegen im Repository Ihrer App, neben den übrigen Dateien in .ironflock/:
.ironflock/
├── ai-template.yml
└── skills/
└── machine-diagnosis/
├── SKILL.md
└── references/
└── codes-press.md.ironflock/skills/<name>/SKILL.mdist erforderlich. Die Datei beginnt mit YAML-Frontmatter, gefolgt von den Anweisungen in Markdown..ironflock/skills/<name>/references/<file>.mdist optional. Verwenden Sie Referenzdateien für Material, das nur manche Aufgaben brauchen. Der Agent lädt jede Datei nur, wenn er sie braucht, daher muss jede Referenzdatei für sich verständlich sein.SKILL.mdsagt, welche Datei wann zu lesen ist.- Sonst darf nichts im Skills-Ordner liegen: keine Skripte, keine Bilder, keine symbolischen Links. Alle Dateien sind UTF-8-Text.
Das Frontmatter hat zwei Felder:
---
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.
---| Feld | Beschreibung |
|---|---|
name | Muss dem Ordnernamen entsprechen. |
description | Reiner Text. Das ist alles, was der Agent sieht, bis er den Skill lädt. |
Einen Skill bei einem Agenten auflisten
Ein Skill bewirkt nichts, bis ein Agent ihn auflistet. Fügen Sie in .ironflock/ai-template.yml dem Agenten den Schlüssel skills hinzu und nennen Sie jeden Skill mit seinem Ordnernamen:
machines:
main: true
skills: [machine-diagnosis]Schreiben Sie nur den Ordnernamen. Beginnen Sie einen Eintrag nie mit app/ oder project/.
Dem Agenten wird der Skill als app/<name> angeboten, hier app/machine-diagnosis. Text in Ihrem system_prompt oder tool_description, der einen Skill erwähnt, verwendet diese Form.
Jeder Skill-Ordner muss von mindestens einem Agenten aufgelistet werden, und jeder Agent listet einen Skill nur einmal auf.
Plattform-Skills
Ein Eintrag der Form platform/<name> ist für Skills reserviert, die die Plattform Apps bereitstellt. Es ist noch kein Plattform-Skill verfügbar, daher lässt ein solcher Eintrag den Release-Build derzeit fehlschlagen.
Limits
| Was | Limit |
|---|---|
| Skill-Name | Kleinbuchstaben und Ziffern, durch einzelne Bindestriche verbunden; höchstens 64 Zeichen |
| Beschreibung | Höchstens 500 Zeichen |
Anweisungen (SKILL.md) | Höchstens 20.000 Zeichen |
| Eine Referenzdatei | Höchstens 40.000 Zeichen |
| Referenzdateien pro Skill | Höchstens 20 |
| Skills pro App | Höchstens 20 |
| Alle Skill-Dateien einer App zusammen | Höchstens 2 MiB |
| Skills, die ein Agent auflistet | Höchstens 20 |
Was der Release-Build prüft
Wenn Sie ein Release erstellen, prüft der Build die Skills zusammen mit ai-template.yml. Schlägt eine Prüfung fehl, wird das Release nicht gebaut und das erste gefundene Problem angezeigt. Beheben Sie es und erstellen Sie das Release erneut.
Der Build schlägt fehl, wenn:
- ein Agent einen Skill auflistet, zu dem es keinen Ordner gibt;
- ein Skill-Ordner von keinem Agenten aufgelistet wird;
- die App einen Skills-Ordner, aber keine
ai-template.ymlhat; - ein Eintrag in
skillsmitapp/oderproject/beginnt; - ein Eintrag mit
platform/beginnt (es ist noch kein Plattform-Skill verfügbar); - eine Datei im Skills-Ordner kein UTF-8-Text ist, ein symbolischer Link ist oder weder
SKILL.mdnoch eine Dateireferences/<file>.mdist; - ein Limit aus der Tabelle oben überschritten wird;
- ein Agent ein Tool namens
load_skillhat. Der Name ist in jeder App für das Laden von Skills reserviert.
Beispiel
Dieser Skill sagt dem Agenten, wie er herausfindet, warum eine Maschine einen Fehler meldet. Er ist hier gekürzt. Eine neue App startet mit drei vollständigen Skills in .ironflock/skills/, die Sie lesen, ändern oder entfernen können.
.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.Der Agent, der ihn auflistet, in .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_readingDer Satz im system_prompt, der mit „When a user asks“ beginnt, verweist auf den Skill als app/machine-diagnosis. Die Sicherheitsregel bleibt im system_prompt, weil ein Agent, der den Skill nicht lädt, sie trotzdem einhalten muss.
Skills ohne Release ausprobieren
Für einen Agenten oder einen Skill brauchen Sie kein Release. Die Cloud-IDE hat einen Entwicklungs-Chat, der Ihre eigene Arbeitskopie verwendet.
Im Seitenpanel der Cloud-IDE hat der Bereich KI-Agenten zwei Aktionen:
- Entwicklungs-Chat öffnen wendet Ihre Arbeitskopie an und öffnet einen Chat, der sie verwendet.
- KI-Agenten aktualisieren wendet weitere Änderungen an
ai-template.ymlund an den Skills an.
Der Entwicklungs-Chat:
- führt Ihre Arbeitskopie der App aus, mit dem Entwicklungs-Daten-Backend des Projekts;
- ist der normale Assistent des Projekts, mit den Agenten, Tools und Skills dieser App aus Ihrer Arbeitskopie;
- ist der einzige Chat, der sie erhält. Niemandem sonst und keinem anderen Chat wird Ihre Arbeitskopie angeboten.
Ein laufender Entwicklungs-Chat verwendet Ihre Änderungen ab seiner nächsten Nachricht. Sie können also einen Skill ändern, auf KI-Agenten aktualisieren klicken und im selben Chat erneut fragen.
Ist das Template oder ein Skill ungültig, erscheint dieselbe Meldung wie bei einem Release-Build, und die vorherige Version bleibt in Gebrauch.
Der Entwicklungs-Chat braucht das Entwicklungs-Daten-Backend der App im Projekt des ausgewählten Geräts.
Wo Benutzer Skills sehen
Im Studio listet der Tab KI-Plugin der App jeden Agenten mit seinen Skills auf und zeigt Name und Beschreibung jedes Skills. Der Text des Skills wird dort nie angezeigt.
Ältere Installationen
Eine Appliance, die noch nicht aktualisiert wurde, installiert die App und führt sie aus. Ihre Agenten funktionieren ohne die Skills und sagen dem Benutzer das, wenn eine Aufgabe einen braucht. Nach der Aktualisierung der Appliance kommen die Skills mit der nächsten Synchronisation der App an.
Gute Skills schreiben
- Die Beschreibung sagt, wofür der Skill da ist und wann er zu laden ist. Bis der Agent den Skill lädt, ist die Beschreibung alles, was er sieht. Verwenden Sie die Wörter, die Ihre Benutzer und Ihre Daten verwenden, etwa Zustandswerte, Symptome und Aufgaben, und schließen Sie damit, wann der Skill zu laden ist: „Load it before you answer why a machine is TOO_HOT.“ Eine Beschreibung wie „Information about machines“ wird nie im richtigen Moment geladen.
- Machen Sie die Anweisungen in sich geschlossen. Der Agent liest sie mitten in einer Aufgabe, während ein Benutzer wartet. Nennen Sie die Tabellen, Spalten und Tools Ihrer App genau, statt sich auf den
system_promptzu verlassen. - Schreiben Sie Schritte im Imperativ, in der Reihenfolge, in der sie auszuführen sind. Sagen Sie, wann der Agent aufhören soll und was er dem Benutzer sagen soll.
- Sagen Sie, was nicht zu tun ist.
Nächste Schritte
- KI-Agenten & Tools — Die Referenz zu
ai-template.yml - Releases & der App Store — Ihre App veröffentlichen