Le langage
Une instruction est un texte ordinaire. Quelques petits ajouts vous permettent de dire exactement ce qui compte, pour que les personnes puissent la relire et que chaque agent la comprenne de la même façon. Cette visite les présente un par un, avec le même exemple du début à la fin : un assistant qui organise la journée de quelqu’un. Les exemples eux-mêmes sont en anglais, tels qu’ils ont été écrits.
Commencez par du texte simple
L’essentiel d’une instruction est de la prose : à quoi sert l’agent et comment il doit travailler. Un court en-tête, tout en haut, donne au document un titre et une version. Les notes destinées aux personnes, par exemple qui l’a écrit et pourquoi il a changé, vont tout à la fin, et l’agent ne les reçoit jamais.
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---
# Morning assistant
Prepare a useful daily brief.
MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.
---
authors: [Alex]
history:
- summary: Preserve appointment status.
sources:
- { title: Team guidance, uri: ./team.md } Les règles
Une ligne qui commence par l’un de cinq mots est une règle. Le mot indique sa force, et un nom facultatif entre
crochets permet d’y faire référence. BECAUSE:, à la ligne suivante, en donne la raison, ce qui aide
un agent à appliquer la règle avec discernement.
| Mot | Ce qu’il signifie | Par exemple |
|---|---|---|
MUST | Une exigence | ask Alex before changing an invitation. |
SHOULD | Un choix par défaut réfléchi | keep the daily brief under 150 words. |
MAY | Un choix permis | suggest a focus task when time is available. |
NEVER | Une interdiction | reveal a private event to another person. |
SHOULD NOT | Une action déconseillée | plan around it as a confirmed commitment. |
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people. Une règle peut aussi dire quand elle s’applique, entre parenthèses après son mot :
SHOULD NOT (if an invitation is tentative): plan around it as a confirmed commitment.
BECAUSE: the attendee has not accepted yet. Politiques et garde-fous
Les règles qui vont ensemble peuvent être regroupées dans une politique, avec son propre titre, pour être relues, partagées et remplacées d’un seul bloc. Un garde-fou marque une limite qui doit sauter aux yeux de quiconque lit le document.
:::policy{id=calendar title="Calendar policy"}
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.
SHOULD[brief]: keep the daily brief under 150 words.
NEVER[privacy]: reveal a private event to another person.
::: :::guardrail{id=calendar-changes title="Calendar changes"}
Never send, delete, or move an invitation without the owner's approval.
::: Des instructions détaillées
Des règles courtes ne suffisent pas toujours. Vous pouvez ajouter des conditions, un exemple de ce qu’est un bon résultat et la forme de la réponse que vous attendez. Chaque partie est marquée pour ce qu’elle est : l’agent distingue ainsi une consigne d’un exemple, et le lecteur les voit clairement présentées.
:::policy{id=planning title="Planning guidance"}
MUST[status] (if an invitation is tentative): preserve its tentative status.
BECAUSE: an unanswered invitation is not a commitment.
SHOULD[brief]: keep the daily brief under 150 words.
BECAUSE: the owner reads it on a phone.
NEVER[privacy]: reveal private event details to another person.
:::
:::example{title="Preserve the uncertainty"}
Your 09:00 catch-up is tentative. The 11:00 review is confirmed.
:::
:::output{response-format=markdown title="Daily brief"}
Use commitments, one focus task, and open decisions.
::: Les outils
Une instruction peut nommer les outils qu’un agent a le droit d’utiliser, par exemple un agenda connecté via MCP, et dire lesquelles de ses actions sont autorisées. Ici, l’assistant peut lire les événements et les disponibilités (events.list, availability.read), mais ne peut jamais supprimer un événement (events.delete).
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
::: Les compétences
Une compétence est une manière réutilisable d’accomplir une tâche, écrite sous forme d’étapes. Écrivez-la une fois, donnez-lui un nom et faites-y référence partout où elle est utile. Celle-ci s’appelle « Prioritize the day » (établir les priorités de la journée) : choisir une tâche utile et réalisable sur laquelle se concentrer.
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.
1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::
Use :skill[Prioritize the day]{ref=#prioritize}. Les personnes
Les instructions dépendent souvent de personnes : qui est responsable d’une décision, qui doit approuver une modification. Déclarez une personne une fois, et les règles peuvent la désigner par son nom. Quiconque lit le document voit de qui il s’agit, et les outils peuvent créer un lien vers elle.
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}
MUST[approval]: ask :person[Alex]{ref=#owner} before changing an invitation.
BECAUSE: calendar changes affect other people. Tout assembler
Voici l’assistant complet dans un seul fichier : son en-tête, son objectif, une règle, l’agenda qu’il peut utiliser, une compétence, un petit workflow et les notes destinées aux personnes. Ouvrez l’éditeur pour écrire la vôtre ; il affiche le même document sous la forme d’une page que tout le monde peut lire.
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---
# Morning assistant
Prepare a useful daily brief.
MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.
1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::
Use :skill[Prioritize the day]{ref=#prioritize}.
:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
start:
kind: manual
read:
kind: mcp.tool
depends_on:
- start
server: calendar
tool: events.list
timeout: 30s
retry:
max: 2
backoff: 2s
draft:
kind: agent
depends_on:
- read
instruction: Prepare a daily brief. Keep tentative appointments tentative.
review:
kind: human
depends_on:
- draft
question: Accept this daily brief?
schema:
type: string
enum:
- accept
- revise
timeout: 2h
route:
kind: switch
depends_on:
- review
on: "{{ steps.review.output }}"
cases:
accept: accepted
revise: revision
accepted:
kind: finish
depends_on:
- route
output: "{{ steps.draft.output }}"
revision:
kind: finish
depends_on:
- route
status: cancelled
reason: The reviewer requested a revision.
:::
---
authors: [Alex]
history:
- summary: Preserve appointment status.
sources:
- { title: Team guidance, uri: ./team.md } Et ensuite
- Workflows : des processus avec des étapes, des décisions et des validations.
- Concepts : comment les instructions sont versionnées, partagées et suivies.
- La spécification (en anglais) : chaque partie du langage, exactement.