El lenguaje

Una instrucción es texto normal. Unos pocos añadidos te permiten decir con exactitud lo que importa, para que las personas puedan revisarlo y todos los agentes lo entiendan igual. Este recorrido los muestra de uno en uno, con el mismo ejemplo de principio a fin: un asistente que planifica el día de alguien. Los ejemplos se muestran en inglés, tal como están escritos.

Empieza con texto sencillo

La mayor parte de una instrucción es prosa: para qué sirve el agente y cómo debe trabajar. Una cabecera breve al principio da al documento un título y una versión. Las notas para las personas, como quién lo escribió y por qué cambió, van al final del todo, y el agente nunca las recibe.

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 }

Reglas

Una línea que empieza con una de cinco palabras es una regla. La palabra indica lo estricta que es, y un nombre opcional entre corchetes permite referirse a ella. BECAUSE: en la línea siguiente da el motivo, lo que ayuda al agente a aplicar la regla con sensatez.

PalabraQué significaPor ejemplo
MUSTUn requisitoask Alex before changing an invitation.
SHOULDUna opción por defecto meditadakeep the daily brief under 150 words.
MAYUna elección permitidasuggest a focus task when time is available.
NEVERUna prohibiciónreveal a private event to another person.
SHOULD NOTUna acción desaconsejadaplan around it as a confirmed commitment.
Una regla y su motivo
MUST[approval]: ask Alex before changing an invitation.
BECAUSE: calendar changes affect other people.

Una regla también puede decir cuándo se aplica, entre paréntesis después de su palabra:

Una regla con una condición
SHOULD NOT (if an invitation is tentative): plan around it as a confirmed commitment.
BECAUSE: the attendee has not accepted yet.

Políticas y salvaguardas

Las reglas que van juntas se pueden agrupar en una política con su propio título, para que se revisen, se compartan y se sustituyan como una sola. Una salvaguarda marca un límite que debe saltar a la vista de cualquiera que lea.

Una política
:::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.
:::
Una salvaguarda
:::guardrail{id=calendar-changes title="Calendar changes"}
Never send, delete, or move an invitation without the owner's approval.
:::

Instrucciones detalladas

Las reglas cortas no siempre bastan. Puedes añadir condiciones, un ejemplo de cómo es un buen resultado y la forma de la respuesta que esperas. Cada parte está marcada como lo que es, así el agente distingue una orientación de un ejemplo, y quien lee las ve dispuestas con claridad.

Una orientación, un ejemplo y el resultado esperado
:::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.
:::

Herramientas

Una instrucción puede nombrar las herramientas que un agente puede usar, como un calendario conectado mediante MCP, y decir cuáles de sus acciones están permitidas. Aquí el asistente puede leer los eventos y la disponibilidad (events.list, availability.read), pero nunca eliminar un evento (events.delete).

Una conexión con una herramienta
:::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.
:::

Habilidades

Una habilidad es una forma reutilizable de hacer una tarea, escrita como pasos. Escríbela una vez, dale un nombre y haz referencia a ella donde haga falta. Esta se llama «Prioritize the day» (priorizar el día): elegir una tarea útil y alcanzable en la que centrarse.

Una habilidad y una referencia a ella
:::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}.

Personas

Las instrucciones dependen a menudo de personas: quién es responsable de una decisión, quién debe aprobar un cambio. Declara a una persona una vez, y las reglas pueden referirse a ella por su nombre. Quien lee ve de quién se trata, y las herramientas pueden enlazar con ella.

Una persona y una regla que la nombra
::person{id=owner title="Alex" role=owner src="https://example.org/people/alex"}

MUST[approval]: ask :person[Alex]{ref=#owner} before changing an invitation.
BECAUSE: calendar changes affect other people.

Todo junto

Aquí está el asistente completo en un solo archivo: su cabecera, su propósito, una regla, el calendario que puede usar, una habilidad, un pequeño flujo de trabajo y las notas para las personas. Abre el editor para escribir el tuyo; muestra el mismo documento como una página que la gente puede leer.

morning-assistant.md
---
spec: "1"
title: Morning assistant
version: "1.0.0"
---

# Morning assistant

Prepare a useful daily brief.

MUST[status]: keep tentative appointments tentative.
BECAUSE: an invitation is not a commitment.


:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

:::skill{id=prioritize title="Prioritize the day"}
Choose one useful, achievable focus task.

1. Review commitments and available focus time.
2. Choose one useful, achievable task.
3. Explain why it is a good first priority.
:::

Use :skill[Prioritize the day]{ref=#prioritize}.

:::workflow{id=brief dialect="instruction/workflow"}
name: morning-brief
steps:
  start:
    kind: manual
  read:
    kind: mcp.tool
    depends_on:
      - start
    server: calendar
    tool: events.list
    timeout: 30s
    retry:
      max: 2
      backoff: 2s
  draft:
    kind: agent
    depends_on:
      - read
    instruction: Prepare a daily brief. Keep tentative appointments tentative.
  review:
    kind: human
    depends_on:
      - draft
    question: Accept this daily brief?
    schema:
      type: string
      enum:
        - accept
        - revise
    timeout: 2h
  route:
    kind: switch
    depends_on:
      - review
    on: "{{ steps.review.output }}"
    cases:
      accept: accepted
      revise: revision
  accepted:
    kind: finish
    depends_on:
      - route
    output: "{{ steps.draft.output }}"
  revision:
    kind: finish
    depends_on:
      - route
    status: cancelled
    reason: The reviewer requested a revision.
:::

---
authors: [Alex]
history:
  - summary: Preserve appointment status.
sources:
  - { title: Team guidance, uri: ./team.md }

Por dónde seguir