docs-improver
v1.0.0专业技术文档提升工具。评估文档质量（完整性、准确性、清晰度、结构化、可维护性），自动生成缺失文档（README、API 文档），检查文档与代码一致性，提供可执行的改进建议。使用场景：文档质量审计、缺失文档生成、文档一致性检查、文档改进规划、新项目文档搭建、发布前检查。支持所有编程语言。
Sourced from ClawHub,
Authored by jerry-guo-mys
Installation
Please help me install the skill `docs-improver` from SkillHub official store.
npx skills add jerry-guo-mys/docs-improver
Docs Improver - 技术文档专家
专业的技术文档分析、生成和改进工具。
快速开始
# 完整流程：分析 + 生成 + 检查 + 改进
python3 scripts/docs-improver.py --path /path/to/project --mode all --report report.md
# 仅质量评估
python3 scripts/analyze.py --path /path/to/project --output quality.md
# 仅文档生成
python3 scripts/generate.py --path /path/to/project --type readme
# 仅一致性检查
python3 scripts/consistency-check.py --path /path/to/project --output issues.md
# 仅改进建议
python3 scripts/improve.py --path /path/to/project --output plan.md
核心功能
📊 文档质量评估
| 维度 | 说明 |
|---|---|
| 完整性 | 覆盖关键内容（30% 权重） |
| 清晰度 | 易读易懂（25% 权重） |
| 结构化 | 组织清晰（20% 权重） |
| 可维护性 | 易于更新（15% 权重） |
| 准确性 | 与代码一致（10% 权重） |
📝 文档生成
| 文档类型 | 说明 |
|---|---|
| README.md | 项目概述和快速开始 |
| API.md | API 接口文档 |
| ARCHITECTURE.md | 架构设计文档 |
| INSTALL.md | 安装部署指南 |
| CONTRIBUTING.md | 贡献指南 |
| CHANGELOG.md | 变更日志 |
🔍 一致性检查
- API 文档 vs 实际接口
- 示例代码 vs 实际代码
- 架构图 vs 实际架构
- 配置说明 vs 实际配置
- 链接有效性检查
💡 改进建议
| 优先级 | 时间 | 说明 |
|---|---|---|
| 快速获胜 | 几小时 | 立即可改的小问题 |
| 短期 | 几天 | 需要一定工作量 |
| 长期 | 几周 | 系统性改进 |
输出示例
质量评估报告
# 文档质量评估报告
## 总体评分：88/100 ✅
| 维度 | 评分 | 状态 |
|------|------|------|
| 完整性 | 80/100 | ✅ 良好 |
| 清晰度 | 100/100 | ✅ 优秀 |
| 结构化 | 85/100 | ✅ 良好 |
| 可维护性 | 100/100 | ✅ 优秀 |
## 改进建议
### 快速获胜（几小时）
- [ ] 添加项目描述和徽章
- [ ] 添加代码示例
### 短期（几天）
- [ ] 创建 API 文档
- [ ] 添加架构图
### 长期（几周）
- [ ] 建立自动化文档生成
- [ ] 建立文档审查流程
一致性问题
# 一致性检查报告
## 发现问题：5 个
### 严重 (1)
1. API 端点 /api/users 存在于代码但未文档化
### 主要 (2)
1. README 中的示例代码使用了过时的 API
2. 架构图缺少新增的微服务
### 次要 (2)
1. 3 个外部链接失效
2. 术语不统一（用户/客户混用）
使用场景
1. 文档质量审计
python3 scripts/analyze.py --path . --output audit.md
适用： - 接手新项目 - 准备发布 - 季度文档审查
2. 生成缺失文档
python3 scripts/generate.py --path . --output ./docs
适用： - 新项目启动 - 准备开源 - 新成员入职
3. 发布前检查
python3 scripts/consistency-check.py --path . --output check.md
适用： - 重大发布前 - 大重构后 - API 变更后
4. 完整文档 overhaul
python3 scripts/docs-improver.py --path . --mode all --output ./docs --report report.md
适用： - 文档严重过时 - 新项目文档搭建 - 技术债务冲刺
文档模板
包含 6+ 专业模板：
- README.md 模板
- API.md 模板
- ARCHITECTURE.md 模板
- CONTRIBUTING.md 模板
- CHANGELOG.md 模板
- ADR（架构决策记录）模板
Mermaid 图表模板
包含 10+ 图表模板：
- 系统架构图
- 微服务架构
- 分层架构
- 事件驱动架构
- 流程图
- 序列图
- 类图
- 状态图
- ER 图
- 甘特图
与 AI 助手配合
Claude/Codex:
"评估我们的文档质量并提出改进建议"
AI 会： 1. 运行 docs-improver 2. 解读质量报告 3. 生成具体改进计划 4. 帮助实施建议
最佳实践
详见 references/best-practices.md： - 文档写作风格指南 - 技术文档最佳实践 - 模板使用指南 - 图表绘制规范
参见
- 文档模板
- Mermaid 图表
- OpenClaw 文档