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.

instruction.md Recorrido por el producto

Escribe tu primera instrucción

Desde una página en blanco hasta las reglas que sigue un agente. No necesitas cuenta.

Agentes compatibles

Lleva tus instrucciones a los agentes que usas.

CodexClaude CodeCursorGemini CLIDevinGitHub CopilotAgentDbot.uaAmpJulesFactoryRoo CodeAidergooseKilo CodeopencodePhoenixZedSemgrepWarpVS CodeOnaWindsurfAutopilot & Coded AgentsAugment CodeJunieZeroClawAutohand Code CLIOpenHandsMuxLettaFirebenderClaudeChatGPTPiebaldpiDatabricks Genie CodeAgentmanTRAESpring AIMistral AI VibeCommand CodeVT CodeQodoLaravel BoostEmdashSnowflake Cortex CodeKiroWorkshopGoogle AI Edge Gallerynanobotfast-agentbubTabnineVitaSuperconductorDeep CodePulumi NeoHermes AgentOpenClaw

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

Se escribe una vez. Lo entienden todos.

morning-assistant.md
Markdown
:::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.
:::
Vista previa

Policy calendar

Calendar policy

Mustapproval

ask Alex before changing an invitation.

Because

calendar changes affect other people.

Shouldbrief

keep the daily brief under 150 words.

Neverprivacy

reveal a private event to another person.

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.

Una sola fuente de pautas

Escríbela. Revísala. Reutilízala con distintos agentes.

Explora ejemplos reales de instrucciones

Instrucciones 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.

:::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.
:::

Planning guidance Policy

Muststatus
if an invitation is tentative

preserve its tentative status.

Because

an unanswered invitation is not a commitment.

Shouldbrief

keep the daily brief under 150 words.

Because

the owner reads it on a phone.

Neverprivacy

reveal private event details to another person.

What good looks like

Your 09:00 catch-up is tentative. The 11:00 review is confirmed.

Daily brief

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.

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.

Mustapproval

ask Alex before changing an invitation.

Because

calendar changes affect other people.

MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.

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.

:::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.
:::

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.

CalendarMCP server

https://calendar.example.org/mcp

Account binding
Personal
Purpose
Read appointments for the daily brief.
Tool permissions
events.listAllow
availability.readAllow
events.deleteDeny
Human approval

Ask 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 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}.
O haz referencia a una habilidad existente
::skill{id=prioritize src="./skills/prioritize/SKILL.md"}

Skill prioritize

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.

Personas y agentes: se declaran una vez y se citan donde haga falta

