Especificación de lenguaje de código abierto
Instrucciones en Markdown para agentes de IA.
instruction.md es un formato abierto para explicar a los agentes de IA cómo trabajar. Un solo archivo Markdown reúne las reglas que el agente debe cumplir, las herramientas y habilidades que puede usar y los flujos de trabajo que ejecuta. Las personas lo leen y lo revisan como un documento claro, y los agentes siguen ese mismo texto. Escríbelo una vez y llévalo a los agentes que ya usas.
Agentes compatibles
Lleva tus instrucciones a los agentes que usas.
Markdown legible, exportaciones específicas para cada agente o conexiones MCP. La compatibilidad con la sintaxis avanzada y con las integraciones varía según el host.
¿Primera vez aquí?
Empieza con una guía
Un vídeo corto, una tarea paso a paso y una lectura rápida. Unos minutos cada una, y para la primera no necesitas cuenta. Todas las guías
-
Vídeo · 2 min Escribe tu primera instrucción Mira cómo se escribe una instrucción en el editor, desde una página en blanco hasta las reglas que sigue un agente. No hace falta cuenta. -
Paso a paso · 5 min Publícala y conecta un agente Inicia sesión, publica tu instrucción y dirige un agente de IA hacia ella para que siga lo que escribiste. -
Lectura breve · 3 min Cómo funcionan las versiones Por qué tu borrador nunca sorprende a un agente: borradores, versiones y qué significa que una versión esté activa.
Se escribe una vez. Lo entienden todos.
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.
Texto sencillo que puedes revisar. Un significado estructurado que un lector compatible conserva.
Descargar ejemplo¿Por qué instruction.md?
El detalle que necesitan los agentes.
La claridad que necesitan las personas.
La configuración de un agente suele estar repartida entre prompts, ajustes, archivos de habilidades y lo que sabe el equipo. Reúne las pautas en un documento reutilizable que las personas puedan leer y las herramientas compatibles interpreten de la misma manera.
El detalle suficiente para ser útil.
Mantén juntos la intención, el contexto, las excepciones, los ejemplos y la justificación. Da a las pautas precisas una estructura a la que un agente pueda remitirse.
Un significado que no se pierde al analizarlo.
Pon nombre a las reglas, define objetos y conserva los orígenes. Un lector compatible distingue un requisito de una recomendación, y una referencia de un permiso para usar una herramienta.
Un documento que las personas pueden revisar.
Muestra los permisos, los flujos de trabajo, las personas y las habilidades en su contexto. Haz que la instrucción sea comprensible para quienes la escriben, la aprueban y la mantienen.
Escríbela. Revísala. Reutilízala con distintos agentes.
Explora ejemplos reales de instruccionesInstrucciones detalladas
El detalle suficiente
para transmitir tu intención.
Las instrucciones pueden ser breves o muy detalladas. Dale al agente las condiciones, los motivos, los ejemplos y el contexto que necesita. El lenguaje hace explícito ese detalle; una vista de lectura enriquecida lo hace manejable para las personas.
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
El nivel de detalle es significado que aporta el autor. El diseño puede ordenarlo; un lector conserva el detalle.
Ejemplos de instrucciones
Responsabilidades distintas.
Un lenguaje común.
Un asistente personal, un compañero de investigación o un equipo entero pueden partir del mismo formato. Elige una instrucción y alterna entre su vista de lectura y el Markdown que hay detrás.
Elige una instrucción
Explora las pautas que necesita cada función.
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"} Reglas y políticas
Haz que los límites
se vean a simple vista.
Un requisito, una recomendación y una opción no pesan lo mismo. Di cuál de ellos quieres decir. Añade un nombre y un motivo para que las personas puedan revisar la instrucción y los agentes puedan referirse a ella con precisión.
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.
Herramientas y permisos
Conecta una capacidad.
Mantén sus límites a la vista.
Una referencia MCP puede indicar un propósito, la cuenta a la que se vincula y un conjunto explícito de herramientas permitidas. Revisa lo que el agente debe usar junto a las pautas que rigen cómo lo usa.
Una referencia describe la conexión. Las credenciales y la comprobación de permisos quedan en manos del host; abrir esta página no conecta nada.
https://calendar.example.org/mcp
- Account binding
- Personal
- Purpose
- Read appointments for the daily brief.
events.listAllowavailability.readAllowevents.deleteDenyAsk Alex before changing an invitation.
Habilidades, personas y agentes
Dale a tu agente
más con qué trabajar.
Define una habilidad dentro de la instrucción o haz referencia a una que ya mantienes. Nombra a las personas que pueden decidir y a los agentes especializados que pueden ayudar. Reutiliza esos objetos allí donde las pautas los necesiten.
::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.
Personas y agentes: se declaran una vez y se citan donde haga falta
::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.
::: Parámetros
Las mismas pautas.
Otro contexto.
Declara los valores que pueden cambiar: una zona horaria, un idioma, la longitud de la respuesta. Con entradas explícitas, una instrucción se puede reutilizar sin pedirle al agente que adivine qué significa un marcador.
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. Herencia
Pautas compartidas.
Cambios propios.
Hereda una instrucción común y después sustituye, amplía o elimina bloques con nombre. El origen de cada decisión sigue a la vista. Fija una referencia a una versión para que las actualizaciones sean predecibles, o elige una referencia dinámica cuando deba seguir a su origen.
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}Flujos de trabajo
El proceso forma parte
de la instrucción.
Un lenguaje de flujos de trabajo propio define activadores, datos, decisiones y resultados. Lee la misma definición como Markdown, como un grafo estructurado o como un modelo listo para el host. El lenguaje de flujos de trabajo y su documentación forman parte de instruction.md.
Una decisión humana con tipo, con resultados explícitos: aceptar o revisar.
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 Dibujado a partir de la definición. Abrir la instrucción no inicia ninguna ejecución.
El flujo de trabajo completo
:::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.
::: Ramas independientes, dentro de un mismo presupuesto de ejecución, que se unen antes del paso siguiente.
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
Dibujado a partir de la definición. Abrir la instrucción no inicia ninguna ejecución.
El flujo de trabajo completo
:::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 }}"
::: Los reintentos, los límites de frecuencia, la idempotencia y la política de repetición describen límites distintos.
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 Dibujado a partir de la definición. Abrir la instrucción no inicia ninguna ejecución.
El flujo de trabajo completo
:::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 }}"
::: Una programación nativa declara cuándo puede empezar un flujo de trabajo. La activación sigue siendo explícita.
steps:
weekday:
kind: schedule
cron: 0 8 * * 1-5 Dibujado a partir de la definición. Abrir la instrucción no inicia ninguna ejecución.
El flujo de trabajo completo
:::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 cuerpo con ámbito propio procesa cada elemento con un paralelismo acotado y una frecuencia declarada.
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
Dibujado a partir de la definición. Abrir la instrucción no inicia ninguna ejecución.
El flujo de trabajo completo
:::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 }}"
::: Programaciones, eventos, webhooks, suscripciones MCP y A2A.
Ramas, cuerpos con ámbito propio, trabajo en paralelo, bucles y esperas duraderas.
Presupuestos, esquemas, reintentos, idempotencia y decisiones humanas.
Escenarios de decisión
Las pautas siguen claras.
La situación cambia.
Una misma instrucción puede describir qué está permitido, qué necesita la decisión de una persona y qué se mantiene privado. Elige una situación para ver las pautas que se aplican y una respuesta de ejemplo.
Elige una situación
Una instrucción de calendario, cuatro peticiones.
What is on my calendar tomorrow?
Respuesta de ejemplo
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.
Respuesta de ejemplo
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.
Respuesta de ejemplo
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?
Respuesta de ejemplo
The 09:00 catch-up is tentative. It has not been confirmed.
preserve its tentative status.
an unanswered invitation is not a confirmed commitment.
Ejemplos escritos por el autor: en esta página no se ejecuta ningún agente ni herramienta. El host hace cumplir los permisos de las herramientas y las aprobaciones humanas.
Leer la instrucción del calendario
---
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.
::: Evaluaciones
Convierte la expectativa
en algo que se puede comprobar.
Una regla con nombre puede tener un caso de prueba revisable. Mantén la entrada, el comportamiento esperado y el contraejemplo junto a las pautas. Una integración del editor puede ejecutar la evaluación de forma explícita, con la autorización del host.
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 ejemplo escrito por el autor, no una ejecución real. La evaluación hace referencia a #status; el resultado de una prueba puede incluir la huella digital del texto de origen, para que quienes revisan sepan qué instrucción se comprobó.
Autoría y revisión
Conserva el cambio.
Conserva el motivo.
Un nombre de regla estable hace que una revisión sea fácil de comentar. Los metadatos finales pueden guardar el historial de autoría y las fuentes, mientras el cuerpo conserva las pautas que comparten personas y agentes.
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 } Presentación enriquecida
Una buena instrucción
debe leerse bien.
Usa títulos, listas, tablas y código. Añade columnas, pestañas y secciones desplegables donde faciliten la revisión. Cada parte del contenido sigue disponible tanto para las personas como para los agentes.
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.
Mantén la precisión del original.
El código, los scripts, los esquemas, las fórmulas, Mermaid y los diagramas de secuencia conservan su notación nativa.
Lleva el contexto contigo.
Haz referencia a imágenes, vídeo, audio, PDF y dibujos editables, con pies, descripciones y transcripciones.
Conserva una alternativa útil.
El Markdown legible sigue siendo útil fuera de un renderizador enriquecido. El diseño mejora la forma en que las personas ven el contenido compartido.
Contexto visual
Hay contexto
que es mejor mostrar.
Lleva a la instrucción un dibujo, un diagrama, un documento o una grabación. Mantén juntos su origen y una descripción útil, para que la explicación visual viaje con las pautas.
:::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. Lenguajes y herramientas
Trae tus tecnologías.
Mantén una sola instrucción.
Escribe texto junto a los lenguajes y formatos que tu equipo ya usa. Mantén las referencias a paquetes, el código y los recursos junto a las pautas, y después usa herramientas compatibles para editarla, mostrarla, validarla y exportarla.
Código y scripts
- Python
- TypeScript
- JavaScript
- Bash
- SQL
- Go
- Rust
- Java
- C++
- C#
Datos y configuración
- JSON
- YAML
- TOML
- XML
- CSV
- HTML
- CSS
Diagramas y contexto
- Mermaid
- Workflows
- Math
- SVG
- Images
- Audio
- Video
El código conserva su propio lenguaje.
Usa la sintaxis nativa, las importaciones de paquetes y los tipos. Por ejemplo, un modelo de Python puede describir la forma de un resumen diario.
Un bloque de código conserva su lenguaje. Los requisitos de paquetes y los pasos de configuración son contexto escrito por el autor; los hosts compatibles deciden qué instalar o ejecutar.
from pydantic import BaseModel
class DailyBrief(BaseModel):
commitments: list[str]
priorities: list[str]
open_decisions: list[str] Editor y estudio
Un archivo que las personas pueden escribir.
Un espacio de trabajo donde revisarlo.
Empieza con Markdown y después lleva el mismo contenido a un espacio de trabajo visual. La presentación enriquecida ayuda a entender en conjunto las reglas, las referencias y la estructura.
Escribe en el código fuente
Mantén el texto legible y fácil de versionar.
Revisa con vistas previas enriquecidas
Ve el significado que hay detrás de los objetos, las reglas y los diseños.
Valida y prueba
Usa esquemas e integraciones de pruebas explícitas.
Resuelve y empaqueta
Deja que las herramientas compatibles reúnan las referencias y los recursos.
Análisis estandarizado
Un lenguaje.
Un significado coherente.
Una gramática estándar convierte el texto en objetos con nombre y tipo. Las herramientas compatibles pueden resolver referencias, conservar los orígenes y producir representaciones predecibles para los agentes. Las interfaces para personas muestran esa misma estructura con reglas claras, diseños legibles y controles útiles.
Markdown legible
Estructura con tipos
Referencias y orígenes
Agentes y personas
El mismo requisito del autor
keep tentative appointments tentative.
Un renderizador cambia la presentación. La identidad y la fuerza de la regla siguen siendo explícitas.
{
"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"
}
]
}
]
} Salvaguardas y contratos de salida
Define los límites.
Describe el resultado.
Una salvaguarda llama la atención sobre un límite. Un contrato de salida describe qué debe contener una respuesta útil, con un esquema cuando la estructura importa. Las personas pueden revisar la expectativa, y los agentes reciben las pautas exactas que escribió el autor.
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.
Extensiones
Espacio para tu
propio vocabulario.
Las extensiones pueden añadir tipos de bloque, objetos en línea, renderizadores, resolutores e integraciones de pruebas. Los espacios de nombres mantienen claras las incorporaciones. Una declaración con versión indica a los lectores qué hace falta, y una alternativa mantiene útil el contenido.
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.
Documentos portátiles
Las pautas.
Y todo lo que las rodea.
Los metadatos iniciales describen la instrucción. El cuerpo contiene su significado. Los metadatos finales guardan el registro de autoría y las fuentes. Haz referencia a los recursos por URL o por ruta local, o empaquétalos juntos en un solo paquete.
---
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 } Identidad y configuración
Versión, parámetros, referencias, extensiones y destinos de exportación.
Un solo cuerpo compartido
Instrucciones, políticas, personas, habilidades, contenido multimedia y flujos de trabajo. Legible para personas y para agentes.
El registro de autoría
Autores, historial, fuentes e información de revisión tras un simple separador ---.
Un paquete autosuficiente
morning-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/morning-brief.json
└── assets/brief.svgUna herramienta compatible puede resolver las referencias y exportar los archivos que necesita su destino. Las credenciales se quedan fuera del paquete.
Cómo funciona
Tu instrucción.
Allí donde hace falta.
Todo empieza con un archivo. Tu agente puede recibirlo en local, leerlo de un registro o actualizarlo cuando llega un evento. Elige una vía de entrega para ver cómo llega el documento al agente.
Empieza con el archivo que ya tienes.
Guarda instruction.md en un proyecto o adjúntalo a una sesión. Configura el host del agente para que lo cargue, o expórtalo al archivo de instrucciones que ese agente espera.
- 01Elige una instrucción local
- 02Cárgala en el contexto del agente
- 03Guarda su origen en el control de versiones
# 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 búsqueda del archivo y la carga automática dependen del agente. Una exportación compatible conserva las pautas en el formato que este espera.
Una dirección. Dos formas de leerla.
Las personas abren una instrucción publicada en el navegador. Una integración puede pedir su Markdown y entregárselo a un agente. Elige una versión publicada o una referencia que siga las actualizaciones.
- 01Publica una instrucción
- 02Pide la representación en Markdown
- 03Carga la versión elegida
curl -H 'Accept: text/markdown' \
https://instruction.md/instruction-md/code-review Las instrucciones privadas usan la conexión autenticada del host. Una URL es una referencia; el host decide cuándo consultarla.
Pon las instrucciones a disposición como contexto.
Conecta un cliente MCP al registro de instrucciones. Un host puede descubrir instrucciones, leer un recurso por su URI e incluir el contenido elegido en el contexto del agente.
- 01Conecta un cliente MCP autorizado
- 02Selecciona un recurso de instrucción
- 03Lee su contenido y aplícalo
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/read",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} El host elige qué recursos se convierten en instrucciones. Una conexión no concede automáticamente herramientas ni permisos.
Un cambio es una señal para volver a leer.
Un cliente compatible puede seguir las actualizaciones de una instrucción. Una notificación del recurso le indica que obtenga y compruebe el contenido nuevo. Otras integraciones de eventos MCP pueden activar flujos de trabajo cuando el host las admite.
- 01Sigue la referencia elegida
- 02Recibe una notificación de cambio
- 03Vuelve a leer, verifica y después aplica
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} Las actualizaciones de recursos avisan de que el contenido ha cambiado; no son lo mismo que los eventos de los flujos de trabajo. La compatibilidad con eventos y suscripciones depende del cliente y del servidor.
La instrucción adecuada para cada evento.
Un webhook llega a tu integración cuando ocurre algo: se abre una incidencia, llega un formulario o se pide una revisión. Esa integración elige una instrucción, la obtiene e inicia el agente con el contexto del evento.
- 01Recibe y autentica el evento
- 02Determina la instrucción elegida
- 03Inicia una ejecución a través de tu host
event: issue.opened
instruction: instruction://acme/support-agent@stable
handoff:
- verify_event
- read_instruction
- provide_event_context
- start_authorized_run Esta receta describe una integración del lado del host, no un punto de conexión de webhooks integrado en instruction.md ni un bloque ejecutable del documento.
Prepáralo una vez. Entrega todo el contexto.
Antes de la entrega, resuelve las instrucciones heredadas, los fragmentos con nombre, las habilidades y los archivos multimedia locales. Empaqueta los recursos con el documento para que un host compatible pueda cargar un conjunto conocido de materiales.
- 01Resuelve las referencias y los bloques heredados
- 02Registra las versiones y los orígenes
- 03Entrega el documento y los recursos
daily-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/daily-brief.json
└── assets/day-plan.svg Un paquete puede hacer que los recursos sean autosuficientes. Las vinculaciones de cuentas, las credenciales y la ejecución siguen en manos del host que lo recibe.
El formato contiene las pautas. El host decide cómo cargarlas, verificarlas y ejecutarlas.
Conectar un agentePreguntas frecuentes
Algunas cosas
que conviene saber.
Desde tu primer archivo hasta un agente conectado.
Comentar la especificación¿Qué es instruction.md?
Una especificación abierta basada en Markdown para instrucciones de IA reutilizables. Un solo documento puede describir el propósito de un agente, pautas detalladas, reglas, habilidades, referencias y flujos de trabajo, con un significado estructurado para los lectores compatibles y una presentación enriquecida para las personas.
¿Por qué no basta con Markdown?
Markdown es una buena base. instruction.md añade significado explícito: un requisito puede tener un identificador y una justificación, una referencia MCP puede indicar las herramientas permitidas, y un bloque compartido se puede heredar conservando su origen. Las personas revisan los mismos detalles que analiza un lector compatible.
¿Todos los agentes de la lista entienden la especificación completa?
La compatibilidad varía. Un agente puede recibir Markdown legible, una exportación en su propio formato de instrucciones o contenido a través de una integración MCP. Los bloques con tipo, las referencias resueltas, la presentación enriquecida y la ejecución de flujos de trabajo requieren herramientas compatibles. El directorio de agentes no certifica la conformidad total con la especificación.
¿Qué relación tiene con AGENTS.md, CLAUDE.md y SKILL.md?
Esos archivos responden a convenciones ya existentes de agentes y habilidades. instruction.md ofrece una fuente reutilizable más rica, que puede hacer referencia a habilidades y adaptarse al formato de instrucciones del agente de destino. El agente que la recibe sigue aplicando sus propias reglas de búsqueda y su jerarquía de instrucciones.
¿Necesito el editor o el servicio de instruction.md?
Puedes escribir un archivo local en un editor de texto y guardarlo en el control de versiones. El editor web y las herramientas compatibles añaden vistas previas, validación, resolución de referencias e integraciones. Un registro alojado es solo una de las formas de entrega; el documento sigue siendo portátil.
¿Es costoso cargar instrucciones detalladas?
El formato permite todo el detalle que necesita una tarea, sin obligar a cargar cada recurso en cada ejecución. Los fragmentos con nombre, las referencias a habilidades y los paquetes permiten que las herramientas compatibles seleccionen y resuelvan el contexto pertinente. El host determina qué llega al modelo y cuánto contexto consume.
¿Escribir MUST o declarar un permiso de herramienta garantiza que se cumpla?
El documento expresa los requisitos del autor y las herramientas que tiene previsto permitir. Es el host del agente quien debe hacer cumplir la autorización, los pasos de aprobación y los controles de acceso. Una regla en Markdown no puede, por sí sola, conceder acceso ni garantizar que un modelo la cumpla.
¿Se ejecutan el código, las programaciones y los flujos de trabajo al abrir el archivo?
Abrir o mostrar una instrucción no la ejecuta. Un editor conectado puede ofrecer pruebas y evaluaciones explícitas. La ejecución en producción, la programación, el aislamiento y las aprobaciones humanas corresponden a un entorno de ejecución externo y autorizado.
¿Pueden actualizarse las instrucciones sin volver a desplegar un agente?
Un host compatible puede seguir una referencia dinámica y actualizarla mediante notificaciones MCP u otra integración. Una versión fijada no cambia. El host controla cuándo se verifica y se aplica una actualización, así que un evento no es una orden de aceptar a ciegas el contenido nuevo.
¿Puedo ampliar el lenguaje y mantenerlo todo autosuficiente?
Las extensiones con espacio de nombres propio pueden añadir objetos, bloques, renderizadores, resolutores e integraciones de pruebas. Los recursos de apoyo pueden venir de archivos locales y de URL; un paquete puede reunir esos materiales. Las extensiones declaran sus requisitos y conservan un contenido alternativo útil.
Empieza con una instrucción clara
Un documento.
Un mejor punto de partida para tu agente.
Instrucciones detalladas para los agentes. Una presentación clara para las personas. Un estándar compartido.