markdown

name: markdown description: Skill for writing or editing Markdown and Markdown-like text on services like Notion, Zenn, or note.

Markdown

Markdown、および Notion・Zenn・note など Markdown-like な記法で記述するサービス上の文章は、文章による完全な説明、見出し・リスト・テーブルによる体系的な整理、必要に応じたMermaid図による視覚的補助で構成する。読み手が論理構造を辿れるよう、情報の羅列ではなく論理ピラミッドの構築を意識する。

Principles

体系性・簡潔性・論理性の3点を最重視する。装飾や記号の多用は読み手の認知負荷を上げるため、必要最低限に抑える。

• 体系性：情報を階層と種別で整理し、見出し・リスト・テーブルを使い分ける。
• 簡潔性：冗長な改行や記号を排除し、完全な文章で意図を伝える。
• 論理性：箇条書きや図を使う前に、要点・結論・示唆を文章で提示する。

既存ドキュメントを更新する際は、言い回しなど枝葉の表現を局所的に書き換えるのではなく、文書全体の論理構造を俯瞰したうえで再分解と再構築を経て本質的に更新する。部分的な修正は構造の歪みや論理の断絶を生むため、骨格レベルで整合を取り直す。

Notation

Front Matter

Front Matter のメタデータは、キーと値のいずれも英語で記載する。

Headings

見出しは文章の論理構造を可視化するために使用する。読み手が目次として一覧したときに、文書全体の骨格が把握できる粒度で設計する。

• H1 および H2 見出しは基本的に英語で記載する（例: Introduction / Overview）。
• 見出しは文章ではなく、簡潔な1〜3語の組み合わせにする（例: Getting Started / References / How to Work）。
• 通し番号や絵文字は付与しない。番号や装飾は構造そのものを曖昧にする。
• 階層は内容の論理構造に従って自然に決める。装飾目的で深くしない。
• セクションは体系的でMECEな見出しで構築し、羅列したような見出しで構成しない。

Lists

リストは兄弟関係（並列・直列）にある複数要素を扱うときに使用する。要素を並べる前に、必ずまとめ・結論・示唆を文章で記載し、なぜその要素群を提示するのかを示す。

リストの構造化ルールを以下に示す。

• ネストは1階層までとする。2階層以上が必要な場合はページや見出しの分割を検討する。
• 要素数が5つ以上になる場合は、テーブルやデータベースの利用を検討する。視認性が落ちるため。

Text

句読点や改行を過度に挟まず、完全な文章を記載する。1文を細切れにせず、主述を明確にした文を書く。

テキスト内で利用するMarkdown記法のルールを以下に示す。

• 太字：必要最低限の利用に留める。乱発すると強調の効果が失われる。
• インラインコードブロック：数値や固有の値を記載する際に使用する。コードブロックの前後には半角スペースを挿入する（例： 42 件、 userId フィールド）。

Tables

複数項目を列方向に比較する場合や、リスト要素が5つ以上になる場合に使用する。ヘッダーの区切り線は各列ともハイフン、もしくはコロン3つの組み合わせとする（例： --- , :-- , :-: ）。

Others

見出し・リスト・テキスト・テーブル・Mermaid のいずれにも属さない記法は、構造を曖昧にしないために利用範囲を限定する。

• 区切り線：冒頭で文書のメタ情報と本文を分けるとき以外は利用しない。本文中の --- は構造の分断を生むため避ける。

Mermaid

フローチャート、データフロー、ロジックツリー、シーケンス図などを描画する際は、常にMermaid形式で作成する。画像ファイルや外部ツールに依存させない。

Mermaid作成時の制約を以下に示す。

• 物理名（変数・ノードID）はcamelCaseの英語で記述する。
• 論理名（表示ラベル）は日本語で、1語ないし2語のシンプルな単語にする。
• CSSによるスタイリング（ classDef , style ）は適用しない。構造そのもので意味を伝える。

例：

flowchart LR
  userRequest[ユーザー要求] --> validate[検証]
  validate --> process[処理]
  process --> response[応答]

Checklist

Markdownを書き終えたら、以下を確認する。

References

併用すべきスキルを以下に示す。

• Humanizer Skill：文章を人間らしい自然な表現に整える際に併用する。