Person:person[Alex]{ref=#owner}A Alex Owner
Agent / A2A:agent[Travel researcher]{ref=#travel} Travel researcher
La persona
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}
El agente
:::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.

Las declaraciones
---
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.

---
spec: "1"
extends:
  - uri: ./team.md
    as: team
    mode: pinned
    version: "1.2.0"
    sha256: sha256:9b823164daf4512c2a41748de43267d5661dbb3bfd88bdb73ad14c1b751ff18e
---

:::replace{target="#team/brief"}
SHOULD: keep the daily brief under 150 words.
:::

:::extend{target="#team/priorities" position=append}
MUST: identify an uninterrupted work period.
:::

::remove{target="#team/mail" reason="Calendar only."}
Resolved guidanceteam.md · v1.2.0
Team guidance → Morning assistant
Inherited

Keep tentative appointments tentative.team.md / status

Replaced

Keep the brief under 150 words.morning-assistant.md → team / brief

Extended

Identify an uninterrupted work period.morning-assistant.md → team / priorities

Removed

Review the inbox.team / mail · Calendar only.

Need just one part?::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.

MCP readHuman gateTwo outcomes
Fragmento de un paso
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
Revisión humana
start (manual)startmanualread (mcp.tool) calendar.events.listreadmcp.tooldraft (agent) Prepare a daily brief. Keep tentative appointments tentative.draftagentreview (human) Accept this daily brief?reviewhumanroute (switch) on {{ steps.review.output }}routeswitchaccepted (finish)acceptedfinishrevision (finish)revisionfinish

Dibujado a partir de la definición. Abrir la instrucción no inicia ninguna ejecución.

El flujo de trabajo completo
instruction/workflow
:::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.
:::
Activadores

Programaciones, eventos, webhooks, suscripciones MCP y A2A.

Control de flujo

Ramas, cuerpos con ámbito propio, trabajo en paralelo, bucles y esperas duraderas.

Límites

Presupuestos, esquemas, reintentos, idempotencia y decisiones humanas.

Explora el lenguaje de flujos de trabajo (en inglés)

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.

Calendar assistant
Petición

What is on my calendar tomorrow?

Dentro de lo permitido

Respuesta de ejemplo

I can use the calendar to prepare your brief, preserving the status of each appointment.

Instrucción aplicable
Maycalendar-read

use events.list to read appointments for the daily brief.

Because

reading appointments is within the declared calendar scope.

Herramienta declaradaevents.listLeer las citas

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

MUST[status]: keep tentative appointments tentative.

:::eval{id=status-check target=#status adapter="example/model-eval"}
cases:
  - name: preserve-status
    message: "09:00 catch-up, tentative; 11:00 review, confirmed."
    expect:
      contains: [tentative, confirmed]
      not_contains: ["both confirmed"]
:::
preserve-status

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 states

Counterexample

Your 09:00 catch-up and 11:00 review are both confirmed.

Loses the uncertainty in the source

Un 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.

Daily brief
SHOULD[brief]: keep the daily brief under 300 words.
SHOULD[brief]: keep the daily brief under 150 words.
Reason

The owner reads the brief on a phone.

Identity preserved

#brief remains the same named rule.

Review state

Draft, awaiting a human decision.

El registro de autoría: cuerpo y metadatos finales
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.

::::columns{count=2}
:::column
### Commitments
- 09:00 · Catch-up — **tentative**
- 11:00 · Review — confirmed
:::
:::column
### Your focus
- [ ] Draft the proposal
- [ ] Leave room for a break
:::
::::

:::details{title="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.

A day with room to focus 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. Your day, with uncertainty intact. An illustrative reading view 08:0010:0012:0014:0016:0018:00 Calendar Catch-up09:00 · Tentative Review11:00 · Confirmed Suggested Draft the proposal13:00–15:00 · Focus time
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.
En la instrucción
:::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
  • PDF

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.

Python · Pydantic
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.

Origen

Markdown legible

→
Análisis

Estructura con tipos

→
Resolución

Referencias y orígenes

→
Presentación

Agentes y personas

El mismo requisito del autor

Muststatus

keep tentative appointments tentative.

Un renderizador cambia la presentación. La identidad y la fuerza de la regla siguen siendo explícitas.

El modelo estandarizado
{
  "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{id=calendar-changes title="Calendar changes"}
Never send, delete, or move an invitation without the owner's approval.
:::

Guardrail

Calendar changes

Never send, delete, or move an invitation without the owner’s approval.

Un contrato de salida estructurado
:::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.
:::
Daily briefJSON output
{
  "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.

---
spec: "1"
extensions:
  charts:
    id: dev.example/charts
    version: "1.0.0"
    required: false
---

:::charts:metric{label="Focus tasks" value=1}
Recommend **one** achievable focus task.
:::

With the extension

Focus tasks
1achievable priority

Recommend one achievable focus task.

charts:metric · dev.example/charts @ 1.0.0

Without 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.

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 }
01

Identidad y configuración

Versión, parámetros, referencias, extensiones y destinos de exportación.

02

Un solo cuerpo compartido

Instrucciones, políticas, personas, habilidades, contenido multimedia y flujos de trabajo. Legible para personas y para agentes.

03

El registro de autoría

Autores, historial, fuentes e información de revisión tras un simple separador ---.

04

Un paquete autosuficiente

morning-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/morning-brief.json
└── assets/brief.svg

Una 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.

  1. 01Elige una instrucción local
  2. 02Cárgala en el contexto del agente
  3. 03Guarda su origen en el control de versiones
instruction.md · contenido del archivo
# 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.

El formato contiene las pautas. El host decide cómo cargarlas, verificarlas y ejecutarlas.

Conectar un agente

Preguntas 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.