Відкрита специфікація мови
Інструкції для ШІ-агентів у Markdown.
instruction.md — це відкритий формат, яким ШІ-агентам пояснюють, як працювати. Один файл Markdown містить правила, яких агент має дотримуватися, інструменти й навички, якими він може користуватися, і робочі процеси, які він виконує. Люди читають і перевіряють його як зрозумілий документ, а агенти дотримуються того самого тексту. Напишіть інструкцію один раз і використовуйте її з агентами, з якими вже працюєте.
Підтримувані агенти
Використовуйте свої інструкції з агентами, з якими працюєте.
Читабельний Markdown, експорт у формат конкретного агента або підключення через MCP. Підтримка розширеного синтаксису та інтеграцій залежить від хоста.
Уперше тут?
Почніть із посібника
Коротке відео, покрокове завдання та стисла стаття. Кожен займає кілька хвилин, а для першого не потрібен обліковий запис. Усі посібники
-
Відео · 2 хв Напишіть першу інструкцію Подивіться, як у редакторі пишуть інструкцію: від порожньої сторінки до правил, яких дотримується агент. Обліковий запис не потрібен. -
Крок за кроком · 5 хв Опублікуйте її та підключіть агента Увійдіть, опублікуйте інструкцію та спрямуйте на неї ШІ-агента, щоб він дотримувався написаного. -
Коротка стаття · 3 хв Як працюють версії Чому чернетка ніколи не застає агента зненацька: чернетки, версії і що означає «чинна версія».
Написано один раз. Зрозуміло всім.
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.
Простий текст, який легко перевірити. Структурований зміст, який сумісна програма зберігає без втрат.
Завантажити прикладЧому instruction.md?
Деталі, потрібні агентам.
Ясність, потрібна людям.
Налаштування агента часто розкидані по промптах, конфігурації, файлах навичок і знаннях команди. Зберіть настанови в один багаторазовий документ, який люди можуть читати, а сумісні інструменти — однаково тлумачити.
Досить деталей, щоб бути корисною.
Тримайте разом задум, контекст, винятки, приклади й обґрунтування. Дайте точним настановам структуру, на яку агент може послатися.
Зміст, який не губиться під час розбору.
Називайте правила, визначайте об’єкти та зберігайте походження. Сумісна програма відрізняє вимогу від рекомендації, а посилання — від дозволу на інструмент.
Документ, який люди можуть перевірити.
Показуйте дозволи, робочі процеси, людей і навички в контексті. Зробіть інструкцію зрозумілою тим, хто її пише, затверджує й підтримує.
Напишіть. Перевірте. Використовуйте з різними агентами.
Перегляньте справжні приклади інструкційЗмістовні інструкції
Досить деталей,
щоб передати ваш задум.
Інструкції можуть бути короткими або дуже докладними. Дайте агентові умови, причини, приклади й контекст, які йому потрібні. Мова робить ці деталі явними, а зручний режим читання допомагає людям у них не загубитися.
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
Докладність — це зміст, закладений автором. Компонування може його впорядкувати; програма-читач зберігає деталі.
Приклади інструкцій
Різні обов’язки.
Одна спільна мова.
Особистий асистент, помічник у дослідженнях чи ціла команда можуть почати з того самого формату. Виберіть інструкцію, а потім перемикайтеся між режимом читання й текстом Markdown, що стоїть за ним.
Виберіть інструкцію
Подивіться, які настанови потрібні кожній ролі.
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"} Правила й політики
Зробіть межі
помітними.
Вимога, рекомендація і вибір важать по-різному. Скажіть, що саме ви маєте на увазі. Додайте назву й причину, щоб люди могли перевірити інструкцію, а агенти — точно на неї посилатися.
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.
Інструменти й дозволи
Підключіть можливість.
Залиште її межі на видноті.
Посилання на MCP може містити призначення, прив’язку до облікового запису та явний перелік дозволених інструментів. Перевіряйте, чим агент має користуватися, поруч із настановами про те, як саме.
Посилання лише описує підключення. Облікові дані й перевірка дозволів залишаються за хостом; відкриття цієї сторінки нічого не підключає.
https://calendar.example.org/mcp
- Account binding
- Personal
- Purpose
- Read appointments for the daily brief.
events.listAllowavailability.readAllowevents.deleteDenyAsk Alex before changing an invitation.
Навички, люди й агенти
Дайте агентові
більше для роботи.
Опишіть навичку просто в інструкції або пошліться на ту, яку вже підтримуєте. Назвіть людей, які можуть ухвалювати рішення, і агентів-фахівців, які можуть допомогти. Використовуйте ці об’єкти всюди, де вони потрібні настановам.
::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.
Люди й агенти: оголошені один раз, згадані будь-де
::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.
::: Параметри
Ті самі настанови.
Інший контекст.
Оголосіть значення, які можуть змінюватися: часовий пояс, мову, довжину відповіді. Явні вхідні дані дають змогу використовувати інструкцію повторно, і агентові не доводиться вгадувати, що означає заповнювач.
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. Успадкування
Спільні настанови.
Власні зміни.
Успадкуйте спільну інструкцію, а потім замініть, доповніть або вилучіть названі блоки. Джерело кожного рішення залишається видимим. Закріпіть посилання за версією, щоб оновлення були передбачуваними, або виберіть живе посилання, якщо воно має стежити за джерелом.
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}Робочі процеси
Процес — це частина
інструкції.
Власна мова робочих процесів описує тригери, дані, рішення та результати. Читайте те саме визначення як Markdown, як структурований граф або як модель, готову для хоста. Мова робочих процесів і її документація є частиною instruction.md.
Типізоване рішення людини з явними результатами: прийняти або доопрацювати.
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 Намальовано з визначення. Відкриття інструкції не починає запуск.
Повний робочий процес
:::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.
::: Незалежні гілки в межах одного бюджету запуску об’єднуються перед наступним кроком.
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
Намальовано з визначення. Відкриття інструкції не починає запуск.
Повний робочий процес
:::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 }}"
::: Повторні спроби, обмеження частоти, ідемпотентність і політика повторного відтворення описують різні межі.
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 Намальовано з визначення. Відкриття інструкції не починає запуск.
Повний робочий процес
:::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 }}"
::: Власний розклад оголошує, коли робочий процес може початися. Активація залишається явною.
steps:
weekday:
kind: schedule
cron: 0 8 * * 1-5 Намальовано з визначення. Відкриття інструкції не починає запуск.
Повний робочий процес
:::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 }}"
::: Вкладений блок обробляє кожен елемент з обмеженим паралелізмом і заданою частотою.
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
Намальовано з визначення. Відкриття інструкції не починає запуск.
Повний робочий процес
:::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 }}"
::: Розклади, події, вебхуки, підписки MCP та A2A.
Розгалуження, вкладені блоки, паралельна робота, цикли й тривалі очікування.
Бюджети, схеми, повторні спроби, ідемпотентність і рішення людини.
Сценарії рішень
Настанови залишаються ясними.
Ситуація змінюється.
Та сама інструкція може описати, що дозволено, що потребує рішення людини, а що залишається приватним. Виберіть ситуацію, щоб побачити відповідні настанови та приклад відповіді.
Виберіть ситуацію
Одна інструкція для календаря, чотири запити.
What is on my calendar tomorrow?
Приклад відповіді
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.
Приклад відповіді
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.
Приклад відповіді
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?
Приклад відповіді
The 09:00 catch-up is tentative. It has not been confirmed.
preserve its tentative status.
an unanswered invitation is not a confirmed commitment.
Це авторські приклади: на цій сторінці не працює жоден агент чи інструмент. Дозволи на інструменти та погодження людиною забезпечує хост.
Прочитати інструкцію для календаря
---
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.
::: Перевірки
Зробіть очікування
таким, яке можна перевірити.
Названому правилу можна дати тестовий приклад для рецензування. Тримайте вхідні дані, очікувану поведінку й контрприклад поруч із настановами. Інтеграція з редактором може явно запустити перевірку з дозволу хоста.
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 sourceЦе авторський приклад, а не справжній запуск. Перевірка посилається на #status; результат тесту може містити дайджест джерела, тож рецензенти знають, яку саме інструкцію перевірено.
Авторство й рецензування
Збережіть зміну.
Збережіть причину.
Стала назва правила полегшує обговорення змін. Наприкінці документа можна зберігати історію авторства та джерела, а основний текст містить настанови, спільні для людей і агентів.
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 } Зручне відображення
Добру інструкцію
має бути приємно читати.
Використовуйте заголовки, списки, таблиці й код. Додавайте колонки, вкладки та згорнуті деталі там, де вони полегшують перевірку. Кожна частина тексту залишається доступною і людям, і агентам.
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.
Точність у джерелі.
Код, скрипти, схеми, формули, Mermaid і діаграми послідовностей зберігають свій рідний запис.
Контекст завжди поруч.
Посилайтеся на зображення, відео, аудіо, PDF і редаговані малюнки з підписами, описами та транскриптами.
Корисний запасний варіант.
Читабельний Markdown залишається корисним і без спеціального рендерера. Компонування лише покращує те, як люди бачать спільний вміст.
Візуальний контекст
Дещо краще
показати.
Додайте до інструкції малюнок, діаграму, документ або запис. Тримайте джерело й корисний опис разом, щоб наочне пояснення подорожувало разом із настановами.
:::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. Мови й інструменти
Працюйте зі своїми технологіями.
Інструкція залишається одна.
Пишіть звичайний текст поруч із мовами й форматами, якими ваша команда вже користується. Тримайте посилання на пакети, код і ресурси разом із настановами, а потім редагуйте, відображайте, перевіряйте й експортуйте їх сумісними інструментами.
Код і скрипти
- Python
- TypeScript
- JavaScript
- Bash
- SQL
- Go
- Rust
- Java
- C++
- C#
Дані й конфігурація
- JSON
- YAML
- TOML
- XML
- CSV
- HTML
- CSS
Діаграми й контекст
- Mermaid
- Workflows
- Math
- SVG
- Images
- Audio
- Video
Код зберігає власну мову.
Використовуйте рідний синтаксис, імпорти пакетів і типи. Наприклад, модель Python може описати структуру щоденного зведення.
Блок коду зберігає свою мову. Вимоги до пакетів і кроки налаштування є авторським контекстом; що встановлювати чи запускати, вирішують сумісні хости.
from pydantic import BaseModel
class DailyBrief(BaseModel):
commitments: list[str]
priorities: list[str]
open_decisions: list[str] Редактор і студія
Файл, який люди можуть писати.
Простір, де його можна перевірити.
Почніть із Markdown, а потім перенесіть той самий вміст у візуальний робочий простір. Зручне відображення допомагає разом розібратися в правилах, посиланнях і структурі.
Пишіть у вихідному тексті
Текст залишається читабельним і зручним для ведення версій.
Перевіряйте в зручному перегляді
Побачте зміст, що стоїть за об’єктами, правилами й компонуванням.
Перевіряйте й тестуйте
Використовуйте схеми та явні інтеграції для тестування.
Розв’язуйте й пакуйте
Нехай сумісні інструменти зберуть посилання та ресурси.
Стандартний розбір
Одна мова.
Однаковий зміст.
Стандартна граматика перетворює текст на названі, типізовані об’єкти. Сумісні інструменти можуть розв’язувати посилання, зберігати походження та створювати передбачувані подання для агентів. Інтерфейси для людей показують ту саму структуру з чіткими правилами, зручним компонуванням і корисними елементами керування.
Читабельний Markdown
Типізована структура
Посилання й походження
Агенти й люди
Та сама авторська вимога
keep tentative appointments tentative.
Рендерер змінює вигляд. Ідентичність і сила правила залишаються явними.
{
"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"
}
]
}
]
} Запобіжники й контракти результату
Визначте межі.
Опишіть результат.
Запобіжник привертає увагу до межі. Контракт результату описує, що має містити корисна відповідь, зі схемою, коли важлива структура. Люди можуть перевірити очікування, а агенти отримують точні авторські настанови.
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.
Розширення
Місце для вашого
власного словника.
Розширення можуть додавати типи блоків, вбудовані об’єкти, рендерери, розв’язувачі посилань та інтеграції для тестування. Простори назв роблять доповнення зрозумілими. Версійована декларація каже програмам-читачам, що потрібно, а запасний варіант залишає вміст корисним.
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.
Переносні документи
Настанови.
І все, що довкола них.
Початкові метадані описують інструкцію. Основний текст несе її зміст. Наприкінці зберігаються відомості про авторство та джерела. Посилайтеся на ресурси за URL чи локальним шляхом або спакуйте їх разом в один пакет.
---
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 } Ідентичність і налаштування
Версія, параметри, посилання, розширення та цілі експорту.
Один спільний текст
Інструкції, політики, люди, навички, медіа та робочі процеси. Зрозуміло і людям, і агентам.
Відомості про авторство
Автори, історія, джерела та дані рецензування після простого роздільника ---.
Самодостатній пакет
morning-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/morning-brief.json
└── assets/brief.svgСумісний інструмент може розв’язати посилання й експортувати файли, потрібні цільовій системі. Облікові дані залишаються поза пакетом.
Як це працює
Ваша інструкція.
Там, де вона потрібна.
Усе починається з файлу. Агент може отримати його локально, прочитати з реєстру або оновити, коли надходить подія. Виберіть спосіб доставки, щоб побачити, як документ потрапляє до агента.
Почніть із файлу, який у вас уже є.
Тримайте instruction.md у проєкті або додайте його до сесії. Налаштуйте хост агента так, щоб він завантажував цей файл, або експортуйте його у файл інструкцій, якого очікує агент.
- 01Виберіть локальну інструкцію
- 02Завантажте її в контекст агента
- 03Зберігайте джерело в системі контролю версій
# Daily assistant
Prepare a short brief from my calendar.
:::policy{id=calendar}
MUST[status]: preserve tentative event status.
NEVER[send]: send invitations without approval.
::: Пошук файлу та автоматичне завантаження залежать від агента. Сумісний експорт зберігає настанови у форматі, якого той очікує.
Одна адреса. Два способи читання.
Люди відкривають опубліковану інструкцію в браузері. Інтеграція може запросити її Markdown і передати агентові. Виберіть опубліковану версію або посилання, яке стежить за оновленнями.
- 01Опублікуйте інструкцію
- 02Запросіть подання Markdown
- 03Завантажте вибрану версію
curl -H 'Accept: text/markdown' \
https://instruction.md/instruction-md/code-review Приватні інструкції використовують автентифіковане підключення хоста. URL — це посилання; хост вирішує, коли його читати.
Зробіть інструкції доступними як контекст.
Підключіть MCP-клієнт до реєстру інструкцій. Хост може знаходити інструкції, читати ресурс за його URI та додавати вибраний вміст до контексту агента.
- 01Підключіть авторизований MCP-клієнт
- 02Виберіть ресурс інструкції
- 03Прочитайте й застосуйте його вміст
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/read",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} Хост вибирає, які ресурси стають інструкціями. Підключення саме собою не надає ні інструментів, ні дозволів.
Зміна — це сигнал прочитати знову.
Сумісний клієнт може стежити за оновленнями інструкції. Сповіщення про ресурс спонукає його отримати й перевірити новий вміст. Інші інтеграції з подіями MCP можуть запускати робочі процеси, якщо хост це підтримує.
- 01Стежте за вибраним посиланням
- 02Отримайте сповіщення про зміну
- 03Перечитайте, перевірте, потім застосуйте
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"uri": "instruction://acme/support-agent@stable"
}
} Оновлення ресурсу сигналізують про змінений вміст; це не те саме, що події робочих процесів. Підтримка подій і підписок залежить від клієнта й сервера.
Доречна інструкція для кожної події.
Вебхук надходить до вашої інтеграції, коли щось стається: відкрито звернення, надійшла форма або запитано рецензію. Інтеграція вибирає інструкцію, отримує її та запускає агента з контекстом події.
- 01Отримайте й автентифікуйте подію
- 02Визначте потрібну інструкцію
- 03Почніть запуск через свій хост
event: issue.opened
instruction: instruction://acme/support-agent@stable
handoff:
- verify_event
- read_instruction
- provide_event_context
- start_authorized_run Цей рецепт описує інтеграцію на боці хоста, а не вбудовану точку доступу для вебхуків instruction.md чи виконуваний блок документа.
Підготуйте один раз. Передайте весь контекст.
Перед доставкою розв’яжіть успадковані інструкції, названі фрагменти, навички та локальні медіа. Спакуйте ресурси разом із документом, щоб сумісний хост міг завантажити відомий набір матеріалів.
- 01Розв’яжіть посилання та успадковані блоки
- 02Запишіть версії та походження
- 03Доставте документ і ресурси
daily-assistant/
├── instruction.md
├── team.md
├── skills/prioritize/SKILL.md
├── workflows/daily-brief.json
└── assets/day-plan.svg Пакет може зробити ресурси самодостатніми. Прив’язки до облікових записів, облікові дані та виконання залишаються за хостом, який його отримує.
Формат несе настанови. Хост вирішує, як їх завантажити, перевірити й виконати.
Підключити агентаЗапитання
Кілька речей,
які варто знати.
Від першого файлу до підключеного агента.
Обговорити специфікаціюЩо таке instruction.md?
Відкрита специфікація на основі Markdown для багаторазових інструкцій ШІ. Один документ може описати призначення агента, докладні настанови, правила, навички, посилання та робочі процеси — зі структурованим змістом для сумісних програм і зручним відображенням для людей.
Чому не досить звичайного Markdown?
Звичайний Markdown — добра основа. instruction.md додає явний зміст: вимога може мати ідентифікатор і обґрунтування, посилання на MCP — перелік дозволених інструментів, а спільний блок можна успадкувати зі збереженням його походження. Люди перевіряють ті самі деталі, які розбирає сумісна програма.
Чи кожен агент зі списку розуміє всю специфікацію?
Підтримка різна. Агент може отримати читабельний Markdown, експорт у власному форматі інструкцій або вміст через інтеграцію MCP. Типізовані блоки, розв’язані посилання, розширене відображення та виконання робочих процесів потребують сумісних інструментів. Каталог агентів не засвідчує повної відповідності специфікації.
Як це пов’язано з AGENTS.md, CLAUDE.md і SKILL.md?
Ці файли обслуговують наявні домовленості агентів і навичок. instruction.md дає багатше джерело для повторного використання: воно може посилатися на навички й пристосовуватися до формату інструкцій цільового агента. Агент-отримувач і далі діє за власними правилами пошуку та ієрархією інструкцій.
Чи потрібен мені редактор або сервіс instruction.md?
Ви можете написати локальний файл у текстовому редакторі й тримати його в системі контролю версій. Вебредактор і сумісні інструменти додають попередній перегляд, перевірку, розв’язання посилань та інтеграції. Реєстр на нашому хостингу — лише один зі способів доставки; документ залишається переносним.
Чи дорого завантажувати докладні інструкції?
Формат дає змогу вказати стільки деталей, скільки потрібно завданню, і не вимагає завантажувати кожен ресурс для кожного запуску. Названі фрагменти, посилання на навички та пакети дають сумісним інструментам змогу вибирати й розв’язувати доречний контекст. Хост визначає, що потрапляє до моделі і скільки контексту це займає.
Чи забезпечує MUST або оголошений дозвіл на інструмент їх дотримання?
Документ виражає вимоги автора та задуманий перелік інструментів. Авторизацію, етапи погодження й контроль доступу має забезпечити хост агента. Саме правило в Markdown не може ні надати доступ, ні гарантувати, що модель його дотримається.
Чи запускаються код, розклади та робочі процеси, коли файл відкривають?
Відкриття або відображення інструкції нічого не виконує. Підключений редактор може запропонувати явні тести й перевірки. Виконання в продакшні, планування, ізоляція та погодження людиною належать авторизованому зовнішньому середовищу виконання.
Чи можуть інструкції оновлюватися без повторного розгортання агента?
Сумісний хост може стежити за живим посиланням і оновлювати його через сповіщення MCP або іншу інтеграцію. Закріплена версія залишається незмінною. Хост вирішує, коли оновлення перевіряється й застосовується, тож подія не є вказівкою сліпо прийняти новий вміст.
Чи можна розширити мову й зберегти все самодостатнім?
Розширення з власними просторами назв можуть додавати об’єкти, блоки, рендерери, розв’язувачі та інтеграції для тестування. Допоміжні ресурси можна брати з локальних файлів і за URL; пакет може зібрати ці матеріали разом. Розширення оголошують свої вимоги та зберігають корисний запасний вміст.
Почніть із чіткої інструкції
Один документ.
Краща відправна точка для вашого агента.
Змістовні інструкції для агентів. Зрозуміле відображення для людей. Спільний стандарт.