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.

morning-assistant.md
---
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.

MotCe qu’il signifiePar exemple
MUSTUne exigenceask Alex before changing an invitation.
SHOULDUn choix par défaut réfléchikeep the daily brief under 150 words.
MAYUn choix permissuggest a focus task when time is available.
NEVERUne interdictionreveal a private event to another person.
SHOULD NOTUne action déconseilléeplan around it as a confirmed commitment.
Une règle et sa raison
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 :

Une règle avec une condition
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.

Une politique
:::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.
:::
Un garde-fou
:::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.

Une consigne, un exemple et le résultat attendu
:::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).

Une connexion à un outil
:::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.

Une compétence et une référence vers elle
:::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.

Une personne, et une règle qui la nomme
::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.

morning-assistant.md
---
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.