name: lint-md description: 使用markdownlint-cli2对文件运行Markdown语法检查验证 argument-hint: [目标文件或指令] allowed-tools: Read, Bash, Skill
Markdown 语法检查命令
使用markdownlint-cli2对所有或目标Markdown文件运行语法检查验证。
指令
使用 code-quality:markdown-linting 技能来处理完整的语法检查工作流。
markdown-linting 技能提供：
- 使用markdownlint-cli2进行验证（CLI工具或npm脚本）
- 自动修复功能，用于可修复的语法检查问题
- 配置指导，用于
.markdownlint-cli2.jsonc - 规则解释和故障排除
- VS Code集成和GitHub Actions设置（可选/高级）
只需调用该技能并遵循其指导：
使用 code-quality:markdown-linting 技能运行语法检查验证。
{如果提供参数}
针对以下文件/文件夹：{参数}
用户提供："{参数}"
这可能是：
- 特定文件路径（例如，"README.md"、"docs/setup.md"）
- 文件夹路径（例如，"docs/"、".claude/skills/"）
- 通配符模式（例如，"docs/**/*.md"、"*.md"）
- 自然语言描述（例如，"仅技能文档"、"git相关文档"）
解释目标指令并构建适当的markdownlint-cli2命令。
{结束如果}
{如果没有参数}
在项目中的所有Markdown文件上运行验证（默认行为）。
{结束如果}
遵循技能的工作流：
1. 确定适当的语法检查命令（npx或npm脚本）
2. 在目标或所有Markdown文件上执行验证
3. 报告结果（发现错误或验证通过）
4. **自动运行自动修复**，如果检测到可修复问题（不要请求确认）
5. 报告修复内容和任何剩余的不可修复问题
6. 解释发现的任何规则违规
重要：不要在没有咨询技能的情况下直接运行语法检查命令。markdown-linting 技能确保：
- 正确的命令构建（npx vs npm脚本）
- 配置合规（尊重
.markdownlint-cli2.jsonc） - 规则解释和上下文
- 自动修复指导
- 正确的错误解释和报告
让技能指导完整的工作流。
关键：无自动化脚本
⚠️ 脚本严格禁止用于Markdown语法检查修复 ⚠️
永远不要使用自动化脚本来修复Markdown文件。 这包括：
- 一次性修改多个文件的Python/Bash脚本
- 跨文件基于正则表达式的查找和替换操作
- 任何在没有逐个更改人工审查的情况下进行批量更改的自动化工具
为什么存在此政策
A) 脚本是危险的 - 我们见过真实问题：
- 上下文盲区：脚本无法理解语义上下文（例如，显示工具输出的代码块 vs 实际代码）
- 过度应用：脚本统一应用修复，即使在不适当的地方
- 级联损坏：一个错误的假设影响数百个文件，需要痛苦的手动清理
- 错误语言检测：向故意没有语言说明的块添加
text或其他语言说明符
B) 手动修复更慢但更准确和安全：
虽然逐个手动修复语法错误需要更长时间，但它确保：
- 每个更改在应用前都在上下文中被审查
- 语义意义被保留（不仅仅是语法正确性）
- 边缘情况被适当处理
- 不相关的内容没有附带损害
速度/准确性权衡是值得的。 一个“节省时间”但需要数小时清理的脚本是净损失。
嵌套代码块：一个关键的复杂性
文档通常包含Markdown中的Markdown - 展示如何编写Markdown的示例、带有代码示例的技能文档、模板等。这创建了脚本无法正确处理的结构：
示例：一个展示如何编写代码块的技能：
这里是创建Python代码块的方法：
````markdown
```python
def hello():
print("Hello, world!")
```
````
在此示例中：
- 外部围栏使用4个反引号（`````markdown`）
- 内部围栏使用3个反引号（
```python） - 看到
```的脚本可能错误地添加语言说明符或破坏嵌套
常见嵌套模式要注意：
```{language}- 带有语法高亮的常规代码块````markdown- 展示Markdown示例的包装器（使用4+个反引号）- 代码块内的代码块（关于文档的文档）
- 不应有语言说明符的示例输出
脚本无法可靠区分：
- 哪个反引号围栏是“真实”的 vs 示例
- 一个裸
```是故意的（原始输出）还是需要语言 - 每个代码块的语义目的
真实世界失败示例
一个脚本向显示MCP工具输出、Notion搜索和其他非代码示例的代码块添加了text语言说明符。这些块故意是裸的（没有语言）以显示原始输出。脚本的“修复”需要数百个手动编辑来撤销。
唯一可接受的方法
- 运行
markdownlint-cli2 --fix进行安全、内置的自动修复（尾部空格、空行） - 对于“不可修复”错误，使用编辑工具逐个进行有针对性的、上下文相关的修复
- 在应用前审查每个更改 - 理解错误存在的原因
- 查看周围上下文 - 这是嵌套代码块吗？一个示例？原始输出？
- 如果修复看起来是机械/重复的，停止并询问用户再继续
如果你甚至考虑使用脚本
- 立即停止
- 明确询问用户：“我正在考虑使用脚本自动化此操作。你确定吗？脚本过去导致了痛苦的清理。”
- 仅在用户明确确认后才继续，并且你已经三重检查了脚本逻辑
- 先在单个文件上测试，并在批量应用前向用户展示差异
示例
示例1：检查所有文件
用户：/code-quality:lint-md
Claude：[调用 code-quality:markdown-linting 技能]
在所有Markdown文件上运行语法检查...
$ npm run lint:md
# 或
$ npx markdownlint-cli2 "**/*.md"
所有Markdown文件通过语法检查验证
示例2：检查特定文件夹
用户：/code-quality:lint-md docs/
Claude：[调用带有目标的 code-quality:markdown-linting 技能]
在 docs/ 文件夹上运行语法检查...
$ npx markdownlint-cli2 "docs/**/*.md"
在 docs/setup.md 中发现3个语法错误：
- 行45：MD022/标题周围空白
- 行78：MD009/无尾部空格
- 行102：MD022/标题周围空白
自动修复中...
$ npx markdownlint-cli2 "docs/**/*.md" --fix
所有问题已修复
示例3：检查特定文件
用户：/code-quality:lint-md README.md CLAUDE.md
Claude：[调用带有目标的 code-quality:markdown-linting 技能]
在指定文件上运行语法检查...
$ npx markdownlint-cli2 README.md CLAUDE.md
README.md：未发现问题
CLAUDE.md：发现2个问题（可自动修复）
- 行23：MD009/无尾部空格
- 行67：MD012/无多个空白
自动修复中...
$ npx markdownlint-cli2 README.md CLAUDE.md --fix
所有问题已修复
示例4：自然语言目标
用户：/code-quality:lint-md 仅技能文档
Claude：[调用带有解释的 code-quality:markdown-linting 技能]
解释目标："仅技能文档"
目标：.claude/skills/**/*.md
$ npx markdownlint-cli2 ".claude/skills/**/*.md"
检查9个技能文件...
所有技能文档通过语法检查验证
示例5：通配符模式
用户：/code-quality:lint-md .claude/**/*.md
Claude：[调用带有模式的 code-quality:markdown-linting 技能]
在 .claude/**/*.md 模式上运行语法检查...
$ npx markdownlint-cli2 ".claude/**/*.md"
在2个文件中发现问题：
- .claude/memory/workflows.md：1个问题（MD022）
- .claude/skills/lint-md/SKILL.md：3个问题（MD009, MD012, MD022）
总计：4个可修复问题
自动修复中...
$ npx markdownlint-cli2 ".claude/**/*.md" --fix
所有问题已修复
命令设计说明
此命令设计为与 code-quality:markdown-linting 技能协同工作，该技能提供实际的语法检查逻辑、规则解释和故障排除指导。此命令专注于：
- 参数解释：解析用户提供的目标指令
- 委托：调用带有上下文的markdown-linting技能
- 简单性：最小化编排，最大化技能利用
markdown-linting 技能处理：
- 语法检查执行：使用正确参数运行markdownlint-cli2
- 结果解释：解释错误和违规
- 自动修复指导：提供和执行修复
- 配置：尊重
.markdownlint-cli2.jsonc设置 - 故障排除：帮助解决语法检查问题
这种关注点分离使命令和技能都保持专注和可维护。