Markdown オーサリング

GitHub Flavored Markdown (GFM) 標準、VS Code 言語機能、および組織的慣例に従い、自動構造修正と手動セマンティックレビューを使用して Markdown ファイルをフォーマットおよび検証します。

このスキルを使用する場合

• Markdown ファイル (.md) を作成または変更する
• Markdown リント エラーを修正する
• 新しいリポジトリに Markdown ツールをセットアップする
• コミット前に Markdown ファイルを検証する
• コンテンツを組織の Markdown 標準に適合させるよう変換する

必要なツール

• read, edit — ファイル操作の核となる機能
• execute — リントタスクとコマンドを実行する
• search — Markdown ファイルとパターンを検索する

ワークフロー

ステップ 1: 自動リントを修正と共に実行する

構造的な問題を解決するために、自動修正機能付きで markdownlint を実行します。

npx markdownlint-cli2 --no-globs {filepath} --fix

注: 単一の明示的なファイルをリントする場合は --no-globs を使用して、意図しないグロブ展開を防ぎます。リポジトリ全体のリントまたは CI ジョブの場合は、フラグを省略するか、明示的なグロブ/CI で設定されたファイルリストを使用してください。

自動修正が対応する内容:

• 箇条書きスタイル (* と + を - に変換)
• ヘッダースタイル (Setext を ATX に変換)
• ヘッダーとコードブロックの周囲の空白行
• コードフェンススタイルと言語識別子
• ネストされたコードブロックのフェンス長

自動修正が対応しない内容 (手動レビューが必要):

• ヘッダーの文頭大文字化
• 太字ラベルの文頭大文字化
• コンテンツの構成
• リンクの有効性
• セマンティック的な正確性

ステップ 2: 手動セマンティックレビューと修正

自動リントが修正できない問題についてファイルをレビューします。

ヘッダー:

• 文頭大文字化に変換: 「How To Use」 → 「How to use」
• 最初の単語と固有名詞のみを大文字にする (GitHub、TypeScript、MADR)
• 冠詞 (a, an, the)、前置詞 (of, to, for)、接続詞 (and, but, or) は小文字にする

リスト開始時の太字ラベル:

• 文頭大文字化に変換: 「Next Steps:」 → 「Next steps:」

リファレンス構文:

• #file: リファレンスからバッククォートを削除: `#file:path` → #file:path
• #file: トークン後の末尾の句読点を削除する
• エントリーポイント ファイル (AGENTS.md) の #file: を Markdown リンクに置き換える

リスト:

• 順序がない項目の順序付きリストを順序なしハイフンリストに変換する
• 適切なインデント配置を確保する

コードブロック:

• すべてのフェンスブロックに言語識別子を追加する (不明な場合は plaintext を使用)
• ネストされたブロックの外側のフェンスがより長いことを確認する

完全なルールはフォーマット標準を参照してください。

ステップ 3: リントで検証する

エラーがゼロであることを確認するために、修正なしで markdownlint を実行します。

npx markdownlint-cli2 --no-globs {filepath}

期待される出力: エラーまたは警告なし

エラーが残っている場合:

• エラーメッセージを確認して特定の違反を把握する
• 問題を手動で修正する
• 検証を再実行する
• エラーがゼロになるまで繰り返す

ステップ 4: コンテンツ品質チェック

コンテンツレベルの要件を確認します:

1. リンク: すべての内部リンクが既存のファイルに解決される
2. コードフェンス: すべてのブロックに言語識別子がある
3. ヘッダー: 文頭大文字化、ATX スタイル、連続した階層 (レベルのスキップなし)
4. リスト: ハイフン箇条書きのみ、適切なインデント
5. ファイル終了: 空白行、--- セパレータ、「Last updated: {date}」フッター (formatting-standards の除外を参照: .github//*.md、README.md、AGENTS.md、.agents//.md、docs/adr/.md)
6. ダイアグラム: Mermaid ダイアグラムはストロークスタイルを使用 (塗りつぶし色ではない)
7. HTML: 許可されている要素のみ、すべての画像に alt テキストがある

完全な品質チェックは検証チェックリストを参照してください。

ステップ 5: オプション: 継続的フィードバック

反復的な編集セッションの場合、ウォッチモードを使用して継続的なフィードバックを取得します:

npx markdownlint-cli2 --no-globs {filepath} --watch

編集中にリアルタイムのリントフィードバックが提供されます。

ステップ 6: リポジトリセットアップ (ツールが見つからない場合)

Markdown ツールがリポジトリで設定されていない場合は、完全なスタックをセットアップします:

1. VS Code 拡張機能をインストール (vscode-markdownlint、github-markdown-preview、EditorConfig)
2. VS Code 設定を構成 (defaultFormatter、formatOnSave、codeActionsOnSave)
3. リント設定を作成 (.markdownlint-cli2.jsonc とベースラインルール)
4. VS Code タスクを追加 「Lint: Markdown」、「Lint: Markdown (auto-fix)」
5. 配置を確認 (settings.json、extensions.json、tasks.json、editorconfig)
6. セットアップをテスト (既存ファイルでリントを実行)

ステップバイステップの設定についてはセットアップガイドを参照してください。

完了条件

• すべての構造的なリントエラーが解決されている (markdownlint-cli2 からエラーゼロ)
• すべてのセマンティック問題が修正されている (文頭大文字化ヘッダー、太字ラベル)
• すべてのリファレンス構文が修正されている (#file:、Markdown リンク)
• すべてのコンテンツ品質チェックに合格している (リンク、フェンス、階層)
• ファイル終了フォーマットが必要な場合は適用されている
• ファイルがリポジトリにコミットされている

よくある落とし穴

自動リントのみに依存する:

• 自動修正は構造を処理し、セマンティクスは処理しない
• 文頭大文字化の手動レビューは必須
• コンテンツ構成には人間の判断が必要

エントリーポイント ファイルで #file: を使用する:

• AGENTS.md とルート命令は多くのコンテキストで自動ロードされる
• #file: リファレンスはカスケードしてコンテキストの肥大化を引き起こす
• 代わりに標準の Markdown リンクを使用する

手動編集後の検証をスキップする:

• 手動変更後は常にリントを再実行する
• 新しい編集で新しい違反が導入される可能性がある
• エラーゼロの検証が必要

不正なリファレンス構文:

• バッククォートは #file: トークン解析を破壊する
• 末尾の句読点はトークン解決を破壊する
• MCP サーバーの誤った #tool: フォーマット

ワンタイム セットアップ

markdownlint-cli2 のインストールと VS Code 拡張機能のセットアップについては、Markdown ツールセットアップガイドを参照してください。

その他のリファレンス

• GitHub Flavored Markdown 仕様
• markdownlint-cli2 ドキュメント