Skills d’application
Un skill d’application est un ensemble d’instructions que l’un des agents IA de votre application charge à la demande, au lieu de les porter à chaque tour dans son system_prompt.
L’agent ne voit d’abord que le nom et la description de chaque skill. Lorsqu’une tâche a besoin d’un skill, l’agent en charge les instructions. Un skill ne coûte rien tant que l’agent ne le charge pas : vous pouvez donc donner à l’agent de longues procédures et de la documentation de référence sans alourdir chaque conversation.
Les skills d’application sont des instructions pour les agents propres à votre application. Ils ne sont pas le skill que Développer avec Claude Code installe pour votre agent de codage.
Skill ou system prompt ?
Le system_prompt est lu à chaque tour. Un skill n’est lu que lorsque l’agent décide de le charger.
À mettre dans le system_prompt | À mettre dans un skill |
|---|---|
| Le rôle de l’agent | Les connaissances dont seules certaines tâches ont besoin |
| Les règles qui s’appliquent toujours | Les longues procédures, comme un diagnostic ou un contrôle de mise en service |
| Les règles de sécurité : ce que l’agent ne doit jamais faire, ou doit d’abord faire confirmer | La documentation de référence du domaine, comme les codes de défaut ou les paramètres d’une machine |
| Les faits courts |
Un agent qui ne charge jamais de skill doit tout de même respecter chaque règle de sécurité : ces règles restent donc toujours dans le system_prompt.
Format du dossier d’un skill
Les skills se trouvent dans le dépôt de votre application, à côté des autres fichiers de .ironflock/ :
.ironflock/
├── ai-template.yml
└── skills/
└── machine-diagnosis/
├── SKILL.md
└── references/
└── codes-press.md.ironflock/skills/<name>/SKILL.mdest obligatoire. Il commence par un en-tête YAML (frontmatter), suivi des instructions en Markdown..ironflock/skills/<name>/references/<file>.mdest facultatif. Utilisez des fichiers de référence pour le contenu dont seules certaines tâches ont besoin. L’agent ne charge chaque fichier que lorsqu’il en a besoin : chaque fichier de référence doit donc être compréhensible seul.SKILL.mdindique quel fichier lire et quand.- Le dossier des skills ne doit rien contenir d’autre : ni scripts, ni images, ni liens symboliques. Tous les fichiers sont du texte UTF-8.
Le frontmatter comporte deux champs :
---
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.
---| Champ | Description |
|---|---|
name | Doit être identique au nom du dossier. |
description | Texte brut. C’est tout ce que l’agent voit tant qu’il n’a pas chargé le skill. |
Déclarer un skill sur un agent
Un skill ne fait rien tant qu’un agent ne le déclare pas. Dans .ironflock/ai-template.yml, ajoutez la clé skills à l’agent et nommez chaque skill par le nom de son dossier :
machines:
main: true
skills: [machine-diagnosis]N’écrivez que le nom du dossier. Ne commencez jamais une entrée par app/ ou project/.
Le skill est proposé à l’agent sous la forme app/<name>, ici app/machine-diagnosis. Le texte de votre system_prompt ou de votre tool_description qui mentionne un skill utilise cette forme.
Chaque dossier de skill doit être déclaré par au moins un agent, et chaque agent déclare un skill une seule fois.
Skills de la plateforme
Une entrée de la forme platform/<name> est réservée aux skills que la plateforme fournit aux applications. Aucun skill de la plateforme n’est encore disponible : une telle entrée fait donc échouer le build de version aujourd’hui.
Limites
| Élément | Limite |
|---|---|
| Nom du skill | Lettres minuscules et chiffres, reliés par des tirets simples ; 64 caractères au plus |
| Description | 500 caractères au plus |
Instructions (SKILL.md) | 20 000 caractères au plus |
| Un fichier de référence | 40 000 caractères au plus |
| Fichiers de référence par skill | 20 au plus |
| Skills par application | 20 au plus |
| Tous les fichiers de skills d’une application ensemble | 2 MiB au plus |
| Skills déclarés par un agent | 20 au plus |
Ce que contrôle le build de version
Lorsque vous créez une version, le build contrôle les skills avec ai-template.yml. Si un contrôle échoue, la version n’est pas construite et le premier problème trouvé est affiché. Corrigez-le et créez à nouveau la version.
Le build échoue lorsque :
- un agent déclare un skill qui n’a pas de dossier ;
- un dossier de skill n’est déclaré par aucun agent ;
- l’application a un dossier de skills mais pas de
ai-template.yml; - une entrée de
skillscommence parapp/ouproject/; - une entrée commence par
platform/(aucun skill de la plateforme n’est encore disponible) ; - un fichier du dossier des skills n’est pas du texte UTF-8, est un lien symbolique, ou n’est ni
SKILL.mdni un fichierreferences/<file>.md; - une limite du tableau ci-dessus est dépassée ;
- un agent a un outil nommé
load_skill. Ce nom est réservé au chargement des skills, dans toutes les applications.
Exemple
Ce skill indique à l’agent comment trouver pourquoi une machine signale un défaut. Il est abrégé ici. Une nouvelle application démarre avec trois skills complets dans .ironflock/skills/, que vous pouvez lire, modifier ou supprimer.
.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.L’agent qui le déclare, dans .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_readingLa phrase du system_prompt qui commence par « When a user asks » désigne le skill sous la forme app/machine-diagnosis. La règle de sécurité reste dans le system_prompt, car un agent qui ne charge pas le skill doit tout de même la respecter.
Essayer les skills sans version
Vous n’avez pas besoin d’une version pour essayer un agent ou un skill. L’IDE cloud dispose d’un chat de développement qui exécute votre propre copie de travail.
Dans le panneau latéral de l’IDE cloud, la section Agents IA propose deux actions :
- Ouvrir le chat de développement applique votre copie de travail et ouvre un chat qui l’utilise.
- Mettre à jour les agents IA applique les modifications suivantes de
ai-template.ymlet des skills.
Le chat de développement :
- exécute votre copie de travail de l’application, avec le backend de données de développement du projet ;
- est l’assistant habituel du projet, avec les agents, les outils et les skills de cette application tirés de votre copie de travail ;
- est le seul chat à les recevoir. Personne d’autre, et aucun autre chat, ne se voit proposer votre copie de travail.
Un chat de développement en cours utilise vos modifications dès son message suivant : vous pouvez donc modifier un skill, cliquer sur Mettre à jour les agents IA et poser à nouveau la question dans le même chat.
Si le template ou un skill est invalide, le même message que pour un build de version s’affiche et la version précédente reste en usage.
Le chat de développement a besoin du backend de données de développement de l’application dans le projet de l’appareil sélectionné.
Où les utilisateurs voient les skills
Dans le Studio, l’onglet Plugin IA de l’application liste chaque agent avec ses skills, en affichant le nom et la description de chaque skill. Le texte du skill n’y est jamais affiché.
Anciennes installations
Une appliance qui n’a pas encore été mise à jour installe l’application et l’exécute. Ses agents fonctionnent sans les skills et le disent à l’utilisateur lorsqu’une tâche en nécessite un. Une fois l’appliance mise à jour, les skills arrivent avec la prochaine synchronisation de l’application.
Écrire de bons skills
- La description dit à quoi sert le skill et quand le charger. Tant que l’agent n’a pas chargé le skill, la description est tout ce qu’il voit. Utilisez les mots de vos utilisateurs et de vos données, comme les valeurs d’état, les symptômes et les tâches, et terminez par le moment où charger le skill : « Load it before you answer why a machine is TOO_HOT. » Une description comme « Information about machines » n’est jamais chargée au bon moment.
- Rendez les instructions autonomes. L’agent les lit au milieu d’une tâche, avec un utilisateur qui attend. Nommez exactement les tables, les colonnes et les outils de votre application au lieu de vous appuyer sur le
system_prompt. - Écrivez des étapes à l’impératif, dans l’ordre où les suivre. Dites quand s’arrêter et ce qu’il faut dire à l’utilisateur.
- Dites ce qu’il ne faut pas faire.
Étapes suivantes
- Agents IA et outils — La référence
ai-template.yml - Versions et l’App Store — Publier votre application