.NET/AspireでAIコーディングエージェントを使っている場合、今回の.NET documentation updateで最初に確認すべき点は、aspire agent initの案内が「スキルの配置先を選ぶ」→「インストールするスキルやツールを選ぶ」という新しい対話フローに整理されたことです。特に、標準のスキル配置先として.agents/skills/が追加され、dotnet-inspect skillもドキュメント上で扱われるようになりました。既存プロジェクトでは、古い.github/skills/や.claude/skills/だけを前提にした手順、チーム内のREADME、AIエージェント用の初期化スクリプトを見直す必要があります。(GitHub)
この更新は、microsoft/aspire.devのPR #827として作成され、microsoft/aspire#15022の変更内容をドキュメント化するものです。PR上では2026年5月5日に変更内容が説明され、GitHub上では2026年5月6日にrelease/13.3へマージされています。変更対象は、AIコーディングエージェントの導入ページとaspire agent initコマンドリファレンスの2ファイルです。(GitHub)
今回の.NET/Aspireドキュメント更新で変わったこと
今回の更新は、単なる文章修正ではありません。AIコーディングエージェントにAspireの扱い方を教える「skill file」の配置ルールと、aspire agent init実行時の選択手順が変わっています。
| 確認項目 | 変更内容 | 実務で見るべきポイント |
|---|---|---|
| 対話フロー | 配置先を選んでから、スキルやツールを選ぶ流れへ | 既存手順書のスクリーンショットや説明が古くなる |
| 標準配置先 | .agents/skills/がStandardとして追加 | VS Code、GitHub Copilot、OpenCode利用チームは優先確認 |
| 既存配置先 | .github/skills/、.claude/skills/、.opencode/skill/も整理 | 使っていないエージェント向けの重複配置を避ける |
| dotnet-inspect skill | .NET API surfaceを調べるスキルとして追加 | API名や型情報をAIに推測させず確認させたい場面で有効 |
| MCP設定 | Aspire MCP serverの設定も引き続き重要 | リソース状態、ログ、トレース確認はMCP側の役割 |
aspire agent initコマンドの説明では、スキルファイルとMCPサーバー設定を初期化し、対話的な複数ステップの流れでAIコーディングエージェントのサポートを構成するとされています。さらに、選択から外した配置先のskill fileは削除され、ワークスペースを整理できる点も明記されています。(GitHub)
aspire agent initは「配置先」と「中身」を分けて選ぶ
以前の理解では、aspire agent initは「どのコンポーネントを設定するか」をまとめて選ぶイメージでした。今回の更新後は、まずskill fileをどこに置くかを選び、その後でAspire skill、Playwright CLI、dotnet-inspect skillなど、何を入れるかを選ぶ流れになります。(GitHub)
基本の実行コマンドは変わりません。
aspire agent init実務上の違いは、コマンドを実行した後の判断にあります。たとえば、GitHub Copilotだけを使うチームなら.agents/skills/を中心に考え、Claude Codeも併用するなら.claude/skills/を追加するか検討します。OpenCodeを使っている場合は、標準配置先とOpenCode固有の配置先のどちらを使うかをチームで決めておくと、後からskill fileが散らばりにくくなります。
古い手順のままだと起きやすいズレ
古いドキュメントや社内手順のままだと、次のような問題が起きます。
| 起きやすい問題 | 原因 | 対応 |
|---|---|---|
.github/skills/だけ確認して、.agents/skills/を見落とす | Standard配置先の追加を知らない | git statusやファイル検索で4種類の配置先を確認する |
| AIエージェントごとに違うSKILL.mdを読んでしまう | 旧配置先と新配置先が混在する | どのエージェントでどの配置先を使うか決める |
dotnet-inspectを入れたのに使われない | エージェント側が対象skill fileを読めていない | 実際にエージェントへ「どのskillを認識しているか」を確認する |
| Aspire MCP serverとskill fileの役割を混同する | どちらもAI支援に関係するため | skill fileは手順や知識、MCPは実行中アプリの情報取得と整理する |
新しいskill file配置先の選び方
ドキュメント更新では、skill fileの配置先として4種類が整理されています。Standardの.agents/skills/はデフォルトで選択される配置先として扱われ、VS Code、GitHub Copilot、OpenCodeをサポートする場所として説明されています。(GitHub)
| 配置先 | ディレクトリ | 主な用途 | 判断基準 |
|---|---|---|---|
| Standard | .agents/skills/ | VS Code、GitHub Copilot、OpenCode向け | まず確認すべき標準配置先。複数エージェントで共有したい場合に向く |
| Claude Code | .claude/skills/ | Claude Code向け | Claude Codeを実際に使うチームだけ追加する |
| GitHub Skills | .github/skills/ | VS Code / GitHub Copilot向け | 既存運用やレガシー配置との互換性を確認する |
| OpenCode | .opencode/skill/ | OpenCode向け | OpenCode固有の運用をしている場合に確認する |
おすすめは、使っているエージェントに必要な配置先だけを残すことです。すべての配置先に同じ内容を置くと安心に見えますが、後から一部だけ更新されると、AIエージェントが古い指示を読んでしまう可能性があります。
チームでの現実的な方針
VS CodeとGitHub Copilotが中心なら、まず.agents/skills/を標準にします。すでに.github/skills/を使った運用がある場合は、すぐ削除せず、どちらを正とするかを決めてから整理します。
Claude Codeを使うメンバーがいるなら、.claude/skills/を別途残す価値があります。ただし、Standard配置先があるからClaude Code側も必ず読める、と決めつけないほうが安全です。ドキュメント上でもClaude Codeには専用配置先が示されています。(GitHub)
OpenCodeについては、Standardの.agents/skills/とOpenCode固有の.opencode/skill/の両方が示されています。プロジェクト全体で共通指示を管理したいならStandardを優先し、OpenCode向けに明確に分けたい場合のみ固有配置を使う、という運用が分かりやすいです。
dotnet-inspect skillで何ができるのか
dotnet-inspect skillは、AIエージェントが.NET API surfaceを確認するためのスキルとして追加されています。ドキュメントでは、NuGetパッケージのAPI surfaceを調べる、パッケージバージョン間のAPI変更を比較する、.NETの型やメンバーを探索するといった用途が説明されています。(GitHub)
これは、AIがメソッド名や型名を「それっぽく」推測して間違えるリスクを下げるために役立ちます。特に、Aspireや周辺パッケージはバージョンによってAPIが変わることがあります。AIにコード修正を任せる前に、現在のプロジェクトで実際に参照しているパッケージのAPIを確認させる流れを作ると、レビュー時の手戻りを減らせます。
たとえば、エージェントには次のように依頼できます。
このプロジェクトで参照しているAspire関連パッケージのAPIを確認してから、AppHostの修正案を出してください。
存在しないメソッド名を使わず、確認できた型とメンバーだけを使ってください。また、パッケージ更新前後の影響確認では、次のような依頼が実務的です。
現在のNuGetパッケージバージョンと更新候補のAPI surfaceを比較し、
既存のAppHostコードに影響しそうな変更点を一覧化してください。Aspire skillとの併用は慎重に判断する
注意したいのは、dotnet-inspect skillを無条件にAspire skillと一緒に入れればよい、とは言い切れない点です。更新後のファイルには、dotnet-inspect skillは各選択先にインストールされると説明される一方で、Aspire skillにはC#とTypeScriptのAspire APIを問い合わせるaspire docs apiサブコマンドのサポートが含まれるため、dotnet-inspect skillをAspire skillと同時に入れるべきではない、という注意書きも追加されています。(GitHub)
実務では、次のように使い分けるのが安全です。
| 目的 | 優先するもの | 理由 |
|---|---|---|
| Aspireの使い方、CLI操作、AppHostの作業手順をAIに理解させたい | Aspire skill | Aspire CLI、MCP、ログ、トレース、ドキュメント検索の流れを教えられる |
| Aspire APIを確認したい | Aspire skill内のaspire docs api系の案内を優先 | Aspire固有のC# / TypeScript API確認に向く |
| 一般的な.NETパッケージのAPI surfaceを確認したい | dotnet-inspect skill | NuGetパッケージ、型、メンバー確認に向く |
| AIが複数の指示で混乱している | 片方を外して再実行 | 重複するskill fileは指示衝突の原因になる |
影響を受ける人とプロジェクト
今回の.NET documentation updateは、Aspireを使うすべての開発者に即時対応を求めるものではありません。影響が大きいのは、AIコーディングエージェントとAspire CLIを組み合わせているチームです。
| 対象 | 影響度 | 対応すべきこと |
|---|---|---|
aspire agent initを使っている開発者 | 高 | 新しい対話フローと配置先を確認する |
| GitHub Copilot / VS CodeでAspire開発をしているチーム | 高 | .agents/skills/を標準配置先として扱うか決める |
| Claude Codeを併用しているチーム | 中〜高 | .claude/skills/が必要か確認する |
| OpenCodeを使うチーム | 中 | .agents/skills/と.opencode/skill/の運用を決める |
| AGENTS.mdを過去に導入したプロジェクト | 中 | SKILL.mdとの重複を整理する |
| CIやテンプレートで初期設定を自動化しているチーム | 中 | 対話フロー変更によりスクリプトが古くなっていないか確認する |
| AIエージェントを使っていないAspireプロジェクト | 低 | すぐの変更は不要。ただし将来導入時の標準として把握しておく |
特に、リポジトリテンプレートや社内スターターキットで.github/skills/aspire/SKILL.mdだけを前提にしている場合は見直しが必要です。今後は.agents/skills/aspire/SKILL.mdが標準配置先として扱われるため、古い配置先だけをコピーするテンプレートは、エージェントによって期待通りに読まれない可能性があります。
既存プロジェクトでの移行・設定確認手順
既存プロジェクトでは、いきなり古いskill fileを削除せず、まず現在の状態を確認します。変更前後の差分が分かるように、作業前にGitの状態をきれいにしておくのが安全です。
現在の状態を確認する
git status --short
aspire --version
aspire agent init --helpaspire agent init --helpは、手元のCLIがどのオプションや説明を出しているかを確認するために使います。ドキュメント更新とCLIの反映タイミングには差が出ることがあります。実際、daily buildではaspire agent init --skills dotnet-inspectが未認識になるという報告もありました。これは、バージョンやチャンネルによって挙動がずれる可能性を確認する材料になります。(GitHub)
aspire agent initを再実行する
プロジェクトルート、つまりAppHostがあるディレクトリで実行します。
aspire agent init実行後は、次の観点で選択します。
| 選択項目 | 判断 |
|---|---|
Standard .agents/skills/ | まず選択候補にする。VS Code、GitHub Copilot、OpenCode中心なら特に重要 |
Claude Code .claude/skills/ | Claude Codeを使っている場合に選択 |
GitHub Skills .github/skills/ | 既存のGitHub Copilot向け運用がある場合に確認 |
OpenCode .opencode/skill/ | OpenCode専用の配置を明示したい場合に選択 |
| Aspire skill | Aspire CLI、AppHost、MCP連携をAIに扱わせるなら選択 |
| Playwright CLI | AIにブラウザ操作やWebリソースのテストをさせたい場合に選択 |
| dotnet-inspect skill | .NET API surface確認をAIにさせたい場合に選択。ただしAspire skillとの重複に注意 |
生成・更新されたファイルを確認する
macOS/Linuxでは、次のようにskill fileの配置を確認できます。
find . -type f \( \
-path "*/.agents/skills/*" -o \
-path "*/.github/skills/*" -o \
-path "*/.claude/skills/*" -o \
-path "*/.opencode/skill/*" \
\)Windows PowerShellでは、次のように確認できます。
Get-ChildItem -Recurse -Force -File |
Where-Object {
$_.FullName -match '\\\.agents\\skills\\' -or
$_.FullName -match '\\\.github\\skills\\' -or
$_.FullName -match '\\\.claude\\skills\\' -or
$_.FullName -match '\\\.opencode\\skill\\'
} |
Select-Object FullName確認すべきファイル例は次のとおりです。
.agents/skills/aspire/SKILL.md
.agents/skills/dotnet-inspect/SKILL.md
.github/skills/aspire/SKILL.md
.claude/skills/aspire/SKILL.md
.opencode/skill/aspire/SKILL.mdPRの更新後ファイルでは、Aspire skillとdotnet-inspect skillの配置例として、これらの各ディレクトリが示されています。(GitHub)
古い配置先を整理する
重要なのは、AIが読む指示を1つに揃えることです。たとえば、.github/skills/aspire/SKILL.mdと.agents/skills/aspire/SKILL.mdの内容が違うと、使うエージェントによって回答や操作が変わる可能性があります。
整理の手順は次の流れが安全です。
| 手順 | 作業 | 判断基準 |
|---|---|---|
| 1 | すべてのskill fileを一覧化 | どの配置先が残っているか確認 |
| 2 | 内容を比較 | 古いCLIコマンド、古いAppHost前提、重複ルールがないか見る |
| 3 | チームの標準配置先を決める | 原則は.agents/skills/を軸にする |
| 4 | 使わない配置先を外す | aspire agent initの選択解除で整理できるか確認 |
| 5 | AIエージェントで読み込み確認 | 「認識しているskillを教えて」と聞く |
aspire agent initの更新後説明では、選択から外したskill fileは削除されるとされています。手動削除だけに頼るより、まず新しいフローで選択状態を整えるほうが安全です。(GitHub)
AGENTS.mdを使っている場合の見直し
過去のAspireドキュメントでは、AGENTS.mdから新しいskill file形式へ移行する案内がありました。skill fileは、AIコーディングエージェントが認識しやすい構造で、CLIコマンド、ワークフロー、守るべきルールを含む形式として説明されています。(Aspire)
既存のAGENTS.mdがある場合は、すぐに削除するのではなく、次の順番で整理します。
AGENTS.mdに書かれているプロジェクト固有ルールを確認する- 新しく生成された
SKILL.mdと内容を比較する - Aspireの一般的な操作ルールは
SKILL.mdへ寄せる - プロジェクト固有の注意点だけを残すか、
SKILL.mdに統合する - AIエージェントが両方を読んで矛盾しないか確認する
たとえば、AGENTS.mdに「dotnet runで起動する」と書かれ、SKILL.mdに「Aspireではaspire startやaspire describeを使う」と書かれていると、エージェントが古い起動方法を選ぶ可能性があります。こうした矛盾は、AIの出力品質に直接影響します。
dotnet-inspect skillを入れるべきケース、入れないほうがよいケース
dotnet-inspect skillは便利ですが、すべてのAspireプロジェクトで必須ではありません。導入判断は、AIに何を任せるかで決めるべきです。
| ケース | 導入判断 | 理由 |
|---|---|---|
| AIにNuGetパッケージのAPI確認を任せたい | 入れる価値が高い | 型やメソッドを確認してからコード提案できる |
| Aspire AppHostの基本操作だけを任せたい | Aspire skill中心でよい | CLI、MCP、ログ、トレースの使い方が重要 |
| チームがAIにコード生成をあまり任せない | 優先度は低い | skill fileが増えるほど管理対象も増える |
| エージェントが指示を混同している | いったん外す | Aspire skillとの役割重複に注意が必要 |
| バージョン差分の影響調査をしたい | 入れる価値がある | API surface比較に向く |
独自の判断基準としては、AIに「調べてから書く」行動をさせたいならdotnet-inspect、AIに「Aspireとして正しく操作する」行動をさせたいならAspire skillと考えると分かりやすいです。
設定時に失敗しやすいポイント
| 失敗しやすいポイント | 何が問題か | 回避策 |
|---|---|---|
| すべての配置先にskill fileを置く | 内容が分岐し、古い指示が残りやすい | 実際に使うエージェントの配置先だけ選ぶ |
.agents/skills/だけでClaude Codeも大丈夫と判断する | ドキュメント上はClaude Code専用配置先も示されている | Claude Code利用者に実際の読み込みを確認してもらう |
dotnet-inspectをランタイム診断用だと誤解する | API確認と実行中アプリの観測は別物 | ランタイム情報はAspire MCP server、ログ、トレースを使う |
既存の.github/skills/を放置する | 新旧のSKILL.mdが競合する | 内容比較後、標準配置先へ寄せる |
| CLIのdaily buildやプレビュー挙動を本番手順に書く | バージョン差でコマンドが動かない可能性がある | aspire --versionとaspire agent init --helpを手順に入れる |
| skill fileにローカルパスや秘密情報を書く | チーム共有時に漏えい・環境差の原因になる | 共有するSKILL.mdには汎用ルールだけを書く |
特に注意したいのは、dotnet-inspect skillを「入れればAIが必ず正確になる」と過信することです。API surfaceを確認できても、プロジェクトの設計意図やセキュリティ要件までは自動で理解できません。重要な変更は、AIの提案をそのまま採用せず、AppHost、依存パッケージ、起動ログ、テスト結果をセットで確認する必要があります。
チームで決めておくと運用が安定するルール
今回の変更をきっかけに、AIエージェント向けの設定ルールをチームで明文化しておくと、今後のAspireアップデートにも対応しやすくなります。
おすすめのルールは次の5つです。
| ルール | 具体例 |
|---|---|
| 標準配置先を決める | 原則は.agents/skills/を使い、必要な場合だけ専用配置を追加する |
| 使うエージェントを明記する | READMEに「VS Code + GitHub Copilot」「Claude Code」などを記載する |
| skill file更新をレビュー対象にする | SKILL.mdの変更は通常のコードレビューに含める |
| 重複指示を避ける | AGENTS.md、.github/skills/、.agents/skills/の内容を揃える |
| バージョン確認を手順化する | aspire --versionとaspire agent init --helpを初期設定手順に入れる |
AIエージェントの設定は、一度作って終わりではありません。Aspire CLIやAIツール側の対応範囲が変わると、最適な配置先やskill fileの内容も変わります。特に、チームのテンプレートリポジトリを管理している場合は、今回のようなドキュメント更新をきっかけに、生成ファイルと社内手順の両方を見直すべきです。
まず何をすべきか
今回の.NET documentation updateで対応すべきことは、次の4つに絞れます。
- Aspireプロジェクトで
aspire agent initを再実行し、新しい対話フローを確認する .agents/skills/、.github/skills/、.claude/skills/、.opencode/skill/のどれを使うか決める- Aspire skillと
dotnet-inspectskillの役割を分け、重複指示を避ける - 既存の
AGENTS.mdや古いSKILL.mdがある場合は、内容を比較して整理する
最も重要なのは、AIエージェントが読む情報を最新かつ一貫した状態にすることです。Aspireでは、AIエージェントがAppHost、CLI、MCP server、ログ、トレースを活用できるようになっています。だからこそ、初期設定のskill fileが古いままだと、AIの提案も古い前提に引きずられます。今日できる実務対応としては、まず対象リポジトリでaspire agent initを実行し、生成されたskill fileの配置と内容をレビューするところから始めるのが確実です。
コメント