MDA — один исходник для SKILL.md и AGENTS.md
MDA
CLI mda собирает из одного файла .mda готовые SKILL.md, AGENTS.md и MCP-SERVER.md и проверяет их по JSON Schema.
- 621 ★ репозитория
- Последний коммит
Расширенный доступ
Почему такой уровень
- Команда `mda compile` пишет файлы в выбранную папку, а `mda integrity compute --write` меняет заголовок исходного файла
- Запуск через npx выполняет код пакета из npm, а подписание подключается к внешним сервисам Sigstore
Установка
- Работает в
В терминале, через SkillFoxx CLI
npx skillfoxx add cli/mdaОпределит агенты на машине, покажет уровень доступа и зафиксирует версию.
Другие способы установки
Доступ и проверки
Как мы проверяемРасширенный доступИнструмент запускает код или ходит в сеть, а внешние данные только читает.
- Команда `mda compile` пишет файлы в выбранную папку, а `mda integrity compute --write` меняет заголовок исходного файла
- Запуск через npx выполняет код пакета из npm, а подписание подключается к внешним сервисам Sigstore
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
MDA — открытая спецификация расширенного Markdown для документов, которые читают агенты. Проблема в том, что один и тот же скилл приходится вести в SKILL.md, AGENTS.md, MCP-SERVER.md и CLAUDE.md, и копии со временем расходятся. В MDA вы пишете один файл `.mda`, а компилятор выдает остальные. К стандартным полям `name` и `description` MDA добавляет необязательные: идентификатор документа, версию, зависимости, теги и типизированные связи между документами в виде сносок. Для защиты от подмены служит контрольная сумма содержимого, которая записывается в заголовок, а подписанные артефакты могут нести подписи Sigstore. Все расширения лежат под ключом `metadata.mda`, поэтому обычный `.mda` с одними стандартными полями компилируется в `.md` без изменений. Эталонная реализация, пакет `@markdown-ai/cli` с командой `mda`, умеет создавать заготовку, проверять исходники и результаты, компилировать, считать и проверять контрольные суммы. Вывод в формате JSON сделан для агентов: он содержит поля `ok`, `exitCode`, `diagnostics` и `nextActions`, поэтому агенту не нужно разбирать текст. Совместимость с Claude Code, Codex CLI, OpenCode, Hermes Agent и OpenClaw подтверждена наборами установки в папке `compat`.
Для кого. Для авторов скиллов и инструкций для агентов, которые публикуют одно содержимое сразу для нескольких сред выполнения и хотят проверять его в CI.
Подходит, если
- Один скилл нужно выпустить как SKILL.md и AGENTS.md, и копии не должны расходиться со временем
- В CI нужна проверка, что SKILL.md соответствует схеме: `mda validate out/SKILL.md --target SKILL.md`
- Агент сам правит документы-инструкции, и перед сборкой его результат надо пропускать через проверку с выводом `--json`
- Нужна контрольная сумма содержимого, чтобы заметить, что файл скилла изменили после публикации
- Скиллы зависят друг от друга, и эти зависимости с версиями нужно записать в машинном виде
Не подходит, если
- Нужен единственный файл SKILL.md для одного агента: компилятор тогда не даст выигрыша
- Вам нужны правила Cursor в формате MDC, правила Windsurf или Aider: версия 1.0 охватывает только форматы agentskills.io и AAIF
- Требуется готовая проверка подписей, преобразователь зависимостей или реестр: их в версии 1.0 еще нет
- Нужна библиотека внутри приложения: авторы советуют использовать CLI для сборки, CI и проверки, а в рантайме держать собственные загрузчики
Пример запроса к агенту
Создай hello.mda, проверь его через `mda validate`, скомпилируй в SKILL.md и AGENTS.md в папку out и проверь контрольную сумму результата.Ограничения
Выпуск пока остается кандидатом: v1.0.0-rc.3, финальная 1.0.0 выйдет, когда CLI пройдет весь набор проверок на соответствие. Спецификация описывает четыре цели, но в справке CLI допустимы source, SKILL.md, AGENTS.md и MCP-SERVER.md, то есть для CLAUDE.md компиляция пока не заявлена. Контрольная сумма показывает, что содержимое изменилось, но не доказывает, кто его написал.
Встроенного проверяющего подписей Sigstore нет: придется сочетать библиотеку канонизации JCS с инструментами подписи DSSE. Нет также резолвера зависимостей, центрального реестра и индексатора графа связей. По словам авторов, ни один известный агентный комплекс пока не маршрутизирует задачи по полю `requires`.
Доступность npm и сервисов Sigstore из России при подготовке карточки не проверялась. Код под Apache-2.0, текст спецификации под CC-BY-4.0.
Как отключить. Для глобальной установки выполните `npm uninstall -g @markdown-ai/cli`, запуск через `npx` ничего не оставляет. Сгенерированные файлы лежат в папке, указанной флагом `--out-dir`, и удаляются обычным способом. Исходные `.mda` остаются вашими: без компилятора их можно оформить вручную как обычные SKILL.md.
Частые вопросы
Что такое MDA и чем .mda отличается от SKILL.md?
MDA — надстройка над Markdown с расширенным заголовком, типизированными связями в сносках и контрольной суммой. Файл `.mda` служит исходником, компилятор выдает из него SKILL.md, AGENTS.md и MCP-SERVER.md. Если в исходнике только стандартные поля `name` и `description`, результат почти не отличается от исходника.
Как скомпилировать .mda в SKILL.md и AGENTS.md?
Выполните `mda compile hello.mda --target SKILL.md AGENTS.md --out-dir out --integrity`. Затем проверьте результаты командами `mda validate out/SKILL.md --target SKILL.md` и `mda integrity verify out/SKILL.md --target SKILL.md`.
Как увидеть работу mda без настройки?
Команда `npx -y @markdown-ai/cli demo` создает папку mda-demo с файлом hello.mda и готовыми SKILL.md, AGENTS.md, MCP-SERVER.md и mcp-server.json с контрольными суммами. Существующую папку mda-demo она не перезаписывает.
Как использовать mda в агенте?
Добавляйте `--json`: ответ содержит `ok`, `command`, `exitCode`, `summary`, `artifacts`, `diagnostics` и `nextActions`. Продолжайте, пока `ok` равно true и код выхода 0, читайте `diagnostics[0].code` перед текстом и сначала пишите результаты во временную папку.
Что в MDA еще не готово?
Нет встроенного проверяющего подписей, резолвера зависимостей, реестра артефактов и индексатора графа связей. Также версия 1.0 не нацелена на Cursor MDC, правила Windsurf, Continue, Aider и файлы instructions.md.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
CLI-инструментыНабор скиллов, который задает агенту процесс разработки: уточнение задачи, план, TDD, субагенты и ревью кода
Matt Pocock skills: скиллы Мэтта Покока для инженеров
Skills For Real Engineers
Небольшие компонуемые скиллы для инженерной работы с агентом: интервью по плану, TDD, диагностика багов, ревью и архитектура
Правила для Claude Code по мотивам Карпаты
Karpathy-Inspired Claude Code Guidelines
Четыре принципа в одном CLAUDE.md против типичных ошибок LLM в коде: допущения, переусложнение, лишние правки
Плагин и скилл, который заставляет агента писать минимум кода: сначала повторное использование, stdlib и нативные возможности
Набор GitHub для разработки от спецификации: CLI specify ставит в проект команды и скиллы для агента, от принципов до реализации
Набор скиллов Гэрри Тана, превращающий Claude Code в виртуальную команду: продукт, архитектура, дизайн, ревью, QA и выпуск
Сравнение с похожими
Записи с тем же главным запросом: чем они отличаются.
| Запись | Официальный | Звезды репозитория | Главное отличие |
|---|---|---|---|
| MDA — один исходник для SKILL.md и AGENTS.md (эта запись) | нет | 621 | |
| agnix | да | 457 | линтер готовых CLAUDE.md, AGENTS.md, SKILL.md, хуков и MCP-конфигов, ничего не компилирует |
| Caliber | нет | 1 310 | создает и поддерживает файлы контекста для кодовых агентов по состоянию проекта |
Коротко о README
Основной документ объясняет, зачем нужен единый исходник для нескольких форматов, и показывает схему компиляции с совместимыми средами. Затем описаны три добавки к Markdown: расширенный заголовок, типизированные связи и криптографическая идентичность, а также три режима создания артефактов: агентом, человеком и компилятором. Приведен минимальный пример pdf-tools.mda, оглавление спецификации с разделами и перечень схем JSON. Блок о статусе перечисляет, что версия 1.0 уже дает и чего еще нет.