mdsvr スキル用 Markdown

mdsvr で使用するための、完全で有効なマルチファイルMarkdownドキュメントセットを生成します。サーバーモードと静的エクスポートの両方をサポートします。

このスキルがトリガーされると、一貫性のあるドキュメントサイトを形成する複数の .md ファイルを、すべてのmdsvr規約に厳密に従って生成します。

ステップ1 — リクエストを理解する

ファイルを生成する前に、ユーザーのリクエストから以下を抽出します：

トピック / 製品名 — 何をドキュメント化するのか？
ターゲットオーディエンス — 開発者、エンドユーザー、運用チームなど
範囲 — 必要なページ数/セクション数
言語 — 日本語、英語、またはバイリンガル？
図は必要か？ — 必要な場合は、references/rules/mermaid.md を読んで構文ルールを確認します。

不明な点がある場合は、先に進む前に1つの焦点を絞った質問をしてください。

ステップ2 — ファイル構造を計画する

コンテンツを書く前に、論理的な階層を設計します。典型的なmdsvrドキュメントサイト：

docs/
├── README.md                    ← ホームページ（必須）
├── 01-getting-started/
│   ├── README.md                ← セクションインデックス
│   ├── 01-installation.md
│   ├── 02-quickstart.md
│   └── 03-configuration.md
├── 02-guides/
│   ├── README.md
│   ├── 01-basic-usage.md
│   └── 02-advanced.md
├── 03-api-reference/
│   ├── README.md
│   └── 01-endpoints.md
└── 04-troubleshooting.md

ユーザーのトピックに合わせて構造を調整します。必要に応じて規模を拡大または縮小します。

ステップ3 — mdsvrのファイルとリンクのルールを適用する（必須）

3.1 ファイル命名ルール

ルール	❌ 誤り	✅ 正しい
名前にドットを含めない	`0.1.quickstart.md`	`01-quickstart.md`
名前にドットを含めない	`config.v2.md`	`config-v2.md`
ケバブケースを使用する	`GettingStarted.md`	`getting-started.md`
順序を示す数値プレフィックスを使用する	`guide.md`（サイドバー内）	`01-guide.md`
説明的な名前を使用する	`page1.md`	`installation.md`
ディレクトリインデックスは	`index.md`	`README.md`

3.2 リンク構造ルール

ルール	❌ 誤り	✅ 正しい
相対パスのみを使用する	`[Guide](/docs/guide)`	`[Guide](./guide)`
リンクに `.md` 拡張子を含めない	`[Setup](./setup.md)`	`[Setup](./setup)`
READMEではなくディレクトリにリンクする	`[Start](./01-getting-started/README)`	`[Start](./01-getting-started)`
アンカーリンクは見出しと一致させる	`[See](#install-steps)`（見出しが存在しない場合）	完全に一致させる

3.3 見出し構造ルール

ルール	❌ 誤り	✅ 正しい
すべてのページにH1が必要	(ページがH2で始まる)	最初の見出しとして `# Page Title`
見出しレベルをスキップしない	H1 → H3	H1 → H2 → H3
見出しは説明的であること	`## Section 1`	`## インストール要件`

ステップ4 — すべてのファイルにフロントマターを適用する

各 .md ファイルには、SEOとmdsvrメタデータのためにYAMLフロントマターを含める必要があります：

---
title: "ページタイトル"
description: "このページの内容を一文で説明します。"
---

ステップ5 — コンテンツガイドライン

README.md（ホームページ）— 必須

docsフォルダのルートに存在する必要があります。
プロジェクトの概要、すべてのセクションへのクイックナビゲーションリンクを含めます。
必要に応じてウェルカムコールアウトを使用します。

セクション README.md（ディレクトリインデックス）

セクションの内容を要約します。
関連リンクとともに、セクション内のすべてのページをリストします。

コンテンツページ

1ページに1つのトピックに焦点を当てます。
簡単な導入段落で始めます。
必要に応じてMDXコンポーネントを使用します：
- コールアウトには :::note, :::warning, :::tip, :::danger を使用します。
- ステップバイステップの手順には番号付きリストを使用します。
相対パスを使用して関連ページに自由にリンクします。
必要に応じて「次のステップ」または「関連項目」セクションで終了します。

