--- name: markdown-docs description: "Use when the user asks to create, edit, review, proofread, restructure, lint, or improve Markdown documents such as README, technical docs, API docs, guides, release notes, or Japanese/English writing." --- # Markdown Document Skill マークダウン形式のドキュメント作成、編集、校閲、レビューを支援するスキル。 ## ワークフロー判定 ### 新規作成 → 「ドキュメント作成ワークフロー」へ ### 既存ドキュメントの編集 → 「編集ワークフロー」へ ### 校閲・レビュー依頼 → 「レビューワークフロー」へ 依頼が「レビュー」「校閲」だけなら、直接編集するかレビューコメントだけ返すかを確認する。既存ファイル編集の依頼なら、対象読者、言語、文体、変更範囲を既存内容から読み取り、不足時だけ確認する。 --- ## ドキュメント作成ワークフロー ### Step 1: 要件確認 以下を確認する: 1. ドキュメントの種類（README、技術仕様、ガイド、API仕様など） 2. 対象読者（開発者、エンドユーザー、チームメンバーなど） 3. 必須セクション（インストール方法、使い方、APIリファレンスなど） 4. 言語（日本語、英語、バイリンガル） ### Step 2: 構成提案 ドキュメント種類に応じた標準構成: **README** ```markdown # プロジェクト名 ## 概要 ## 機能 ## インストール ## 使い方 ## 設定 ## 開発 ## ライセンス ``` **技術仕様書** ```markdown # タイトル ## 背景・目的 ## 設計 ## 実装詳細 ## テスト方針 ## 制限事項 ``` **APIドキュメント** ```markdown # API名 ## エンドポイント一覧 ### GET /resource #### リクエスト #### レスポンス #### エラー ``` ### Step 3: 執筆 各セクションを順番に執筆。ユーザーからのフィードバックを反映しながら進める。 --- ## 編集ワークフロー ### Step 1: 現状把握 1. 対象ファイルを読み込む 2. 構成と内容を把握 3. 編集目的を確認（内容追加、構成変更、表現改善など） 4. 既存の文体、用語、見出し階層、リンク形式、コードブロック言語を確認する ### Step 2: 編集実施 **内容追加**: 既存の構成に合わせて追記 **構成変更**: セクションの順序や階層を調整 **表現改善**: 簡潔で明確な表現に修正 ### Step 3: 確認 編集後の差分を確認し、意図通りの変更か検証。 - 内部リンク、相対リンク、画像パス、見出しアンカーを確認する。 - コマンドやAPI名などのリテラルは勝手に言い換えない。 - 最終報告には変更したファイル、主な編集内容、リンク検証の有無、未確認事項を含める。 --- ## レビューワークフロー ### Step 1: 全体確認 ドキュメントを通読し、以下を確認: - 論理的な構成か - 情報の過不足はないか - 対象読者に適切か ### Step 2: 詳細チェック 詳細は[レビューチェックリスト](references/review-checklist.md)を参照。 主要チェック項目: 1. **構成・構造**: 見出し階層、セクション順序 2. **内容**: 正確性、網羅性、冗長性 3. **文章**: 文法、表現、一貫性 4. **フォーマット**: マークダウン記法、リンク 5. **アクセシビリティ**: 画像alt属性、見出し構造 ### Step 3: フィードバック 問題点と改善提案を以下の形式で報告: ```markdown ## レビュー結果 ### 重要度: 高 - [具体的な問題と改善案] ### 重要度: 中 - [具体的な問題と改善案] ### 重要度: 低（推奨） - [具体的な問題と改善案] ``` --- ## 品質基準 ### 文章スタイル - 一文は60文字以内を目安 - 主語と述語を明確に - 専門用語は初出時に説明 - 箇条書きを活用して読みやすく ### マークダウン記法 - 見出しは`#`の後にスペース - コードブロックには言語指定 - リンクテキストは具体的に（「こちら」は避ける） - 画像にはalt属性を付与 ### 一貫性 - 用語の統一（表記揺れを避ける） - 文体の統一（です/ます調 or である調） - フォーマットの統一（日付形式、コードスタイルなど） --- ## リファレンス - [レビューチェックリスト](references/review-checklist.md): 詳細なレビュー観点