Spécification de langage open source
Des instructions en Markdown pour les agents d’IA.
instruction.md est un format ouvert pour expliquer aux agents d’IA comment travailler. Un seul fichier Markdown réunit les règles que l’agent doit suivre, les outils et les compétences qu’il peut utiliser, et les workflows qu’il exécute. Vous le lisez et le relisez comme un document clair, et les agents suivent exactement le même texte. Écrivez-le une fois, puis utilisez-le avec les agents que vous avez déjà.
Agents pris en charge
Utilisez vos instructions avec les agents dont vous vous servez.
Markdown lisible, exports propres à chaque agent ou connexions MCP. La prise en charge de la syntaxe enrichie et des intégrations varie selon l’hôte.
Vous découvrez ?
Commencez par un guide
Une courte vidéo, une tâche à suivre pas à pas et une lecture rapide. Quelques minutes chacun, et le premier ne demande aucun compte. Tous les guides
-
Vidéo · 2 min Écrivez votre première instruction Regardez une instruction s’écrire dans l’éditeur, de la page blanche aux règles que suit un agent. Aucun compte n’est nécessaire. -
Pas à pas · 5 min Publiez-la et connectez un agent Connectez-vous, publiez votre instruction et dirigez un agent d’IA vers elle pour qu’il suive ce que vous avez écrit. -
Lecture rapide · 3 min Comment fonctionnent les versions Pourquoi votre brouillon ne surprend jamais un agent : les brouillons, les versions et ce que signifie « en ligne ».
Écrit une fois. Compris par tous.
morning-assistant.md:::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.
::: Policy calendar
Calendar policy
ask Alex before changing an invitation.
calendar changes affect other people.
keep the daily brief under 150 words.
reveal a private event to another person.
:::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.
::: MCP server calendar
Calendar
Read appointments for planning. Ask Alex before changing an invitation.
events.listAllowedavailability.readAllowedevents.deleteDenied:::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}. Skill prioritize
Prioritize the day
Choose one useful, achievable focus task.
- Review commitments and available focus time.
- Choose one useful, achievable task.
- Explain why it is a good first priority.
Use Prioritize the day.
Du texte simple, facile à relire. Un sens structuré qu’un outil compatible conserve intact.
Télécharger l’exemplePourquoi instruction.md ?
Le détail qu’il faut aux agents.
La clarté qu’il faut aux personnes.
La configuration d’un agent est souvent éparpillée entre des prompts, des réglages, des fichiers de compétences et le savoir de l’équipe. Réunissez les consignes dans un document réutilisable, que chacun peut lire et que les outils compatibles interprètent de la même façon.
Assez de détail pour être utile.
Gardez ensemble l’intention, le contexte, les exceptions, les exemples et les justifications. Donnez à des consignes précises une structure à laquelle un agent peut se référer.
Un sens qui survit à l’analyse.
Nommez les règles, définissez les objets et conservez les origines. Un outil compatible distingue une exigence d’une recommandation, et une référence d’une autorisation d’outil.
Un document que l’on peut relire.
Affichez les autorisations, les workflows, les personnes et les compétences dans leur contexte. Rendez l’instruction compréhensible pour celles et ceux qui l’écrivent, l’approuvent et la maintiennent.
Écrivez-la. Relisez-la. Réutilisez-la d’un agent à l’autre.
Explorer de vrais exemples d’instructionsInstructions détaillées
Assez de détail
pour porter votre intention.
Une instruction peut être brève ou très détaillée. Donnez à l’agent les conditions, les raisons, les exemples et le contexte dont il a besoin. Le langage rend ce détail explicite ; une vue de lecture soignée le rend facile à parcourir.
Planning guidance Policy
preserve its tentative status.
an unanswered invitation is not a commitment.
keep the daily brief under 150 words.
the owner reads it on a phone.
reveal private event details to another person.
Your 09:00 catch-up is tentative. The 11:00 review is confirmed.
Commitments · One focus task · Open decisions
Le détail fait partie du sens voulu par l’auteur. La mise en page peut l’organiser ; un outil de lecture le conserve.
Exemples d’instructions
Des responsabilités différentes.
Un langage commun.
Un assistant personnel, un partenaire de recherche ou toute une équipe peuvent partir du même format. Choisissez une instruction, puis passez de sa vue de lecture au Markdown qui se trouve derrière.
Choisissez une instruction
Découvrez les consignes dont chaque rôle a besoin.
A thoughtful start to the day
Prepare a useful daily brief from commitments and available focus time.
preserve tentative appointment status.
an unanswered invitation is not a commitment.
ask the owner before changing an invitation.
Skill
Prioritize the day
Choose one useful, achievable focus task.
- Review commitments and available time.
- Choose one achievable task.
- Explain why it is a good first priority.
---
spec: "1"
title: Personal assistant
version: "1.0.0"
---
# A thoughtful start to the day
Prepare a useful daily brief from commitments and available focus time.
MUST[status]: preserve tentative appointment status.
BECAUSE: an unanswered invitation is not a commitment.
MUST[approval]: ask the owner before changing an invitation.
:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.
1. Review commitments and available time.
2. Choose one achievable task.
3. Explain why it is a good first priority.
::: Research that can be reviewed
Prepare a brief that helps a reader understand the evidence and its limits.
distinguish sourced facts from your own inference.
a reader needs to assess the basis of each conclusion.
invent a source, quotation, or citation.
Output
Research brief
Make the reasoning easy to follow.
- A summary with source links.
- Findings and the evidence behind them.
- Open questions and limitations.
---
spec: "1"
title: Research partner
version: "1.0.0"
---
# Research that can be reviewed
Prepare a brief that helps a reader understand the evidence and its limits.
MUST[evidence]: distinguish sourced facts from your own inference.
BECAUSE: a reader needs to assess the basis of each conclusion.
NEVER[citations]: invent a source, quotation, or citation.
:::output{response-format=markdown title="Research brief"}
Make the reasoning easy to follow.
- A summary with source links.
- Findings and the evidence behind them.
- Open questions and limitations.
::: A review with a clear purpose
Review a proposed change for defects that affect its behavior.
report defects you can substantiate from the change and its context.
identify the relevant file and line for each finding.
precise locations make a review easier to act on.
Output
Review findings
Keep each finding specific and actionable.
- The file and line involved.
- The defect and its practical impact.
- A suggested correction when one is clear.
---
spec: "1"
title: Code reviewer
version: "1.0.0"
---
# A review with a clear purpose
Review a proposed change for defects that affect its behavior.
MUST[findings]: report defects you can substantiate from the change and its context.
SHOULD[location]: identify the relevant file and line for each finding.
BECAUSE: precise locations make a review easier to act on.
:::output{response-format=markdown title="Review findings"}
Keep each finding specific and actionable.
- The file and line involved.
- The defect and its practical impact.
- A suggested correction when one is clear.
::: A shared product working brief
Turn an approved goal into a proposal the team can review and implement.
distinguish confirmed requirements from assumptions.
ask Alex before changing approved scope.
the product owner decides changes to the agreed goal.
Output
Proposal structure
Make the next decision clear.
- The goal and confirmed constraints.
- A proposal with acceptance criteria.
- Open decisions for the product owner.
---
spec: "1"
title: Product team
version: "1.0.0"
---
# A shared product working brief
Turn an approved goal into a proposal the team can review and implement.
MUST[assumptions]: distinguish confirmed requirements from assumptions.
MUST[scope]: ask Alex before changing approved scope.
BECAUSE: the product owner decides changes to the agreed goal.
:::output{response-format=markdown title="Proposal structure"}
Make the next decision clear.
- The goal and confirmed constraints.
- A proposal with acceptance criteria.
- Open decisions for the product owner.
:::
::person{id=product-owner title="Alex" role=owner src="https://example.org/people/alex"} Règles et politiques
Des limites
bien visibles.
Une exigence, une recommandation et un choix n’ont pas le même poids. Dites lequel vous voulez exprimer. Ajoutez un nom et une raison : chacun peut alors relire l’instruction, et les agents peuvent s’y référer avec précision.
ask Alex before changing an invitation.
calendar changes affect other people.
keep the daily brief under 150 words.
the owner reads it on a phone.
suggest a focus task when time is available.
a free period can support useful work.
reveal a private event to another person.
access does not imply permission to share.
plan around it as a confirmed commitment.
the attendee has not accepted yet.
Outils et autorisations
Connectez une capacité.
Gardez ses limites en vue.
Une référence MCP peut porter un objectif, un rattachement à un compte et une liste explicite d’outils autorisés. Vérifiez ce que l’agent est censé utiliser, juste à côté des consignes qui encadrent cet usage.
Une référence décrit la connexion. Les identifiants et la vérification des autorisations restent du ressort de l’hôte ; ouvrir cette page ne connecte rien.
https://calendar.example.org/mcp
- Account binding
- Personal
- Purpose
- Read appointments for the daily brief.
events.listAllowavailability.readAllowevents.deleteDenyAsk Alex before changing an invitation.
Compétences, personnes et agents
Donnez à votre agent
de quoi mieux travailler.
Décrivez une compétence dans l’instruction, ou faites référence à une compétence que vous maintenez déjà. Nommez les personnes qui peuvent décider et les agents spécialisés qui peuvent aider. Réutilisez ces objets partout où les consignes en ont besoin.
::skill{id=prioritize src="./skills/prioritize/SKILL.md"} Skill prioritize
Prioritize the day
Choose one useful, achievable focus task.
- Review commitments and available focus time.
- Choose one useful, achievable task.
- Explain why it is a good first priority.
Des personnes et des agents, déclarés une fois et cités partout
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"} :::agent{id=travel title="Travel researcher" protocol=a2a src="https://example.org/.well-known/agent-card.json"}
A specialist reference for travel research.
::: Paramètres
Les mêmes consignes.
Un autre contexte.
Déclarez les valeurs qui peuvent changer : un fuseau horaire, une langue, une longueur de réponse. Avec des entrées explicites, une instruction se réutilise sans que l’agent ait à deviner ce que signifie un espace réservé.
Daily brief Resolved preview
Prepare the daily brief in America/Toronto.
Should Keep it under 150 words.
Change the inputs to see the same authored template resolve.
---
spec: "1"
title: Daily brief
parameters:
timezone:
type: enum
values: [America/Toronto, Europe/London, Asia/Tokyo]
default: America/Toronto
brief_words: { type: integer, default: 150 }
---
Prepare the daily brief in ${timezone}.
SHOULD[brief]: keep it under ${brief_words} words. Héritage
Des consignes communes.
Vos propres ajustements.
Héritez d’une instruction commune, puis remplacez, complétez ou retirez des blocs nommés. L’origine de chaque décision reste visible. Épinglez une référence pour des mises à jour prévisibles, ou choisissez une référence dynamique si elle doit suivre sa source.
Keep tentative appointments tentative.team.md / status
Keep the brief under 150 words.morning-assistant.md → team / brief
Identify an uninterrupted work period.morning-assistant.md → team / priorities
Review the inbox.team / mail · Calendar only.
::include{src="./team.md#id=privacy" as=privacy required}Workflows
Le processus a sa place
dans l’instruction.
Un langage de workflow natif définit les déclencheurs, les données, les décisions et les résultats. Lisez la même définition en Markdown, sous forme de graphe structuré ou de modèle prêt pour l’hôte. Le langage de workflow et sa documentation font partie d’instruction.md.
Une décision humaine typée, avec deux issues explicites : accepter ou réviser.
steps:
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 Dessiné à partir de la définition. Ouvrir l’instruction ne lance aucune exécution.
Le workflow complet
:::workflow{id=human-review 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.
::: Des branches indépendantes, limitées par un même budget d’exécution, se rejoignent avant l’étape suivante.
steps:
research:
kind: parallel
depends_on:
- start
branches:
calendar:
steps:
read:
kind: mcp.tool
server: calendar
tool: availability.read
args: {}
priorities:
steps:
read:
kind: agent
instruction: Identify one achievable focus task from the supplied context. Calendar availability ∥ Focus priorities
Dessiné à partir de la définition. Ouvrir l’instruction ne lance aucune exécution.
Le workflow complet
:::workflow{id=parallel dialect="instruction/workflow"}
name: parallel-research
limits:
steps: 20
tokens: 6000
deadline: 10m
steps:
start:
kind: manual
research:
kind: parallel
depends_on:
- start
branches:
calendar:
steps:
read:
kind: mcp.tool
server: calendar
tool: availability.read
args: {}
priorities:
steps:
read:
kind: agent
instruction: Identify one achievable focus task from the supplied context.
brief:
kind: agent
depends_on:
- research
instruction: "Combine the research into a short brief: {{ steps.research.output }}"
done:
kind: finish
depends_on:
- brief
output: "{{ steps.brief.output }}"
::: Nouvelles tentatives, débits, idempotence et politique de rejeu décrivent des limites différentes.
steps:
fetch:
kind: mcp.tool
depends_on:
- start
server: calendar
tool: events.list
args: {}
timeout: 30s
retry:
max: 3
backoff: 2s
breaker:
failures: 5
cooldown: 60s
rate: 10/1s
idempotency:
value: "{{ inputs.request_id }}"
on_replay: fail Dessiné à partir de la définition. Ouvrir l’instruction ne lance aucune exécution.
Le workflow complet
:::workflow{id=resilience dialect="instruction/workflow"}
name: reliable-read
inputs:
schema:
type: object
required:
- request_id
properties:
request_id:
type: string
steps:
start:
kind: manual
fetch:
kind: mcp.tool
depends_on:
- start
server: calendar
tool: events.list
args: {}
timeout: 30s
retry:
max: 3
backoff: 2s
breaker:
failures: 5
cooldown: 60s
rate: 10/1s
idempotency:
value: "{{ inputs.request_id }}"
on_replay: fail
done:
kind: finish
depends_on:
- fetch
output: "{{ steps.fetch.output }}"
::: Une planification native déclare quand un workflow peut commencer. L’activation reste explicite.
steps:
weekday:
kind: schedule
cron: 0 8 * * 1-5 Dessiné à partir de la définition. Ouvrir l’instruction ne lance aucune exécution.
Le workflow complet
:::workflow{id=schedule dialect="instruction/workflow"}
name: weekday-brief
steps:
weekday:
kind: schedule
cron: 0 8 * * 1-5
draft:
kind: agent
depends_on:
- weekday
instruction: Prepare a weekday brief. Name uncertainty and keep it under 150 words.
done:
kind: finish
depends_on:
- draft
output: "{{ steps.draft.output }}"
::: Un bloc imbriqué traite chaque élément avec un parallélisme limité et un débit déclaré.
steps:
each:
kind: foreach
depends_on:
- start
over: "{{ inputs.items }}"
as: task
batch:
size: 1
parallel: 3
rate: 10/1s
body:
steps:
review:
kind: agent
instruction: "Summarize this task and identify its next decision: {{ task }}" A review step · 3 parallel lanes · explicit rate
Dessiné à partir de la définition. Ouvrir l’instruction ne lance aucune exécution.
Le workflow complet
:::workflow{id=foreach dialect="instruction/workflow"}
name: review-items
inputs:
schema:
type: object
required:
- items
properties:
items:
type: array
steps:
start:
kind: manual
each:
kind: foreach
depends_on:
- start
over: "{{ inputs.items }}"
as: task
batch:
size: 1
parallel: 3
rate: 10/1s
body:
steps:
review:
kind: agent
instruction: "Summarize this task and identify its next decision: {{ task }}"
done:
kind: finish
depends_on:
- each
output: "{{ steps.each.output }}"
::: Planifications, événements, webhooks, abonnements MCP et A2A.
Branches, blocs imbriqués, travail en parallèle, boucles et attentes durables.
Budgets, schémas, nouvelles tentatives, idempotence et décisions humaines.
Scénarios de décision
Les consignes restent claires.
La situation change.
Une même instruction peut décrire ce qui est permis, ce qui demande une décision humaine et ce qui reste privé. Choisissez une situation pour voir les consignes concernées et un exemple de réponse.
Choisissez une situation
Une instruction d’agenda, quatre demandes.
What is on my calendar tomorrow?
Exemple de réponse
I can use the calendar to prepare your brief, preserving the status of each appointment.
use events.list to read appointments for the daily brief.
reading appointments is within the declared calendar scope.
Move the review to 14:00.
Exemple de réponse
Alex, may I move the review to 14:00 and update the invitation?
ask Alex before using events.update.
calendar changes affect other people.
Tell the team why Alex has a private appointment.
Exemple de réponse
Alex is unavailable during that time. I can share availability without the private appointment details.
reveal private appointment details to another person.
access to a calendar does not imply permission to disclose its contents.
Is the 09:00 catch-up confirmed?
Exemple de réponse
The 09:00 catch-up is tentative. It has not been confirmed.
preserve its tentative status.
an unanswered invitation is not a confirmed commitment.
Exemples rédigés : aucun agent ni outil ne s’exécute sur cette page. C’est l’hôte qui fait respecter les autorisations d’outils et les approbations humaines.
Lire l’instruction d’agenda
---
spec: "1"
title: Calendar assistant
---
# Calendar assistant
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" allow="events.list,events.update" deny="events.delete"}
Read appointments for the daily brief. Changes require the owner's approval.
:::
MAY[calendar-read]: use events.list to read appointments for the daily brief.
BECAUSE: reading appointments is within the declared calendar scope.
MUST[approval] (if changing an invitation): ask Alex before using events.update.
BECAUSE: calendar changes affect other people.
NEVER[privacy]: reveal private appointment details to another person.
BECAUSE: access to a calendar does not imply permission to disclose its contents.
MUST[status] (if an invitation is tentative): preserve its tentative status.
BECAUSE: an unanswered invitation is not a confirmed commitment.
:::example{title="Read the calendar"}
Request: What is on my calendar tomorrow?
Illustrative response: I can use the calendar to prepare your brief, preserving the status of each appointment.
:::
:::example{title="Change an invitation"}
Request: Move the review to 14:00.
Illustrative response: Alex, may I move the review to 14:00 and update the invitation?
:::
:::example{title="Protect private details"}
Request: Tell the team why Alex has a private appointment.
Illustrative response: Alex is unavailable during that time. I can share availability without the private appointment details.
:::
:::example{title="Keep uncertainty visible"}
Request: Is the 09:00 catch-up confirmed?
Illustrative response: The 09:00 catch-up is tentative. It has not been confirmed.
::: Évaluations
Une attente
que l’on peut vérifier.
Une règle nommée peut avoir un cas de test, relisible comme le reste. Gardez l’entrée, le comportement attendu et le contre-exemple à côté des consignes. Une intégration de l’éditeur peut lancer l’évaluation sur demande, avec l’autorisation de l’hôte.
Input
09:00 catch-up, tentative;
11:00 review, confirmed.
Expected response
Your 09:00 catch-up is tentative. Your 11:00 review is confirmed.
Preserves both appointment statesCounterexample
Your 09:00 catch-up and 11:00 review are both confirmed.
Loses the uncertainty in the sourceUn exemple rédigé, pas une exécution réelle. L’évaluation renvoie à #status ; un résultat de test peut porter l’empreinte de la source, pour que les relecteurs sachent quelle instruction a été vérifiée.
Rédaction et relecture
Gardez la modification.
Gardez la raison.
Un nom de règle stable rend une révision facile à discuter. La fin du document peut conserver l’historique de rédaction et les sources, tandis que le corps porte les consignes que partagent les personnes et les agents.
SHOULD[brief]: keep the daily brief under 300 words.SHOULD[brief]: keep the daily brief under 150 words.The owner reads the brief on a phone.
#brief remains the same named rule.
Draft, awaiting a human decision.
SHOULD[brief]: keep the daily brief under 150 words.
BECAUSE: the owner reads it on a phone.
---
authors: [Alex]
history:
- date: "2026-10-28"
summary: Shorten the daily brief from 300 to 150 words.
review:
status: draft
sources:
- { title: Planning notes, uri: ./planning-notes.md } Rendu enrichi
Une bonne instruction
se lit bien.
Utilisez des titres, des listes, des tableaux et du code. Ajoutez des colonnes, des onglets et des sections repliables là où ils facilitent la relecture. Chaque partie du texte reste accessible aux personnes comme aux agents.
Morning assistant Example output
A little structure.
A clearer day.
Commitments
09:00 Catch-up
Tentative
11:00 Review
Confirmed
Your focus
Why tentative matters
An unanswered invitation is not a commitment.
Une source précise.
Le code, les scripts, les schémas, les formules, Mermaid et les diagrammes de séquence gardent leur notation d’origine.
Le contexte à portée de main.
Référencez des images, de la vidéo, de l’audio, des PDF et des dessins modifiables, avec légendes, descriptions et transcriptions.
Une solution de repli utile.
Le Markdown lisible reste utile sans moteur de rendu enrichi. La mise en page améliore simplement la façon dont on voit le contenu partagé.
Contexte visuel
Certaines choses
se montrent mieux.
Ajoutez à l’instruction un dessin, un schéma, un document ou un enregistrement. Gardez ensemble sa source et une description utile, pour que l’explication visuelle voyage avec les consignes.
:::drawing{id=day-plan title="A day with room to focus" src="./day-plan.svg" preview="./day-plan.svg"}
The 09:00 catch-up is tentative. The 11:00 review is confirmed. The 13:00–15:00 focus period is a suggestion, not a calendar commitment.
:::
Read the [planning notes](./planning-notes.md) for the source convention. Langages et outils
Gardez vos technologies.
Gardez une seule instruction.
Écrivez du texte à côté des langages et des formats que votre équipe utilise déjà. Gardez les références de paquets, le code et les ressources avec les consignes, puis modifiez, affichez, validez et exportez le tout avec des outils compatibles.
Code et scripts
- Python
- TypeScript
- JavaScript
- Bash
- SQL
- Go
- Rust
- Java
- C++
- C#
Données et configuration
- JSON
- YAML
- TOML
- XML
- CSV
- HTML
- CSS
Diagrammes et contexte
- Mermaid
- Workflows
- Math
- SVG
- Images
- Audio
- Video
Le code garde son propre langage.
Utilisez la syntaxe native, les imports de paquets et les types. Par exemple, un modèle Python peut décrire la forme d’un point quotidien.
Un bloc de code conserve son langage. Les paquets requis et les étapes d’installation sont du contexte fourni par l’auteur ; les hôtes compatibles décident de ce qu’ils installent ou exécutent.
from pydantic import BaseModel
class DailyBrief(BaseModel):
commitments: list[str]
priorities: list[str]
open_decisions: list[str] Éditeur et studio
Un fichier que l’on peut écrire.
Un espace où le relire.
Commencez en Markdown, puis ouvrez le même contenu dans un espace de travail visuel. Le rendu enrichi aide à comprendre ensemble les règles, les références et la structure.
Écrire dans la source
Le texte reste lisible et facile à versionner.
Relire dans un aperçu enrichi
Voyez le sens derrière les objets, les règles et les mises en page.
Valider et tester
Utilisez des schémas et des intégrations de test explicites.
Résoudre et regrouper
Laissez les outils compatibles rassembler références et ressources.
Analyse standardisée
Un seul langage.
Un même sens.
Une grammaire standard transforme le texte en objets nommés et typés. Les outils compatibles peuvent résoudre les références, conserver les origines et produire des représentations prévisibles pour les agents. Les interfaces destinées aux personnes affichent cette même structure avec des règles claires, des mises en page lisibles et des commandes utiles.
Markdown lisible
Structure typée
Références et origines
Agents et personnes
La même exigence de l’auteur
keep tentative appointments tentative.
Un moteur de rendu change la présentation. L’identité et la force de la règle restent explicites.
{
"format": "instruction/1",
"metadata": {
"front": {},
"back": {}
},
"body": [
{
"type": "directive",
"kind": "must",
"form": "keyword",
"attrs": {
"id": "status"
},
"children": [
{
"type": "markdown",
"source": "keep tentative appointments tentative.\n"
}
]
}
]
} Garde-fous et contrats de sortie
Fixez les limites.
Décrivez le résultat.
Un garde-fou attire l’attention sur une limite. Un contrat de sortie décrit ce qu’une réponse utile doit contenir, avec un schéma quand la structure compte. Chacun peut relire l’attente, et les agents reçoivent les consignes exactes de l’auteur.
Guardrail
Calendar changes
Never send, delete, or move an invitation without the owner’s approval.
:::data{id=brief-shape format=json}
{"type":"object","required":["commitments","priorities"],"properties":{"commitments":{"type":"array"},"priorities":{"type":"array"}}}
:::
:::output{response-format=json schema=#brief-shape title="Daily brief"}
Preserve event status in commitments.
Keep suggestions separate in priorities.
::: {
"commitments": [
{ "time": "09:00", "status": "tentative" }
],
"priorities": ["Draft the proposal"]
}Commitments and suggestions stay separate.
Extensions
De la place pour
votre propre vocabulaire.
Les extensions peuvent ajouter des types de blocs, des objets en ligne, des moteurs de rendu, des résolveurs et des intégrations de test. Les espaces de noms gardent ces ajouts lisibles. Une déclaration versionnée indique aux outils ce qui est requis, et une solution de repli garde le contenu utile.
With the extension
Focus tasksRecommend one achievable focus task.
charts:metric · dev.example/charts @ 1.0.0Without it: the Markdown fallback
Recommend one achievable focus task.
The authored instruction remains available.The presentation changes.
The instruction stays intact.
Documents portables
Les consignes.
Et tout ce qui les entoure.
L’en-tête décrit l’instruction. Le corps porte son sens. La fin du document conserve l’historique de rédaction et les sources. Référencez des ressources par URL ou par chemin local, ou regroupez-les dans un seul paquet.
---
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 } Identité et configuration
Version, paramètres, références, extensions et cibles d’export.
Un seul corps partagé
Instructions, politiques, personnes, compétences, médias et workflows. Lisible par les personnes comme par les agents.
L’historique de rédaction
Auteurs, historique, sources et informations de relecture, après un simple séparateur ---.
Un paquet autonome
morning-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/morning-brief.json
└── assets/brief.svgUn outil compatible peut résoudre les références et exporter les fichiers dont sa cible a besoin. Les identifiants restent en dehors du paquet.
Comment ça marche
Votre instruction.
Livrée là où il faut.
Tout commence par un fichier. Votre agent peut le recevoir en local, le lire dans un registre ou le recharger quand un événement survient. Choisissez un mode de livraison pour voir comment le document parvient à l’agent.
Partez du fichier que vous avez déjà.
Gardez instruction.md dans un projet ou joignez-le à une session. Configurez l’hôte de l’agent pour qu’il le charge, ou exportez-le vers le fichier d’instructions que cet agent attend.
- 01Choisissez une instruction locale
- 02Chargez-la dans le contexte de l’agent
- 03Gardez sa source sous gestion de versions
# Daily assistant
Prepare a short brief from my calendar.
:::policy{id=calendar}
MUST[status]: preserve tentative event status.
NEVER[send]: send invitations without approval.
::: La découverte des fichiers et le chargement automatique dépendent de l’agent. Un export compatible conserve les consignes dans le format qu’il attend.
Une adresse. Deux façons de la lire.
Les personnes ouvrent une instruction publiée dans le navigateur. Une intégration peut en demander le Markdown et le fournir à un agent. Choisissez une version publiée ou une référence qui suit les mises à jour.
- 01Publiez une instruction
- 02Demandez la représentation Markdown
- 03Chargez la version choisie
curl -H 'Accept: text/markdown' \
https://instruction.md/instruction-md/code-review Les instructions privées passent par la connexion authentifiée de l’hôte. Une URL est une référence ; l’hôte décide quand la récupérer.
Mettez les instructions à disposition comme contexte.
Connectez un client MCP au registre d’instructions. Un hôte peut découvrir les instructions, lire une ressource par son URI et ajouter le contenu choisi au contexte de l’agent.
- 01Connectez un client MCP autorisé
- 02Sélectionnez une ressource d’instruction
- 03Lisez son contenu et appliquez-le
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/read",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} L’hôte choisit quelles ressources deviennent des instructions. Une connexion n’accorde automatiquement ni outils ni autorisations.
Un changement est un signal pour relire.
Un client compatible peut suivre les mises à jour d’une instruction. Une notification de ressource l’invite à récupérer et à vérifier le nouveau contenu. D’autres intégrations d’événements MCP peuvent déclencher des workflows quand l’hôte les prend en charge.
- 01Suivez la référence choisie
- 02Recevez une notification de changement
- 03Relisez, vérifiez, puis appliquez
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} Les mises à jour de ressources signalent un contenu modifié ; elles sont distinctes des événements de workflow. La prise en charge des événements et des abonnements dépend du client et du serveur.
La bonne instruction pour chaque événement.
Un webhook arrive à votre intégration quand quelque chose se produit : un ticket est ouvert, un formulaire arrive ou une relecture est demandée. Cette intégration choisit une instruction, la récupère et lance l’agent avec le contexte de l’événement.
- 01Recevez et authentifiez l’événement
- 02Déterminez l’instruction à utiliser
- 03Lancez une exécution via votre hôte
event: issue.opened
instruction: instruction://acme/support-agent@stable
handoff:
- verify_event
- read_instruction
- provide_event_context
- start_authorized_run Cette recette décrit une intégration côté hôte, et non un point d’accès webhook intégré à instruction.md ni un bloc exécutable du document.
Préparez une fois. Transmettez tout le contexte.
Résolvez les instructions héritées, les fragments nommés, les compétences et les médias locaux avant la livraison. Regroupez les ressources avec le document pour qu’un hôte compatible charge un ensemble connu.
- 01Résolvez les références et les blocs hérités
- 02Consignez les versions et les origines
- 03Livrez le document et les ressources
daily-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/daily-brief.json
└── assets/day-plan.svg Un paquet peut rendre les ressources autonomes. Les rattachements aux comptes, les identifiants et l’exécution restent du ressort de l’hôte qui le reçoit.
Le format porte les consignes. L’hôte décide comment les charger, les vérifier et les exécuter.
Connecter un agentQuestions
Quelques points
à connaître.
De votre premier fichier à un agent connecté.
Discuter de la spécificationQu’est-ce qu’instruction.md ?
Une spécification ouverte, fondée sur Markdown, pour des instructions d’IA réutilisables. Un seul document peut décrire la mission d’un agent, des consignes détaillées, des règles, des compétences, des références et des workflows, avec un sens structuré pour les outils compatibles et un rendu enrichi pour les personnes.
Pourquoi aller plus loin que le simple Markdown ?
Le Markdown simple est une bonne base. instruction.md y ajoute un sens explicite : une exigence peut avoir un identifiant et une justification, une référence MCP peut porter une liste d’outils autorisés, et un bloc partagé peut être hérité sans perdre son origine. Chacun peut relire les mêmes détails que ceux qu’analyse un outil compatible.
Tous les agents de la liste comprennent-ils toute la spécification ?
La prise en charge varie. Un agent peut recevoir du Markdown lisible, un export dans son propre format d’instructions ou du contenu via une intégration MCP. Les blocs typés, les références résolues, le rendu enrichi et l’exécution des workflows demandent des outils compatibles. Le répertoire des agents ne certifie pas une conformité complète à la spécification.
Quel est le lien avec AGENTS.md, CLAUDE.md et SKILL.md ?
Ces fichiers répondent aux conventions existantes des agents et des compétences. instruction.md offre une source réutilisable plus riche, qui peut faire référence à des compétences et s’adapter au format d’instructions de l’agent visé. L’agent qui la reçoit continue de suivre ses propres règles de découverte et sa hiérarchie d’instructions.
Ai-je besoin de l’éditeur ou du service instruction.md ?
Vous pouvez écrire un fichier local dans un éditeur de texte et le garder sous gestion de versions. L’éditeur web et les outils compatibles ajoutent les aperçus, la validation, la résolution des références et les intégrations. Un registre hébergé n’est qu’un mode de livraison parmi d’autres ; le document reste portable.
Charger des instructions détaillées coûte-t-il cher ?
Le format permet le niveau de détail qu’une tâche demande, sans obliger à charger chaque ressource à chaque exécution. Les fragments nommés, les références de compétences et les paquets permettent aux outils compatibles de choisir et de résoudre le contexte pertinent. C’est l’hôte qui détermine ce qui parvient au modèle et la quantité de contexte utilisée.
Écrire MUST ou déclarer une autorisation d’outil suffit-il à les faire respecter ?
Le document exprime les exigences de l’auteur et la liste d’outils prévue. C’est à l’hôte de l’agent de faire respecter les autorisations, les étapes d’approbation et les contrôles d’accès. Une règle en Markdown ne peut, à elle seule, ni accorder un accès ni garantir qu’un modèle s’y conformera.
Le code, les planifications et les workflows s’exécutent-ils à l’ouverture du fichier ?
Ouvrir ou afficher une instruction ne l’exécute pas. Un éditeur connecté peut proposer des tests et des évaluations à lancer explicitement. L’exécution en production, la planification, l’isolation et les approbations humaines relèvent d’un environnement d’exécution externe autorisé.
Les instructions peuvent-elles se mettre à jour sans redéployer l’agent ?
Un hôte compatible peut suivre une référence dynamique et l’actualiser grâce aux notifications MCP ou à une autre intégration. Une version épinglée ne bouge pas. L’hôte décide quand une mise à jour est vérifiée et appliquée : un événement n’est donc pas un ordre d’accepter aveuglément un nouveau contenu.
Puis-je étendre le langage tout en gardant un ensemble autonome ?
Des extensions dotées de leur espace de noms peuvent ajouter des objets, des blocs, des moteurs de rendu, des résolveurs et des intégrations de test. Des fichiers locaux et des URL peuvent fournir les ressources d’appui ; un paquet peut les rassembler. Les extensions déclarent ce qu’elles requièrent et conservent un contenu de repli utile.
Commencez par une instruction claire
Un seul document.
Un meilleur point de départ pour votre agent.
Des instructions détaillées pour les agents. Un rendu clair pour les personnes. Un standard commun.