Skip to Content

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_promptIn einen Skill
Die Rolle des AgentenWissen, das nur manche Aufgaben brauchen
Regeln, die immer geltenLange Abläufe, etwa eine Diagnose oder eine Inbetriebnahmeprüfung
Sicherheitsrelevante Regeln: was der Agent nie tun darf oder erst bestätigen lassen mussFachliches 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.md ist erforderlich. Die Datei beginnt mit YAML-Frontmatter, gefolgt von den Anweisungen in Markdown.
  • .ironflock/skills/<name>/references/<file>.md ist 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.md sagt, 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. ---
FeldBeschreibung
nameMuss dem Ordnernamen entsprechen.
descriptionReiner 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

WasLimit
Skill-NameKleinbuchstaben und Ziffern, durch einzelne Bindestriche verbunden; höchstens 64 Zeichen
BeschreibungHöchstens 500 Zeichen
Anweisungen (SKILL.md)Höchstens 20.000 Zeichen
Eine ReferenzdateiHöchstens 40.000 Zeichen
Referenzdateien pro SkillHöchstens 20
Skills pro AppHöchstens 20
Alle Skill-Dateien einer App zusammenHöchstens 2 MiB
Skills, die ein Agent auflistetHö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.yml hat;
  • ein Eintrag in skills mit app/ oder project/ 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.md noch eine Datei references/<file>.md ist;
  • ein Limit aus der Tabelle oben überschritten wird;
  • ein Agent ein Tool namens load_skill hat. 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_reading

Der 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.yml und 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_prompt zu 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

Last updated on