Docs Improver

专业技术文档提升工具。评估文档质量（完整性、准确性、清晰度、结构化、可维护性），自动生成缺失文档（README、API 文档），检查文档与代码一致性，提供可执行的改进建议。使用场景：文档质量审计、缺失文档生成、文档一致性检查、文档改进规划、新项目文档搭建、发布前检查。支持所有编程语言。

Security Scan

The skill is an internally consistent, instruction-first documentation tool that reads a project tree and generates/edits docs locally; it does not request credentials, install remote code, or contact external endpoints in the provided files.

Purpose & Capability

Name/description match the implementation: Python scripts scan project files, assess docs, check consistency, and generate README/API/ARCHITECTURE files — all expected for a 'Docs Improver'. No unrelated credentials, binaries, or config paths are requested.

Instruction Scope

SKILL.md instructs the agent to run the included scripts against a user-specified path. The scripts operate on repository files (rglob *.md, *.py, etc.), produce reports, and write generated docs — this is within the stated scope. There are no instructions to read unrelated system config, secrets, or to exfiltrate data.

Install Mechanism

No install spec is present (instruction-only plus included Python scripts). Nothing is downloaded or executed from remote URLs; risk from install mechanism is minimal.

Credentials

No environment variables, credentials, or external tokens are required. The scripts accept a --path argument and operate on local files only, which is proportionate to the skill's purpose.

Persistence & Privilege

The skill is not always-enabled and does not request elevated or persistent privileges. It writes documentation files into the target project directory (normal behavior) and does not modify other skills or global agent settings.

Assessment

This skill appears coherent and operates on local project files only. Before running it: (1) review the full scripts if possible (they are included) to confirm no hidden network calls or surprising behavior, (2) run it against a copy or branch of your repository (it will create/overwrite README/API/ARCHITECTURE files), and (3) back up any important docs. If you need stronger guarantees, run the scripts in an isolated environment (container or VM) and inspect generated outputs before committing changes.

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 文档