readability-report

warmeaf's avatarfrom warmeaf

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.

⭐18stars🔀8forks📁View on GitHub🕐Updated Dec 15, 2025

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.
namereadability-report
description生成可读性报告。当用户请求为项目源代码生成可读性报告时,使用此功能。输出名为 readability-report.html 的单页 HTML 文件作为可读性报告,该报告集成了 Node.js 脚本和 HTML 模板。
licenseComplete terms in LICENSE.txt

报告生成步骤

  1. 确定路径和输出目录

    • 确定源码文件夹路径(通常为 src/)
    • 确定报告输出文件夹:默认为项目根目录下的 .cqm/readability/
    • 如果输出文件夹不存在,则创建该目录
  2. 初始化文件结构数据

    • 执行脚本:node .claude/skills/readability-report/script/generate-file-structure.js <源码文件夹路径> .cqm/readability/readability.json
    • 脚本会在输出文件夹(.cqm/readability/)下生成 readability.json 文件
    • 该 JSON 文件包含源码目录结构,每个代码文件的 readability 字段初始值为 0
  3. 评估代码可读性

    • 读取 .claude/skills/readability-report/code-readability.md 作为可读性评估标准
    • 读取 .cqm/readability/readability.json 获取所有代码文件列表
    • 对于 JSON 中的每个代码文件:
      • 读取文件内容
      • 根据 code-readability.md 的标准,运用 AI 能力评估其可读性
      • 将评估结果(0-100 的分数)更新到该文件对应的 readability 字段
    • 将更新后的数据写回 readability.json
  4. 生成 HTML 报告

    • 读取模板文件:.claude/skills/readability-report/template/readability-report-template.html
    • 读取最终的 readability.json 数据
    • 在模板文件中找到 rawData 变量(通常在 JavaScript 代码中)
    • 将 readability.json 的内容赋值给 rawData 变量
    • 将更新后的模板内容保存为 .cqm/readability/readability-report.html
  5. 完成

    • 最终报告文件位于:.cqm/readability/readability-report.html