Skills のベストプラクティスと具体例（C# / ASP.NET Core 想定）

Cursor の Agent Skills は、手順が長い・段階がある・チームで共有したいワークフローをファイル化する仕組み。.cursor/skills/<name>/SKILL.md に置く。

この記事では、書き方のベストプラクティスと、C# / ASP.NET Core 想定の具体例をまとめる。例として AGENTS.md 記事と同じ架空プロダクト OrderNest（受注 API + バックグラウンド処理）を使う。

関連: Agent 設定フォルダ構成 / ローカル vs クラウドエージェント

先に結論

Skills = 手順・ワークフロー。常時効かせたい短い規約は AGENTS.md や .cursor/rules へ
1 Skill 1 テーマ。SKILL.md の frontmatter に name と description（いつ使うか）を書く
本文は When to Use と Instructions を中心に、実行可能なステップで書く
詳細資料は references/、実行物は scripts/ に逃がして本体を短く保つ
Cloud Agent では ~/.cursor/skills/ は使えない。リポジトリの .cursor/skills/ にコミットする

Skills とは

Agent Skills は、エージェントに「このタスクではこう進めて」と教えるポータブルな手順パッケージ。Open 標準として SKILL.md + 任意の scripts/ / references/ / assets/ で構成される。

Cursor 起動時に .cursor/skills/（ほか .agents/skills/ 等）から自動検出され、Agent が文脈に応じて読み込む。チャットで /skill-name と打てば明示的に呼び出せる。

AGENTS.md / Rules / Skills の使い分け

