markdown-docslisted

# Markdown Document Skill マークダウン形式のドキュメント作成、編集、校閲、レビューを支援するスキル。 依頼内容に応じて「作成」「編集」「レビュー」のワークフローを使い分ける。依頼が「レビュー」「校閲」だけなら、直接編集するかレビューコメントだけ返すかを確認する。既存ファイル編集の依頼なら、対象読者、言語、文体、変更範囲を既存内容から読み取り、不足時だけ確認する。 --- ## ドキュメント作成ワークフロー ### Step 1: 要件確認 以下を確認する: 1. ドキュメントの種類（README、技術仕様、ガイド、API仕様など） 2. 対象読者（開発者、エンドユーザー、チームメンバーなど） 3. 必須セクション（インストール方法、使い方、APIリファレンスなど） 4. 言語（日本語、英語、バイリンガル） ### Step 2: 構成提案 ドキュメント種類（README、技術仕様書、API ドキュメントなど）と対象読者に応じた標準構成を提案し、執筆前にユーザーと合意する。同種の既存ドキュメントがリポジトリにあれば、その構成に合わせる。 ### Step 3: 執筆 構成に沿って執筆し、後述の「品質基準」を満たしているかをセルフチェックする。���い文書はセクション単位でユーザーのフィードバックを反映しながら進める。 --- ## 編集ワークフロー ### Step 1: 現状把握 1. 対象ファイルを読み込む 2. 構��と内容を把握 3. 編集目的を確認（内容追加、構成変更、表現改善など） 4. 既存の文体、用語、見出し階層、リンク形式��コードブロック言語を確認する ### Step 2: 編集実施 **内容追加**: 既存の構成に合わせて追記 **構成変更**: セクションの順序や階層を調整 **表現改善**: 簡潔で明確な表現に修正 ### Step 3: 確認 編集後の差分を確認し、意図通りの変更か検証。 - 内部リンク、相対リンク、画像パス、見出しアンカーを確認する。 - Notion・Slack 等へ貼り付ける文書は、貼り付け後の表示で記号・箇条書き・強調が欠落しないか確認する（プレーンテキスト化で `*` や `•` が落ちる事故が起きやすい）。 - コマンドやAPI名などのリテラルは勝手に言い換えない。 - 最終報告には変更したファイル、主な編集内容、リンク検証の有無、未確認事項を含める。 --- ## レビューワークフロー ### Step 1: 全体確認 ドキュメントを通読し、以下を確認: - 論理的な構成か - 情報の過不足はないか - 対象読者に適切か ### Step 2: 詳細チェック 詳細は[レビューチェックリスト](references/review-checklist.md)を参照。 主要チェック項目: 1. **構成・構造**: 見出し階層、セクション順序 2. **内容**: 正確性、網羅性、冗長性 3. **文章**: 文法、表現、一貫性 4. **リンク**: 内部・外部リンク、相対パス、アンカー 5. **アクセシビリティ**: 画像alt属性、見出し構造 ### Step 3: フィードバック 問題点と改善提案を以下の形式で報告: ```markdown ## レビュー結果 ### 重要度: 高 - [具体的な問題と改善案] ### 重要度: 中 - [具体的な問題と改善案] ### 重要度: 低（推奨）