Skip to Content

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’agentLes connaissances dont seules certaines tâches ont besoin
Les règles qui s’appliquent toujoursLes 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 confirmerLa 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.md est obligatoire. Il commence par un en-tête YAML (frontmatter), suivi des instructions en Markdown.
  • .ironflock/skills/<name>/references/<file>.md est 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.md indique 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. ---
ChampDescription
nameDoit être identique au nom du dossier.
descriptionTexte 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émentLimite
Nom du skillLettres minuscules et chiffres, reliés par des tirets simples ; 64 caractères au plus
Description500 caractères au plus
Instructions (SKILL.md)20 000 caractères au plus
Un fichier de référence40 000 caractères au plus
Fichiers de référence par skill20 au plus
Skills par application20 au plus
Tous les fichiers de skills d’une application ensemble2 MiB au plus
Skills déclarés par un agent20 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 skills commence par app/ ou project/ ;
  • 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.md ni un fichier references/<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_reading

La 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.yml et 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

Last updated on