Better-md-skill：让 AI 写出工程师级 Markdown 文档的 Skill

Better-md-skill：让 AI 写出工程师级 Markdown 文档的 Skill

Better-md-skill 是一个专注于 Markdown 文档工程质量的 AI Agent Skill，能够对 README、API 文档、教程、规格说明和变更日志进行创建、改善、重构、审计与验证。它不是美化工具，而是一套有态度的质量标准——内置 CommonMark + GFM 规范检查、markdownlint 风格规则、GitHub 文档规范、阅读心理学原则，以及一个 51 条用例的防伪造测试套件，确保 AI 在处理文档时不会编造链接、图片路径或徽章。

功能与原则

Better-md-skill 的核心能力覆盖文档全生命周期：

• Structured Workflows：为每种文档类型（README、API 文档、changelog 等）设计专用处理流程，采用增量 diff 方式编辑，确保每次改动都有迹可循
• Validation Gate：执行严格的验证门控，自动检查链接有效性、资源完整性，在文档离开 AI 之前拦截失效内容
• Anti-fabrication 原则：明确拒绝生成不存在的 URL、徽章、图片路径或图标——这是 Skill 内置的”诚信红线”
• Evidence-based Readability：引入目标导向标题、分块段落、克制强调等阅读心理学规则，让文档真正易读而非表面好看
• Visual Asset Suggestions：以不可见注释形式精确标注”此处应放截图/图表”，而不是让 AI 胡乱猜测图片路径

设计原则很清晰：做标准层，不做内容层。好文档原样保留，只动结构不动内容；AI 的职责是工程化质量把关，不是自由发挥写文档。

认可度

• GitHub Stars：截至 2026-08-18 为 8 星，2026-08-15 刚创建，仍处萌芽期
• GitHub Forks：0
• 平台支持：遵循 Agent Skills 开放标准（agentskills.io），兼容 Claude Code、OpenCode、Codex、Gemini CLI、Cursor、GitHub Copilot 等 30+ Agent
• 定位稀缺性：目前市面上缺少专门针对 AI 生成 Markdown 文档进行质量工程化管控的 Skill，填补了这一空白

链接

GitHub：https://github.com/FrekiJoms/better-md-skill

原作者

FrekiJoms（GitHub @FrekiJoms），目前公开仓库仅 better-md-skill 一个项目，走的是小而精路线。

介绍

大模型在写代码方面已经相当成熟，但在处理 Markdown 文档时却常常”放飞自我”——编造不存在的链接、乱放徽章和截图路径、写出违反 CommonMark 规范的语法。这类错误在 AI 生成内容中极为普遍，因为大多数 Skill 和 Agent 根本没有针对文档质量的校验机制。

Better-md-skill 正是为解决这一问题而生。它构建了一套完整的文档工程框架，从语义结构、可读性层级、链接完整性到视觉规范，全部纳入 Skill 的行为约束之中。简单来说，它教会 AI：”什么样的 Markdown 文档算工程师级别的标准输出，你应该怎么改、哪些不能编造。”

Skill 内部包含 16 个规则分类，覆盖从核心原则到发布分发的完整文档工程链路。文档类型覆盖 README、API 文档、教程、规格说明和 changelog 五类，每类都有对应的结构化处理流程。

特点

• CommonMark + GFM 双标准支持：严格遵循标准 Markdown 规范生成和验证内容，输出可直接在 GitHub 渲染
• 51 条测试用例覆盖：每个功能点均有对应测试 fixture，保证 Skill 行为可预测、可回归
• Validation Gate 机制：文档修改后自动触发验证门控，未通过的改动不允许输出，杜绝失效链接流出
• 零伪造承诺：Skill 明确拒绝生成不存在的 URL、徽章、图片路径——遇到不确定内容会主动报疑，而非猜测填充
• 多 Agent 兼容：通过 npm 全局安装后自动部署到所有主流 Agent 的个人技能目录，真正实现”一次安装，处处生效”

使用方法

安装（推荐全局 npm 方式）：

npm install -g https://github.com/FrekiJoms/better-md-skill/archive/refs/heads/main.tar.gz

postinstall 钩子会自动将 Skill 部署到各 Agent 的个人技能目录（OpenCode → ~/.config/opencode/skills/、Claude Code → ~/.claude/skills/ 等）。

手动安装示例：

# 从本地检出版本通过 skills CLI 安装
npx skills add ./better-md-skill --skill better-md-skill -g --copy -y

# 从 GitHub 直接安装
npx skills add FrekiJoms/better-md-skill --skill better-md-skill -g --copy -y

使用（安装后重启 Agent 会话）：

Improve this README using Better-md-skill.

无改动审计模式：

Audit this Markdown without changing it.

Skill 会报告：修改了什么、为什么改、以及哪些项目无法验证。

使用场景与人群

适用场景：
– AI 生成项目 README 后进行质量验收
– 团队要求 AI 输出文档符合公司文档规范
– 对 AI 生成的 changelog / API 文档进行真实性校验
– 批量处理多个文档，统一质量标准

目标用户：
– 使用 Claude Code / OpenCode / Codex 等工具编程的开发者
– 需要 AI 输出高质量技术文档的团队
– 对文档质量有工程化要求的技术负责人

输入与输出案例

案例 1：改善 README

Input：

“Improve this README using Better-md-skill.”（附带一个结构混乱、链接失效、徽章指向不存在的 README）

Output：

Skill 自动检测到：3 处失效链接、2 个不存在徽章、标题层级不符合目标导向原则。对每处改动说明原因，输出 diff 风格的增量修改建议，拒绝伪造任何新链接或图片路径。最终生成符合 GitHub 文档规范的 README。

案例 2：防伪造审计

Input：

“Audit this Markdown without changing it.”（附一份 AI 刚生成的 API 文档）

Output：

Skill 报告：
– ✅ 链接 https://api.example.com/v2/users 结构有效
– ❌ 徽章 build-passing 指向不存在的 shields.io 端点
– ❌ “screenshot.png” 文件路径未出现在仓库中，无法验证
– ⚠️ README 缺少目标导向的 H1 标题

无任何伪造内容，审计结果诚实透明。

GitHub: https://github.com/FrekiJoms/better-md-skill