readability-report
Generate a readability report. Utilize this capability when users request generating a readability report for project source code. Output a single-page HTML file named readability-report.html as the readability report, which integrates Node.js scripts and HTML templates.
When & Why to Use This Skill
This Claude skill automates the assessment of source code quality by generating a comprehensive, single-page HTML readability report. By leveraging AI to evaluate code against defined standards and utilizing Node.js for structural analysis, it provides developers with a visual and data-driven overview of project maintainability and clarity.
Use Cases
- Technical Debt Identification: Scan legacy codebases to pinpoint complex or poorly structured files that require refactoring to improve long-term maintainability.
- Pre-merge Quality Checks: Integrate readability scoring into the development workflow to ensure new code contributions meet team standards before being merged.
- Developer Onboarding: Provide new team members with a visual map of the project's code health, helping them understand which areas follow best practices and which are more complex.
- Project Handover Documentation: Generate a professional HTML report as part of project delivery to demonstrate code quality and provide an objective health metric to stakeholders.
| name | readability-report |
|---|---|
| description | 生成可读性报告。当用户请求为项目源代码生成可读性报告时,使用此功能。输出名为 readability-report.html 的单页 HTML 文件作为可读性报告,该报告集成了 Node.js 脚本和 HTML 模板。 |
| license | Complete terms in LICENSE.txt |
报告生成步骤
确定路径和输出目录
- 确定源码文件夹路径(通常为
src/) - 确定报告输出文件夹:默认为项目根目录下的
.cqm/readability/ - 如果输出文件夹不存在,则创建该目录
- 确定源码文件夹路径(通常为
初始化文件结构数据
- 执行脚本:
node .claude/skills/readability-report/script/generate-file-structure.js <源码文件夹路径> .cqm/readability/readability.json - 脚本会在输出文件夹(
.cqm/readability/)下生成readability.json文件 - 该 JSON 文件包含源码目录结构,每个代码文件的
readability字段初始值为0
- 执行脚本:
评估代码可读性
- 读取
.claude/skills/readability-report/code-readability.md作为可读性评估标准 - 读取
.cqm/readability/readability.json获取所有代码文件列表 - 对于 JSON 中的每个代码文件:
- 读取文件内容
- 根据
code-readability.md的标准,运用 AI 能力评估其可读性 - 将评估结果(0-100 的分数)更新到该文件对应的
readability字段
- 将更新后的数据写回
readability.json
- 读取
生成 HTML 报告
- 读取模板文件:
.claude/skills/readability-report/template/readability-report-template.html - 读取最终的
readability.json数据 - 在模板文件中找到
rawData变量(通常在 JavaScript 代码中) - 将
readability.json的内容赋值给rawData变量 - 将更新后的模板内容保存为
.cqm/readability/readability-report.html
- 读取模板文件:
完成
- 最终报告文件位于:
.cqm/readability/readability-report.html
- 最终报告文件位于: