documentation-auditor

takumi0706's avatarfrom takumi0706

プロジェクト内のドキュメント（README.md、CHANGELOG.md、docs/ など）を監査し、コード変更に基づいて更新が必要な箇所を特定・提案します。作業完了後のドキュメント更新確認に使用。

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 1, 2026
[Technical Writing]

When & Why to Use This Skill

The Documentation Auditor is a specialized Claude skill designed to automate the maintenance of technical documentation. By analyzing code changes through git diffs, it identifies outdated sections in README.md, CHANGELOG.md, and other project documents. This skill ensures your documentation remains accurate and synchronized with your codebase, providing intelligent update suggestions and automated editing to streamline the technical writing process for developers.

Use Cases

  • Post-Development Audit: Automatically identify and update README sections when new features, CLI flags, or environment variables are added to the source code.
  • Changelog Automation: Maintain an accurate CHANGELOG.md by auditing recent commits and file modifications to ensure all significant updates are recorded.
  • API Documentation Sync: Ensure that Markdown-based API references in the docs/ folder accurately reflect changes made to API endpoints, parameters, or data structures.
  • Project Metadata Validation: Audit internal project guides like CONTRIBUTING.md or .claude/CLAUDE.md to ensure they align with the current project architecture and environment settings.
namedocumentation-auditor
descriptionプロジェクト内のドキュメント（README.md、CHANGELOG.md、docs/ など）を監査し、コード変更に基づいて更新が必要な箇所を特定・提案します。作業完了後のドキュメント更新確認に使用。

Documentation Auditor Skill

プロジェクト内のドキュメントを監査し、更新提案を行います。

デフォルト監査対象

以下のドキュメントを自動検出して監査:

  • README.md, README.mdx - プロジェクト説明
  • CHANGELOG.md, CHANGELOG.txt - 変更履歴
  • docs/ ディレクトリ内の全 Markdown
  • .claude/CLAUDE.md - Claude Code 設定
  • CONTRIBUTING.md - コントリビューションガイド

プロジェクト固有設定

.claude/doc-audit.json が存在する場合、その設定を優先:

{
  "documents": ["path/to/doc.md"],
  "exclude": ["docs/generated/**"],
  "triggers": {
    "src/api/**": ["docs/api.md"],
    "src/components/**": ["docs/components.md"]
  }
}

監査プロセス

1. 変更検出

git diff --name-only で変更ファイルを特定

2. 関連ドキュメントの特定

  • 変更ファイルのパスに基づいて関連ドキュメントを推定
  • プロジェクト設定ファイルがあれば、その triggers を使用

3. 整合性チェック

  • ドキュメントの内容と実際のコード/設定を比較
  • 新機能がドキュメント化されているか
  • 削除された機能がドキュメントから削除されているか
  • API変更がドキュメントに反映されているか

4. 更新提案

  • 自動更新可能: 変更内容を提示し、確認後に更新
  • 判断が必要: 更新提案と理由を提示

出力形式

## ドキュメント監査結果

### 更新が必要なドキュメント

1. **README.md**
   - 理由: 新しい CLI オプション --verbose が追加されました
   - 推奨: 「使用方法」セクションに追記

2. **docs/api.md**
   - 理由: /api/users エンドポイントのレスポンス形式が変更
   - 推奨: API リファレンスを更新

更新を実行しますか？

監査実行手順

  1. git status と git diff --name-only HEAD で変更ファイルを確認
  2. プロジェクト内のドキュメントファイルを Glob で検索
  3. 変更内容とドキュメントの整合性を確認
  4. 更新が必要な場合は具体的な提案を行う
  5. ユーザーの承認後に更新を実行