用 MDA 写一份技能源码，编译成所有主流 Agent 运行时格式

你只维护一份技能，但每个运行时都要自己的包装格式：agentskills.io 系运行时要 SKILL.md，AAIF 生态要 AGENTS.md，MCP 要 MCP-SERVER.md 加 JSON 边车，Claude 要 CLAUDE.md。改了一个忘了其他几个，一个月后这些文件就悄悄漂移成了四份略有出入的说明书。sno-ai 出品的 MDA 是一个 616 星的开放规范，把单个 .mda 源文件编译成以上全部格式。

为什么这个 Skill 重要

MDA 是面向 agent 文档的 Markdown 超集。一个 .mda 源文件编译成各大 agent 运行时本来就加载的那些 .md 文件：SKILL.md、AGENTS.md、MCP-SERVER.md（外加 mcp-server.json 边车）和 CLAUDE.md。仓库的 compat/ 目录为五个 SKILL.md 运行时提供了可复现的安装套件并做了端到端验证：Claude Code、Codex CLI、OpenCode、Hermes Agent 和 OpenClaw。编译出的 AGENTS.md 产物也能直接用于 AAIF 生态（Codex、Copilot、Cursor、Windsurf、Amp、Devin、Gemini CLI、VS Code、Jules、Factory）。

去重只是一半卖点。标准 frontmatter 没有地方放内容摘要或签名，信任决策只能退回到「反正我们信这个仓库」的直觉。MDA 把 JCS 规范化的 integrity 摘要和 DSSE 封装、Sigstore 锚定的 signatures[] 直接放进 frontmatter，加载文档的 agent 和审查文档的人都能对手里的产物做真正的校验。

在标准 Markdown 之上，.mda 增加了三个可选能力：更丰富的 YAML frontmatter（doc-id、version、requires、depends-on、relationships、tags）、带类型的脚注关系（parent、child、related、cites、supports、contradicts、extends），以及上面说的密码学身份。只带开放标准 frontmatter 的源文件会原样编译成 .md——需要多少用多少。

安装

参考 CLI 以 npm 包 @markdown-ai/cli 发布，安装后的二进制名是 mda。全局安装，或者免安装直接运行：

npm install -g @markdown-ai/cli
# 或者免安装运行：
npx @markdown-ai/cli --help

当前版本是候选版 v1.0.0-rc.3。

实战：把一份技能同时发布给 Claude Code 和 Codex

1. 一条命令看懂整条流水线。npx -y @markdown-ai/cli demo 会写出 mda-demo/hello.mda，以及 SKILL.md、AGENTS.md、MCP-SERVER.md 和 mcp-server.json 产物，每个都带 sha256 完整性摘要。
2. 编写源文件。mda init code-review --out code-review.mda 生成脚手架；然后编辑 name、description、metadata 和正文。
3. 编译前先校验源文件：

mda validate code-review.mda

4. 带完整性摘要编译，只面向你要发布的运行时：

mda compile code-review.mda --target SKILL.md AGENTS.md --out-dir out --integrity

5. 校验和核验的是编译产物，而不只是源文件：

mda validate out/SKILL.md --target SKILL.md
mda validate out/AGENTS.md --target AGENTS.md
mda integrity verify out/SKILL.md --target SKILL.md

同一套流程有 agent 模式：给命令加上 --json——CLI 手册建议几乎每条命令都加——就能得到稳定的 ok、artifacts、diagnostics 和 nextActions 字段，方便接脚本和 CI 门禁。

技巧

• 从开放标准 frontmatter 起步。MDA 新增的能力全部可选；只写 name 和 description 的 .mda 会编译成一个普通且合法的 .md。
• 三种创作方式——agent 直写、人直写、编译——用同一套 JSON Schema 2020-12 目标 schema 和同一套一致性测试评判。agent 产出的内容没有第二条代码路径。
• 别把 CLI 塞进运行时。README 把 @markdown-ai/cli 定位为创作、CI 和 agent 侧的检查工具；运行时库应当保留自己的轻量加载器和校验钩子。
• 许可证是拆分的：规范内容 CC-BY-4.0，schema 与工具 Apache-2.0。

何时不用这个 Skill

README 自己的「Status, honestly」一节就是边界。v1.0 交付的是契约而非生态：签名校验器尚未打包发布，依赖解析器和中心化产物仓库还不存在，也还没有已知的 2026 年多 agent 框架会按 metadata.mda.requires 路由。规范也不覆盖 Cursor MDC、Windsurf rules、Continue、Aider 或 *.instructions.md——这些仍需并行维护。另外，如果你只向一个运行时发布一份技能，直接写 SKILL.md 比引入编译器更简单。

查看排行榜了解更多 skill。