markdown-linter

Markdown Linter 是一款专注于 Markdown 文件质量检查与格式修复的文档型工具技能。该技能核心功能围绕两大模式展开：首选方案是利用成熟的 markdownlint-cli 工具进行自动化检查与修复，支持单文件或批量目录扫描；备选方案则通过内置的文本分析逻辑，手动检测标题层级跳跃、列表符号不一致、尾部空格、缺失空行、超长行、损坏的相对链接等常见问题，并提供具体的修复建议。

该技能的显著优点在于其纯文档型资产属性，意味着不存在任何代码执行风险，所有功能逻辑透明可查。它无需 API 密钥即可工作，支持自动生成目录（TOC），并提供了详尽的边界情况处理指南（如 MDX 文件、自动生成文档的特殊处理）。此外，技能推荐的配置方案（.markdownlint.json）允许用户根据项目需求灵活调整规则，例如设置行长度限制或允许 HTML 标签。

然而，该技能也存在一定局限性。首先，其来源为 T3 级个人账号，虽经安全审计内容无害，但长期维护与更新稳定性不如 T1/T2 级官方来源。其次，对于包含 JSX 语法的 MDX 文件，标准 Markdown 检查规则可能产生误报，需要手动关闭特定规则（如 MD033）。此外，链接验证功能主要依赖文本模式匹配，对于复杂的动态链接或外部 URL 的有效性检查能力有限。

该技能特别适合软件开发团队、技术文档撰写者、开源项目维护者以及任何需要维护大量 Markdown 文档的场景。它能够有效统一文档风格，预防死链，提升 README、开发文档、API 文档的专业度与可读性。

使用时的常规风险主要包括：处理超大文件时的性能消耗、可选依赖 markdownlint-cli 的版本兼容性问题（建议锁定版本号），以及相对链接验证可能因路径解析差异导致的假阳性或假阴性结果。建议在使用前审查推荐配置，并在持续集成（CI）流程中结合其他工具进行交叉验证。

Markdown Linter 综合评估

核心用法

Markdown Linter 是一款专注于 Markdown 文档质量检测的 Skill，提供双重工作模式：

1. CLI 模式（推荐）：调用 markdownlint-cli 进行标准化检测，支持单文件、多文件批量扫描及 --fix 自动修复
2. 纯文本分析模式：无需外部依赖，通过正则匹配识别常见格式问题，包括标题层级跳跃、列表符号混用、行尾空格、缺失空行、超长行、失效相对链接、重复标题、图片缺失替代文本等

附加功能涵盖链接有效性验证（grep 提取 + 文件存在性检查）和目录自动生成（TOC），输出格式化的 Markdown 检测报告。

显著优点

• 零依赖可用：纯文本分析模式确保在无 Node.js 环境下仍可工作
• 检测维度全面：覆盖结构（标题层级）、样式（空白字符）、可访问性（alt 文本）、可维护性（链接完整性）四大层面
• 工程化友好：提供 .markdownlint.json 配置示例，支持项目级规范定制
• 边缘场景覆盖：明确标注 MDX、生成文件、YAML frontmatter、表格等特殊场景的处理方案

潜在局限

• CLI 为可选依赖：完整功能需用户自行安装 markdownlint-cli，未提供自动安装引导
• 链接验证局限：仅支持相对链接的文件存在性检查，无法验证外部 URL 可达性
• 无实时集成：缺少与 Git hooks、CI/CD pipeline 的集成示例
• 配置文档分散：规则说明（如 MD013/MD033）需用户查阅 markdownlint 官方文档理解含义

适合人群

• 技术文档工程师、开源项目维护者需批量规范 Markdown 格式
• 写作团队建立统一的 Markdown 编码标准
• 静态站点（如 Docusaurus、VitePress、MkDocs）内容预处理

常规风险

| 风险类型 | 评估 | 说明 |

|---------|------|------|

| 执行安全 | ✅ 极低 | 无可执行代码，仅文档与命令示例 |

| 网络暴露 | ✅ 无 | 无外部 API 调用 |

| 隐私泄露 | ✅ 无 | 不处理用户敏感数据 |

| 依赖风险 | ⚠️ 低 | CLI 工具为用户自主安装的知名开源项目 |

---

总结：该 Skill 为纯文档型工具，安全等级 S，适合作为 Markdown 文档质量门禁或写作辅助。