用途：在生成 SDK 之前检查 OpenAPI 规范是否有效，识别会阻断 SDK 生成的错误，以及可能引发问题的警告和最佳实践提示。触发场景包括“validate spec”“lint spec”“check OpenAPI”“spec errors”“is my spec valid”等。
主要能力：调用 speakeasy lint 对规范进行校验，输出分为三类。Error 表示阻断 SDK 生成的问题，必须修复；Warning 表示可能引发问题，建议修复；Hint 为最佳实践建议，可考虑修复。常见问题包括缺少 operationId、无效的 $ref、缺少响应 schema、重复的 operationId 等，资料也给出了对应处理方向，例如补充 operationId 或使用 speakeasy suggest operation-ids、修正引用路径、补充响应 schema 定义、使 operation ID 唯一。
使用方式：输入为 OpenAPI 规范文件路径，通过 -s 指定。命令为：speakeasy lint openapi --non-interactive -s <path-to-spec>。当输出较大时，可管道给 grep 或 tail 减少上下文，例如：speakeasy lint openapi --non-interactive -s ./openapi.yaml 2>&1 | grep -E "(error|warning)"。
适用场景：生成 SDK 前的规范校验、定位阻断生成的错误、排查规范质量问题。
限制与注意事项：不要在不理解根因的情况下逐个修复错误；不要忽略警告，它们往往指向真实问题；如果规范由外部管理，未经询问不要修改源规范。排错方面，出现“file not found”应检查路径是否存在；出现大量重复错误通常源于共享 schema 问题，应修复根 schema 而非每个引用；“$ref not found”应检查引用路径与实际位置是否匹配。相关技能包括 diagnose-generation-failure、fix-validation-errors-with-overlays、get-ai-suggestions。