# 📝 MDA Open Spec — Markdown для агентов > Надмножество Markdown для документов, ориентированных на агентов. **Один источник, множество целей** — компилируется в `.md`-файлы, которые уже умеют загружать все основные runtime-окружения агентов. **Защита от подмены при загрузке** — каждый артефакт несёт воспроизводимый дайджест содержимого, а подписанные артефакты — подписи, заякоренные в Sigstore. Ни агенту, загружающему документ, ни человеку, проверяющему его, не придётся доверять неподписанному blob'у. [![Latest release](https://img.shields.io/badge/release-v1.0.0--rc.3-blue)](https://github.com/sno-ai/mda/releases/tag/v1.0.0-rc.3) [![License](https://img.shields.io/github/license/sno-ai/mda)](https://github.com/sno-ai/mda/blob/main/LICENSE) [![Docs](https://img.shields.io/badge/docs-mda.sno.dev-3b82f6)](https://mda.sno.dev) [![GitHub stars](https://img.shields.io/github/stars/sno-ai/mda?style=flat&color=yellow)](https://github.com/sno-ai/mda/stargazers) **Читать на других языках:** [English](../../README.md) · [中文](README.zh-CN.md) · [Deutsch](README.de.md) · [Español](README.es.md) · [Français](README.fr.md) · **Русский** · [한국어](README.ko.md) · [日本語](README.ja.md) · [हिन्दी](README.hi.md) ## Что такое MDA До сих пор один и тот же навык приходилось публиковать четыре раза. Один — как `SKILL.md` для runtime-окружений agentskills.io. Другой — как `AGENTS.md` для экосистемы AAIF. Третий — как `MCP-SERVER.md` с sidecar-файлом JSON. Четвёртый — как `CLAUDE.md`. Контент один и тот же, формы frontmatter — четыре. Поправил один файл, забыл про остальные — и через месяц четыре файла тихо разошлись в четыре слегка разных набора инструкций. Вы пишете один `.mda`. Компилятор выпускает остальное. ![Один источник .mda, скомпилированный детерминированным конвейером в SKILL.md, AGENTS.md, MCP-SERVER.md и CLAUDE.md](../../images/hero-compile-pipeline.png) ``` ┌─────────────────────────┐ │ .mda (source) │ ← MDA superset └────────────┬────────────┘ │ mda compile ▼ ┌─────────────────────────────────────────────────────────┐ │ /SKILL.md (+ scripts/, references/, assets/) │ │ AGENTS.md │ │ /MCP-SERVER.md (+ mcp-server.json sidecar) │ │ CLAUDE.md │ └─────────────────────────────────────────────────────────┘ drop-in compatible ``` И ни один из этих четырёх файлов не способен сказать, кто его подписал. У агента, загружающего `SKILL.md`, нет способа убедиться, что содержимое соответствует тому, что вы написали, а у куратора, проверяющего `AGENTS.md`, нет способа узнать, через чьи руки файл прошёл между мерджем и загрузкой. В стандартных формах frontmatter попросту негде разместить дайджест содержимого или подпись, поэтому решение о доверии тихо сводится к «мы как-то доверяем репозиторию». MDA несёт `integrity.digest`, канонизированный по JCS, и `signatures[]` в DSSE-конверте, заякоренные в Sigstore, прямо в самом frontmatter. Обе стороны — агент в момент загрузки и человек в момент ревью — могут принять реальное решение о доверии относительно конкретного артефакта, а не относительно ощущения от репозитория. Защита от подмены и проверка подписанта заложены в контракт, а не приклеены сбоку. ![Три добавления MDA поверх стандартного Markdown: расширенный frontmatter, типизированные связи через сноски, подписанная идентичность](../../images/three-additions.png) `.mda` добавляет три вещи поверх стандартного Markdown. Все они опциональны. 1. **Расширенный YAML-frontmatter.** Помимо открытого стандартного минимума с `name` и `description`, MDA несёт `doc-id`, `version`, `requires`, `depends-on`, `relationships` и `tags`. Инструменты, понимающие агентов, используют их для маршрутизации, разрешения зависимостей и обхода графа. См. [`spec/v1.0/02-frontmatter.md`](../../spec/v1.0/02-frontmatter.md) и [`spec/v1.0/10-capabilities.md`](../../spec/v1.0/10-capabilities.md). 2. **Типизированные связи через сноски.** Стандартные сноски Markdown, полезной нагрузкой которых служит JSON-объект: `parent`, `child`, `related`, `cites`, `supports`, `contradicts`, `extends`. При компиляции зеркалируются в `metadata.mda.relationships` в порядке появления в теле. См. [`spec/v1.0/03-relationships.md`](../../spec/v1.0/03-relationships.md). 3. **Криптографическая идентичность.** Дайджест `integrity`, канонизированный по JCS, плюс `signatures[]` в DSSE-конверте, заякоренные в Sigstore. Скомпилированный `.md` несёт воспроизводимое обнаружение подмены, не приклеенное задним числом. См. [`spec/v1.0/08-integrity.md`](../../spec/v1.0/08-integrity.md) и [`spec/v1.0/09-signatures.md`](../../spec/v1.0/09-signatures.md). Источник `.mda`, содержащий только открытый стандартный frontmatter, компилируется в `.md` без изменений. Используйте ровно столько MDA, сколько нужно вашему проекту. ## Зачем это нужно Если честно — я раз за разом публиковал один и тот же навык по четыре раза. Один контент, четыре обёртки. У каждого runtime были свои представления о том, какой frontmatter положен сверху и что считать вендор-специфичным. На третий или четвёртый раз, когда я скопировал абзац между `SKILL.md` и `AGENTS.md`, а потом наблюдал, как они расходятся, — я начал писать это. Дело в том, что дублирование — ещё не самая большая беда. Самое неприятное — то, чего ни в одном из этих форматов попросту не выразить. Нельзя сказать: «этот навык зависит от вон того, версии `^1.2.0`, с таким-то дайджестом содержимого». Нельзя сказать: «этот файл подписан вот этой идентичностью с вот таким индексом в Rekor». Нельзя сказать: «связь между этим документом и тем — это `supports`, а не `cites`». Эту информацию некуда положить, и она оседает в прозе, где ни агенты, ни люди не могут на неё надёжно опереться. MDA кладёт всё это во frontmatter и сноски в формах, которые валидирует JSON Schema. Тело Markdown по-прежнему рендерится. Стандартные поля по-прежнему загружаются. Всё новое — опционально. Вот, собственно, и весь смысл. Подробнее — два документа уходят глубже. Оба возводят каждое утверждение к разделу спецификации и оба прямо называют текущие пробелы экосистемы. Прочитайте, если решаете, стоит ли внедрять. - [**`docs/v1.0/ai-agent-core-value.md`**](../../docs/v1.0/ai-agent-core-value.md) — пять пунктов с прицелом на runtime-окружения, harness'ы, валидаторы и диспетчеры. Что MDA даёт агенту в момент загрузки: структурированный `requires` для типизированной диспетчеризации, проверяемое доверие при загрузке, машиночитаемые рёбра графа, диспетчеризация целей по имени файла за один lookup и одинаковый контракт валидации для вывода, написанного агентом, и вывода, выпущенного компилятором. - [**`docs/v1.0/human-curator-user-core-value.md`**](../../docs/v1.0/human-curator-user-core-value.md) — шесть пунктов с прицелом на людей, которые пишут и курируют библиотеки инструкций для агентов. Что MDA даёт автору в момент публикации: один источник во множество экосистем, защита от подмены и атрибуция издателя, машиночитаемый граф зависимостей и фиксация версий, авторство при участии LLM без необходимости учить frontmatter каждого runtime, меньший (но не нулевой) vendor lock-in и строгая валидация, отлавливающая почти-конформные артефакты до публикации. ## Три режима создания Артефакты MDA можно получить тремя способами. С точки зрения валидации они равнозначны. 1. **Режим агента** — ИИ-агент пишет `.md` напрямую. Основной сценарий ближайшего будущего. 2. **Ручной режим** — человек пишет `.md` напрямую, добавляет integrity и подписывает через путь подписи с поддержкой DSSE/Rekor. 3. **Режим компиляции** — автор пишет источник `.mda`; компилятор MDA выпускает один или несколько `.md`-файлов. Какой бы путь вы ни выбрали, артефакт оценивается одной и той же целевой схемой JSON Schema 2020-12 и одним и тем же набором conformance-тестов. Никакой второй кодовой ветки «это пришло от агента» нет. См. [`docs/create-sign-verify-mda.md`](../../docs/create-sign-verify-mda.md) — про ручные пути и пути, написанные агентом, без эталонного CLI, и [`spec/v1.0/00-overview.md §0.5–§0.6`](../../spec/v1.0/00-overview.md) — нормативное изложение приоритетов и режимов. ## Минимальный пример `pdf-tools.mda`: ```yaml --- name: pdf-tools description: Extract PDF text, fill forms, merge files. Use when handling PDFs. metadata: mda: doc-id: 38f5a922-81b2-4f1a-8d8c-3a5be4ea7511 title: PDF Tools version: "1.2.0" tags: [pdf, extraction] --- # PDF Tools … ``` Компилируется в `pdf-tools/SKILL.md`. Источник уже находится в строгой целевой форме, со всеми расширенными MDA-полями, вложенными в `metadata.mda.*`, поэтому компиляция, по сути, сводится к переименованию. Больше разобранных примеров — в [`examples/`](../../examples/) и [`docs/mda-examples/`](../../docs/mda-examples/). ## Совместимость Скомпилированный `SKILL.md` загружается основными потребителями agentskills.io v1: - **Claude Code** — https://code.claude.com/docs/en/skills - **OpenCode** — https://opencode.ai/docs/skills/ - **OpenAI Codex** — https://developers.openai.com/codex/skills - **Hermes Agent** — https://hermes-agent.nousresearch.com/docs/user-guide/features/skills - **OpenClaw** — https://docs.openclaw.ai/tools/skills - **skills.sh / Skills Directory** — https://www.skillsdirectory.com/ - **Cursor**, **Windsurf** и прочие потребители SKILL.md образца 2026 года Скомпилированный `AGENTS.md` ложится в экосистему, выровненную по AAIF (Agentic AI Foundation при Linux Foundation): Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, Devin, Gemini CLI, VS Code, Jules, Factory. Расширения отдельных вендоров живут в зарезервированных пространствах имён `metadata..*`. Загрузчики читают только своё пространство имён, и потребители не должны отвергать документ только из-за того, что в нём есть незарегистрированное пространство. См. [`REGISTRY.md`](../../REGISTRY.md) — реестр пространств имён, стандартные ключи `requires`, зарезервированные OIDC-эмитенты Sigstore и зарезервированные значения DSSE `payload-type`. ## Open Spec Нормативная MDA Open Spec расположена в [**SPEC.md**](../../SPEC.md) → [`spec/v1.0/`](../../spec/v1.0/). - [§00 Обзор](../../spec/v1.0/00-overview.md) — термины, RFC 2119, приоритеты P0 > P1 > P2, три режима создания, управление, версионирование - [§01 Источник и вывод](../../spec/v1.0/01-source-and-output.md) - [§02 Frontmatter](../../spec/v1.0/02-frontmatter.md) - [§03 Связи](../../spec/v1.0/03-relationships.md) — сноски + `depends-on` + закрепление по версии и дайджесту - [§04 Пространства имён платформ](../../spec/v1.0/04-platform-namespaces.md) - [§05 Прогрессивное раскрытие](../../spec/v1.0/05-progressive-disclosure.md) - [§06 Целевые схемы](../../spec/v1.0/06-targets/) — `SKILL.md`, `AGENTS.md`, `MCP-SERVER.md`, `CLAUDE.md` - [§07 Conformance](../../spec/v1.0/07-conformance.md) - [§08 Целостность](../../spec/v1.0/08-integrity.md) - [§09 Подписи](../../spec/v1.0/09-signatures.md) — Sigstore OIDC по умолчанию, did:web как запасной вариант - [§10 Возможности](../../spec/v1.0/10-capabilities.md) — `metadata.mda.requires` - [§11 Руководство для разработчиков реализаций](../../spec/v1.0/11-implementer-guide.md) (информативно) - [§12 Интеграция инструментария Sigstore](../../spec/v1.0/12-sigstore-tooling.md) (информативно) - [§13 Trusted Runtime Profile](../../spec/v1.0/13-trusted-runtime.md) — production-проверка и trust policy JSON-схемы лежат в [`schemas/`](../../schemas/) — `frontmatter-source`, `frontmatter-skill-md`, `frontmatter-agents-md`, `frontmatter-mcp-server-md`, `relationship-footnote`, `mda-trust-policy`, плюс общий `_defs/` для `integrity`, `signature`, `requires`, `depends-on` и `version-range`. Conformance-фикстуры и валидационный раннер лежат в [`conformance/`](../../conformance/) (`node scripts/validate-conformance.mjs`). ## Эталонная реализация CLI на TypeScript находится в [`apps/cli/`](../../apps/cli/) (npm-пакет: `@markdown-ai/cli`). Архитектурная спецификация — [`apps/cli/IMPL-SPEC.md`](../../apps/cli/IMPL-SPEC.md). CLI зреет через теги `v1.0.0-rc.N`. Финальный `1.0.0` выйдет, когда CLI пройдёт 100% conformance-набора. ![v1.0 публикует контракт — схемы, conformance и компилятор — оставляя верификатор, резолвер, реестр, графовый индексатор и runtime-маршрутизацию как будущую работу экосистемы](../../images/status-contract-and-ecosystem.png) ## Положение дел, честно v1.0 публикует **контракт**, а не всю экосистему вокруг него. **Что работает уже сейчас:** вы можете написать `.mda`, скомпилировать его в один или несколько конформных `.md` и провалидировать их относительно целевых JSON-схем и conformance-набора. **Что ещё в разработке:** - Встроенный верификатор подписей пока не поставляется. Операторы пока комбинируют JCS-библиотеку с Sigstore-инструментами подписи и проверки, поддерживающими DSSE/Rekor. - Рабочего резолвера зависимостей и центрального реестра артефактов пока нет. - Графовый индексатор, потребляющий `metadata.mda.relationships`, не выпущен. - Ни про один мульти-агентный harness 2026 года не известно, что он сегодня маршрутизирует через `metadata.mda.requires`. - v1.0 покрывает подмножество agentskills.io и AAIF. Он не нацелен на Cursor MDC, Windsurf rules, Continue, Aider или `*.instructions.md`. Им по-прежнему нужна параллельная поддержка. `.mda`, который вы пишете сегодня, всё равно даёт конформные `.md`, загружающиеся во всех перечисленных выше runtime-окружениях. Куски с верификацией, разрешением зависимостей и обходом графа — work in progress. Контракт, позволяющий построить их без дальнейших согласований, — это то, что v1.0 фиксирует. Полное расхождение между спецификацией и потребительской частью экосистемы расписано в [`docs/v1.0/what-v1.0-does-not-ship.md`](../../docs/v1.0/what-v1.0-does-not-ship.md). Различение между честной заморозкой спецификации и маркетинговой заморозкой — это то, что проект пытается удержать. ## Участие в проекте Контрибьюции приветствуются. Серьёзные изменения в Open Spec или в реестре вендоров стоит начинать с обсуждения, а не с кода. См. [`CONTRIBUTING.md`](../../CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](../../CODE_OF_CONDUCT.md) и [`SECURITY.md`](../../SECURITY.md). Назначение пространств имён вендоров — в [`REGISTRY.md`](../../REGISTRY.md). Свежие изменения зафиксированы в [`CHANGELOG.md`](../../CHANGELOG.md). ## Лицензия - Содержимое Open Spec (`spec/`, `REGISTRY.md`, `SPEC.md`): [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/) - Схемы (`schemas/`), инструментарий и эталонные реализации: [Apache-2.0](../../LICENSE) ## Связанные ссылки - Сайт документации: https://mda.sno.dev - Обсуждение спецификации: https://github.com/sno-ai/mda/discussions - Руководство по репозиторию для LLM: [`llms.txt`](../../llms.txt)