用途:撰写或评审随代码库发布的说明性文字,包括 README、开发者指南、教程、运行手册、迁移与弃用说明、CLI 标志与帮助文本、代码注释与文档字符串、AGENTS.md/CLAUDE.md 操作指南、提交信息与 PR 描述及变更日志。
主要能力:按文档类型选择对应约定文件(READMES.md、GUIDES.md、CLI.md、COMMENTS.md、AGENTSMD.md、PR.md),一次只加载一个以免混用约定;先阅读实现、schema、测试、--help 或 diff 以确认事实;明确目标读者与文档要促成的动作;为重复概念固定一个术语,保留准确的 API 名称与标识符;按所选文档类型起草,再核对每条断言、命令、注意事项与边界是否与来源一致。提供 strict 与 natural 两种清晰度模式,可按内容块分别应用。
使用方式:先选定文档类型并读取对应约定文件,再按工作流起草与核对,最后运行检查器:python3 scripts/prose_lint.py --mode strict <path> 或 --mode natural <path>;支持 - 表示标准输入,--json 输出结构化结果,退出码 1 表示 strict 错误,仅评审类发现返回 0,可用 <!-- prose-lint-ignore --> 忽略单行。重写既有文档前,应在测试与 CI 中检索被文档固定的字符串,把断言改为验证需求(顺序、链接存在)而非精确文字,并在 PR 中说明改动;同时查找由其派生的副本(包 README、文档站、翻译)并更新或标明不在范围内。评审时采用同一视角反向检查,指出目标读者无法执行、无法信任或需要重读之处,先报缺陷与位置。
适用场景:面向维护者、使用者或智能体的代码库文档。
限制:检查器无法在无项目上下文时识别同义词轮换,需人工核对术语;它不是 STE 认证,也不能替代事实审查;博客文章与随笔、设计文档与 ADR、内部服务 wiki、技能编写均不属于本技能范围。资料未提供安装方式与其他平台细节。