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.
---
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.
| Palabra | Qué significa | Por ejemplo |
|---|---|---|
MUST | Un requisito | ask Alex before changing an invitation. |
SHOULD | Una opción por defecto meditada | keep the daily brief under 150 words. |
MAY | Una elección permitida | suggest a focus task when time is available. |
NEVER | Una prohibición | reveal a private event to another person. |
SHOULD NOT | Una acción desaconsejada | plan around it as a confirmed commitment. |
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:
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.
:::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.
::: :::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.
:::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).
:::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.
:::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.
::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.
---
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
- Flujos de trabajo: procesos con pasos, decisiones y aprobaciones.
- Conceptos: cómo se versionan, se comparten y se siguen las instrucciones.
- La especificación (en inglés): cada parte del lenguaje, con exactitud.