ステップ6 — Mermaid図（必要な場合）

ドキュメントに図（アーキテクチャ、フロー、シーケンス、ERD、ステートマシンなど）が役立つ場合は、関連する .md ファイルにMermaid図をインラインで埋め込みます。

図を生成する前に、完全な構文リファレンスと生成ルールについて references/rules/mermaid.md を読んでください。そのファイルのすべてのルールは必須です。

クイックチェックリスト（mermaid.md より）：

最も適切なダイアグラムタイプを選択してください — デフォルトで flowchart にしないでください。
フローチャートでは常に方向を宣言してください：flowchart TD または flowchart LR。
ノードID：文字、数字、アンダースコアのみ。-、.、(、) は使用しないでください。
スペースを含むノードラベルは二重引用符を使用します：A["My Label"]。
サブグラフには明示的なIDが必要です：subgraph myid["Label"]。
シーケンス図：メッセージの前にすべての participant 行を宣言してください。
ユーザーが明示的に要求しない限り、色やスタイルをハードコードしないでください。
意味を伝えるために色の代わりに絵文字を使用してください。
コードブロックごとに1つの図にしてください。出力前に構文を検証してください。

ステップ7 — ファイルを作成して提供する

create_file を使用して各 .md ファイルをファイルシステムに書き込みます。次にすべてをZIPに圧縮し、present_files を呼び出してユーザーが結果をダウンロードできるようにします。

7.1 各ファイルを書き込む

計画された構造のすべてのファイルについて、/mnt/user-data/outputs/<project-name>/ の下のフルパスで create_file を呼び出します：

/mnt/user-data/outputs/my-project/README.md
/mnt/user-data/outputs/my-project/01-getting-started/README.md
/mnt/user-data/outputs/my-project/01-getting-started/01-installation.md
...

各呼び出しで、完全な最終コンテンツを書き込みます。プレースホルダーは書き込まないでください。

7.2 ZIPに圧縮して提供する

すべてのファイルが書き込まれたら、出力フォルダをZIPに圧縮し、present_files を呼び出します：

cd /mnt/user-data/outputs
zip -r my-project-docs.zip my-project/

次に、.zip ファイルへのパスを指定して present_files を呼び出します。

7.3 チャットでの要約

present_files の後、チャットに短いメッセージを書き込みます。内容は以下の通りです：

ファイルツリー — 生成された完全なディレクトリ構造を表示します。
サーバーの起動方法 — ワンライナー：npx mdsvr ./my-project または mdsvr ./my-project。
ページ数 — 例：「3つのセクションにわたって8ページを生成しました。」

クイックリファレンス — 避けるべき一般的な間違い

❌ リンクに絶対パスを使用：[Page](/docs/page)
✅ 相対パスを使用：[Page](./page)

❌ リンクに .md 拡張子を含める：[Page](./page.md)
✅ 拡張子を含めない：[Page](./page)

❌ READMEファイルにリンクする：[Section](./01-section/README)
✅ ディレクトリにリンクする：[Section](./01-section)

❌ ファイル名にドットを使用する：01.quickstart.md
✅ ハイフン区切りを使用する：01-quickstart.md

❌ H1が欠落している：## Introduction（最初の見出しがH2）
✅ H1で始める：# Introduction

❌ 見出しレベルをスキップする：# Title → ### Sub（H2をスキップ）
✅ 適切な階層：# Title → ## Section → ### Subsection

❌ フロントマターがない：（ファイルが # で直接始まる）
✅ フロントマターが存在する：--- title: "..." description: "..." ---

参考ファイル

references/rules/mermaid.md — 19のダイアグラムタイプすべてに対応する、完全なMermaid v11構文リファレンス。ドキュメント内で図が必要な場合は常にこれを読んでください。

satoshiman/mdsvr

mdsvr とは？

お気に入りのAIに質問する

ドキュメント