AGENTS.md … プロジェクトの地図・ビルドコマンド・不変条件（常に読ませたい文脈）
.cursor/rules/*.mdc … パス glob 付きの短い規約（「この層ではこう書け」）
Skills … 多段階の手順、調査フロー、リリース手順、Cloud 検証などステップが続くもの

目安: 「何のリポジトリ？」→ AGENTS.md。「このファイル種別の書き方」→ rules。「障害調査の 1〜5 手順」→ Skills。

ベストプラクティス

SKILL.md の型

---
name: my-skill
description: 何をする Skill か。Agent が「いつ使うか」を判断する短文。
paths:                          # 任意。glob でファイルにスコープ
  - "src/Infrastructure/**"
---

# My Skill

## When to Use
- ユーザーが ○○ と言ったとき
- マイグレーション追加・ロールバックを依頼されたとき

## Instructions
1. まず ○○ を確認
2. 次に △△ を実行
3. 完了前に □□ で検証

書くと効くもの

description に「何をするか」と「いつ使うか」を両方入れる（Agent の自動選択に効く）
番号付きステップ。各ステップに完了条件を書く
実行コマンドはコピペ可能な形で（dotnet test ... など）
参照すべき既存ファイルをパスで示す（全文コピーしない）
長い説明は references/ に分離し、必要時だけ読ませる

避けた方がいいもの

AGENTS.md と同じ内容の二重管理
一般論だけ（「きれいに」「適切に」）で実行手順がない
1 ファイルに unrelated な手順を詰め込む（Skill を分割する）
すぐ陳腐化するコード全文の貼り付け
スラッシュコマンド専用にしたいのに disable-model-invocation を付け忘れる

frontmatter の要点

name … フォルダ名と一致。小文字・ハイフンのみ
description … 必須。自動選択のキー
paths … 特定ディレクトリだけで効かせたいとき（例: Infrastructure 専用 Skill）
disable-model-invocation: true … 明示的 /skill-name 呼び出し専用（旧 slash command 相当）

想定プロダクト: OrderNest

以降の例で使う架空プロダクト（AGENTS.md 記事と同じ）。

内容: B2B 受注の Web API + 非同期ワーカー
スタック: .NET 8 / ASP.NET Core / EF Core / SQL Server
構成: Api / Application / Domain / Infrastructure / Workers

OrderNest/
├── AGENTS.md
├── .cursor/
│   └── skills/
│       ├── ef-migration/
│       │   ├── SKILL.md
│       │   └── references/
│       │       └── rollback-checklist.md
│       ├── api-integration-test/
│       │   ├── SKILL.md
│       │   └── scripts/
│       │       └── run-api-tests.sh
│       └── cloud-verify/
│           └── SKILL.md
└── src/ ...

具体例 1: EF Core マイグレーション Skill

スキーマ変更依頼が来たとき、Agent が毎回迷わないようにする例。

---
name: ef-migration
description: OrderNest で EF Core マイグレーションを追加・更新・ロールバックするとき。スキーマ変更、Migration 追加、dotnet ef 操作の依頼で使う。
paths:
  - "src/Infrastructure/**"
  - "src/Domain/**"
---

# EF Core Migration (OrderNest)

## When to Use
- エンティティ変更に伴うマイグレーション追加
- マイグレーション失敗後の切り分け
- ロールバック方針の確認

## Instructions

1. **変更の意図を確認**
   - 破壊的変更（列削除・型変更）かどうか
   - 本番データ量・ダウンタイム許容

2. **エンティティと設定を先に直す**
   - 変更は `src/Domain` と `src/Infrastructure/Persistence/Configurations`
   - Domain に EF 依存を入れない

3. **マイグレーション生成**
   - `dotnet ef migrations add <Name> --project src/Infrastructure --startup-project src/Api`
   - 生成された Up/Down を目視。意図しない Drop がないか

4. **ローカル適用**
   - `dotnet ef database update --project src/Infrastructure --startup-project src/Api`
   - 失敗したらログを読み、接続先が開発 DB か確認

5. **テスト**
   - `dotnet test tests/Application.Tests`
   - 統合テスト利用可なら `dotnet test tests/Api.Tests`

6. **PR に書くこと**
   - 変更理由、ロールバック手順（`dotnet ef database update <PreviousMigration>`）
   - 本番適用時の注意（ロック・時間帯）

## References
- 詳細チェックリスト: `references/rollback-checklist.md`

## Do not
- 手動で Migration ファイルだけ編集して整合を崩す
- 接続文字列を Skill やログに書かない

具体例 2: API 統合テスト Skill

Testcontainers を使う統合テストは手順が長いので Skill 向き。

---
name: api-integration-test
description: OrderNest の API 統合テストを追加・実行・デバッグするとき。Testcontainers、Api.Tests、HTTP エンドポイント検証の依頼で使う。
paths:
  - "tests/Api.Tests/**"
  - "src/Api/**"
---

# API Integration Test (OrderNest)

## When to Use
- 新規エンドポイントの統合テスト追加
- CI / ローカルで Api.Tests が落ちたとき
- Docker 前提のテスト環境の確認

## Instructions

1. **前提確認**
   - Docker が起動していること
   - `dotnet --version` が .NET 8 系

2. **既存パターンをコピー**
   - `tests/Api.Tests/Orders/` 配下の Factory + WebApplicationFactory 構成を真似る
   - 認証は既存の `TestAuthHandler` を使う

3. **テスト追加の型**
   - Arrange: DB シードは `Infrastructure` のテスト用拡張を利用
   - Act: `HttpClient` で実 HTTP
   - Assert: ステータス + ProblemDetails + 必要なら DB 状態

4. **実行**
   - 全体: `dotnet test tests/Api.Tests`
   - 単体: `dotnet test tests/Api.Tests --filter "FullyQualifiedName~OrdersCreate"`
   - または `scripts/run-api-tests.sh`

5. **失敗時**
   - コンテナ起動ログ → ポート競合 → マイグレーション未適用の順で見る
   - Application.Tests は通るが Api.Tests だけ落ちるなら Docker / 起動順を疑う

## Scripts
- `scripts/run-api-tests.sh` … ログ付きで Api.Tests を実行

## Do not
- 本番 DB 接続文字列でテストを書かない
- テスト内で `Thread.Sleep` で待たない（Eventually / リトライヘルパーを使う）

具体例 3: Cloud Agent 検証 Skill

Cloud では VM ごとに環境が異なる。完了前に何を実行するかを Skill に固定する例。

---
name: cloud-verify
description: OrderNest を Cloud Agent で変更したあと、マージ前に実行する検証手順。Cloud、PR 完了前、environment.json があるリポジトリで使う。
disable-model-invocation: false
---

# Cloud Verify (OrderNest)

## When to Use
- Cloud Agent がコード変更を終えた直後
- ユーザーが「動くか確認して」と言ったとき
- `.cursor/environment.json` があるプロジェクト

## Instructions

1. **環境を読む**
   - ルート `AGENTS.md` の `Cursor Cloud specific instructions`
   - `.cursor/environment.json` の install / start / terminals

2. **依存関係**
   - `dotnet restore OrderNest.sln`
   - 失敗したら package 源・SDK バージョンを報告

3. **ビルド**
   - `dotnet build OrderNest.sln -c Release --no-restore`
   - 警告は既存分と新規分を分けて報告

4. **テスト（段階的）**
   - 必須: `dotnet test tests/Application.Tests --no-build`
   - Docker 利用可: `dotnet test tests/Api.Tests --no-build`
   - Docker 不可: Application.Tests のみ実行し、Api.Tests スキップ理由を明記

5. **報告フォーマット**
   - 実行したコマンド一覧
   - 成功 / 失敗
   - スキップした検証と理由
   - 未実行の手動確認（あれば）

## Notes
- VPN / 社内専用リソースには触れない
- 秘密情報をログや PR コメントに出さない
- 長いリリース手順は別 Skill に分離し、ここは「マージ前の最低限」に留める

フォルダ構成とスコープ

置き場所

プロジェクト: .cursor/skills/ または .agents/skills/（チーム共有・Cloud 向け）
ユーザー全体: ~/.cursor/skills/（ローカル専用。Cloud では基本不可）
モノレポ: apps/web/.cursor/skills/ のようにサブツリーに置ける（その配下の作業時だけ効く）

paths で絞る vs ネストで絞る

paths frontmatter … 同じ Skill フォルダを glob でファイル種別に限定
サブディレクトリの .cursor/skills/ … そのディレクトリ配下の作業時だけ自動スコープ
どちらも「関係ないファイルを触るときに Skill を読ませない」ための手段

scripts / references / assets

scripts/ … Agent が実行するシェル・スクリプト（自己完結・エラーメッセージ付き）
references/ … 長いチェックリスト・Runbook（必要時だけ読み込み）
assets/ … テンプレ JSON など静的ファイル

Rules から Skills へ移すタイミング

手順が 5 ステップを超え、rules が読みにくくなった
同じ調査フローを毎回 Agent に口述している
スクリプト実行を含む（rules より Skills が向く）
旧 slash command を残している（/migrate-to-skills で変換可能）

逆に、常に効かせたい 1〜2 行の規約は rules のまま。Skills にすると自動選択が外れることがある。

よくある失敗

AGENTS.md に手順を書き続けて肥大化 → Skills に分割すべきだった
description が曖昧で Agent が Skill を選ばない → 「いつ使うか」を具体語で
ホーム配下だけに Skill があり Cloud で使えない → リポジトリへ移す
コマンドが古い → CI と同じコマンドをメンテする
1 Skill にマイグレーション + リリース + 障害対応 → 分割して自動選択精度を上げる

ざっくりまとめ

Skills = 段階的ワークフローの置き場（SKILL.md）
必須: name / description、本文の When to Use と Instructions
AGENTS.md は地図、rules は短い規約、Skills は長い手順
C# では EF 操作・統合テスト・Cloud 検証が Skill 化しやすい
チーム / Cloud 共有は .cursor/skills/ にコミット

まずは「毎回同じ口癖で Agent に頼んでいる手順」を 1 つ Skill にするのがおすすめ。OrderNest なら ef-migration か cloud-verify からで十分。

公式: Agent Skills ドキュメント