docs-improver_skill

Overview

This skill is a professional technical documentation improver that analyzes, generates, and audits project docs across all programming languages. It evaluates quality dimensions like completeness, clarity, structure, maintainability, and accuracy, then produces missing artifacts and actionable improvement plans. The tool also checks consistency between documentation and code and prioritizes fixes into quick wins, short-term tasks, and long-term initiatives.

How this skill works

It scans a project path to evaluate documentation against multiple weighted dimensions and generates a quality report with scores and prioritized recommendations. It can auto-generate common files (README, API docs, architecture, install, contributing, changelog) and create templates and diagrams. It performs consistency checks between doc content and code (endpoints, examples, config, links) and outputs an issues report. Finally, it produces an actionable improvement plan with time estimates and priorities.

When to use it

• Perform a documentation quality audit before release or handover
• Generate missing documentation for a new project or open-source release
• Check doc-code consistency after API changes or refactors
• Build a documentation improvement roadmap for technical debt sprints
• Prepare onboarding materials and technical templates for new team members

Best practices

• Run a full analysis and consistency check before major releases
• Start with quick-win fixes from the report to improve developer experience fast
• Use generated templates as the base, then customize examples and architecture diagrams
• Automate recurring checks in CI to detect doc/code drift early
• Prioritize fixes by impact and effort: quick wins, short-term, long-term

Example use cases

• Run a full docs-improver pass to produce README, API.md, and an audit report for a new repo
• Use the generator to create an initial set of docs and diagrams when bootstrapping a project
• Execute a consistency check after an API change to find undocumented endpoints and broken examples
• Generate a prioritized improvement plan for a documentation sprint targeting technical debt
• Integrate periodic audits into CI to surface stale links, inconsistent terms, and missing config docs