# Markdown Writer > markdown（.mdファイル）を新規作成・編集・添削するときに必ず使う。README、ドキュメント、仕様書、SKILL.md、CLAUDE.mdなどあらゆるmarkdownの執筆・修正で起動し、LLMが解釈しやすいmarkdownを出力する。「markdownを書いて」「ドキュメントを作って／直して」「READMEを更新」「.mdを編集」などmarkdownの記述が関わる作業すべてが対象。空間的レイアウトに依存せず線形構造と明示的な言葉で表現する。 - Skill: `s2terminal/markdown-writer` (Agent Skill) - Install (CLI): `npx skillmds@latest add s2terminal/markdown-writer` - Raw SKILL.md: https://api.skillmd.com/api/skills/s2terminal/markdown-writer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: s2terminal (https://skillmd.com/u/s2terminal) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/s2terminal/markdown-writer --- LLMが解釈しやすいmarkdownを作成、または既存のmarkdownを添削してください。 ## 基本方針 LLMはテキストをトークンの並びとして線形（1次元）に読む。 人間のように視線を2次元的に動かして表や図の空間的な対応関係を把握することは苦手である。 そのため「見た目（空間的レイアウト）に意味を持たせる表現」を避け、「テキストの並び（線形構造）と明示的な言葉」で意味を表現することを最優先する。 ### 守るべき原則 以下の原則に従ってmarkdownを作成・添削する。 1. **データ構造は表よりリストやコードブロックで表現する** - 多列・セル結合・長文セル・ネストを含む複雑なテーブルは避ける - 行と列の対応がトークン列の中で離れ、誤読の原因になるため - 単純な対応関係はネストした箇条書きで表現する - 厳密な構造を渡したい場合はJSONやYAMLのコードブロックにする - ごく単純な2〜3列で各セルが短い表に限り、テーブルを使ってもよい 2. **図やフローはアスキーアートで書かない** - 罫線図、ボックスと矢印などのアスキーアートは、空間配置に意味を持たせるため誤読される - 関係や流れは、文章と番号付きリストで明示的に記述する - 図として表現したい場合は、空間配置に依存せず関係をテキストで宣言するMermaid記法を使う 3. **見出しで階層を明確にする** - `#`から始まる見出しで文書を階層化し、情報がどのセクションに属するかを明確にする - 見出しは内容を表す具体的な語にする（「詳細」ではなく「認証エラーの対処」など） - 見出しレベルを飛ばさない（`#`の次は`##`にする） 4. **明示的に書き、暗黙の前提や省略を減らす** - 「それ」「上記の方法」などの代名詞や指示語を減らし、具体名を繰り返す - 人間なら文脈で補える前提も言葉にして書き出す - 長い散文より、項目に分割した箇条書きを優先する 5. **逐語的なものはコードブロックで隔離する** - ファイルパス、コマンド、設定値、識別子などはインラインコードやコードブロックで囲む - コードブロックには可能な限り言語を指定する 6. **区切りと記法を一貫させる** - セクション境界は水平線`---`や空行で明確に区切る - リストマーカーや強調記法を文書内で統一する - 1行を極端に長くせず、論理的な単位で改行する ### 表現の使い分け 伝えたい内容ごとに、以下の表現を選ぶ。 - 厳密なデータ構造: JSONまたはYAMLのコードブロック - 単純な対応関係: ネストした箇条書き - 処理の流れや関係図: 文章と番号付きリスト、または Mermaid記法 - 逐語的な値やコマンド: コードブロック - 文書の論理構造: 見出しの階層 ## 手順 ### 1. 入力内容の確認 markdownにしたい内容、または添削対象のmarkdownを確認する。 ファイルパスが指定された場合はそのファイルを読み込む。 何を伝えるための文書なのか（目的と想定読者）を把握する。 不明確な場合は、入力内容から最も妥当に推測できる目的を前提として進める。 ### 2. 表現方法の選択 入力内容に含まれる情報を、伝えたい内容ごとに分類し、「表現の使い分け」に従って最適な表現方法を選ぶ。 特に以下を確認する。 - データ構造を表現する箇所が、複雑なテーブルになっていないか - なっている場合は箇条書きやJSON/YAMLに置き換える - 図やフローがアスキーアートになっていないか - なっている場合は文章と番号付きリスト、またはMermaidに置き換える ### 3. markdownの作成・添削 「守るべき原則」と選択した表現方法に従ってmarkdownを作成する。 添削の場合は、原則に反する箇所を修正する。 新規作成の場合はWriteで、添削の場合はEditで出力する。 出力先が指定されていない場合は、内容に応じた適切なファイル名で作成する。 ### 4. 確認 作成・添削したmarkdownが「守るべき原則」のすべてを満たしているかを再確認する。 - 複雑なテーブルが残っていないこと - アスキーアートの図が残っていないこと - 見出しで階層が明確になっていること - 代名詞や省略が過剰でなく、明示的に書かれていること - 逐語的なものがコードブロックで隔離されていること - 区切りと記法が一貫していること すべてを満たしていれば、作成・添削したファイルのパスを出力して作業を終了する。 原則に反するが入力内容の都合で修正できなかった箇所があれば、その理由を添えて報告する。