| name | writer |
| description | ASP.NET Core ハンドブックの新規章コンテンツを作成する。Use when: 新しい章を書く、ドキュメントを作成する、チャプターを追加する、コンテンツを執筆する。技術ドキュメントのライティング、ASP.NET Core ガイドの執筆。 |
| argument-hint | 作成する章のタイトルとセクション一覧を指定 |
ASP.NET Core ハンドブック ライタースキル
概要
このスキルは、docs/ フォルダ内に新しい章のマークダウンドキュメントを作成するためのワークフローです。
対象読者は C# 以外の言語経験者 であり、日本語で記述します。
前提条件
- 言語: 日本語
- 対象読者: 他言語の経験者（対象言語・フレームワーク一覧は
.github/skills/languages.md を参照）
- 対象バージョン:
.github/instructions/versioning.instructions.md のバージョン決定ルールに従い、作成時点の最新バージョンを使用する
手順
1. 情報収集
以下の情報源を 必ず 確認し、最新かつ正確な内容のみを記載する。
- MS Learn 公式ドキュメント — ASP.NET Core や .NET 固有の概念だけでなく、一般的な IT 知識についても MS Learn を根拠とする
- URL パターン:
https://learn.microsoft.com/en-us/aspnet/core/...?view=aspnetcore-N.0（N はバージョン決定ルールで決定した番号）
- マークダウン取得: URL に
&accept=text/markdown を付与して curl で取得するとノイズが少ない
- ロケール運用: 情報収集時は
en-us の URL を使用し、章末の参考リンクとして記載する際は ja-jp の URL を使用する
- 他言語フレームワークの公式ドキュメント — 比較情報を記載する際は、各フレームワークの最新ドキュメントを検索して正確性を確認する
2. 既存ドキュメントの形式確認
docs/ フォルダ内の既存ファイル（例: 01-setup-dev-env.md, 02-solutions-and-projects.md）を読み、以下の形式要素を踏襲する。
ドキュメント構造
# 第N章：タイトル
---
## 目次
1. [セクション1](#anchor)
- [サブセクション](#anchor)
2. [セクション2](#anchor)
...
---
## 1. セクション1
### サブセクション
...
## N. 参考ドキュメント
- [タイトル | Microsoft Learn](URL)
---
*前の章: [第N-1章：タイトル](./NN-filename.md)*
*次の章: [第N+1章：タイトル](./NN-filename.md)*
形式ルール
| 要素 | ルール |
|---|
| 見出し | # = 章タイトル、## = 大セクション（番号付き）、### = サブセクション、#### = 小見出し |
| 目次 | ドキュメント冒頭に ## 目次 として内部アンカーリンク一覧を配置 |
| コードブロック | 言語指定必須（csharp, xml, json, bash, text など） |
| 図表 | Mermaid 記法で概念図・フローチャートを積極的に使用 |
| 注記 | > [!TIP], > [!NOTE], > [!WARNING] を適切に使い分け |
| テーブル | 比較情報や一覧はテーブルで整理 |
| 他言語比較 | > [!TIP] または > [!NOTE] ブロック内に記載 |
| 折りたたみ | IDE 別の手順は <details><summary> で折りたたむ |
| 参考リンク | 最終セクションに MS Learn 等の公式ドキュメントリンクを一覧化 |
| 前後リンク | ドキュメント末尾に前後の章へのリンクを配置 |
3. コンテンツ作成の原則
- 初心者にわかりやすく — 概念の説明は具体例とコードサンプルを交えて記述する
- 実装サンプルを豊富に — 可能な限り動作するコード例を記載し、コピー＆ペーストで試せるようにする
- 最新バージョン準拠 — バージョン決定ルールで決定した .NET N / ASP.NET Core N に準拠し、古い API（Startup.cs 方式など）ではなく最新の Program.cs 方式で記載する
- 最新 C# 機能の活用 — 対象バージョンに対応する最新の C# 言語機能を使用する
- MS Learn を根拠にする — 独自の解釈や推測ではなく、公式ドキュメントの記載を根拠とする
- 他言語比較を含める — ASP.NET Core 特有の機能について、
.github/skills/languages.md に記載の言語・フレームワークに対応する機能がある場合は NOTE として比較を記載する
4. 日本語表記ルール
- カタカナ語の長音符号:
.github/instructions/katakana.instructions.md の辞書に従う
- 句読点: 「、」「。」を使用
- 専門用語: 初出時に英語を括弧で併記（例: 依存性注入 (Dependency Injection: DI)）
5. 品質チェック
コンテンツ作成後に以下を確認する。
出力先
- ファイルパス:
docs/NN-<slug>.md（NN は章番号の 2 桁ゼロ埋め）
- ファイル名のスラッグ: 英語のケバブケース（例:
06-dependency-injection.md）
