GitHub Copilot 現代化是可擴充的。 代理程式提供多個自訂點，以編碼團隊的升級模式、在升級過程中執行編碼標準，並定義新的升級工作流程。
自訂點數概覽
| 客製化點 | Scope | 持續性 | 努力 |
|---|---|---|---|
| 聊天指示 | 每次會話或升級 | 會話已儲存至 scenario-instructions.md |
最小 |
| 情境產物 | 每次升級 | 升級期限 | 低 |
| 自訂技能 | 團隊或個人 | 永久（已登錄到倉庫或使用者設定檔） | 中等 |
| 自訂劇本 | 團隊或個人 | 持續性 | 高 |
小提示
先從聊天指令和劇本文稿編輯開始。 當你發現自己在升級過程中重複相同指示時，應考慮切換至自訂技能。
透過聊天自訂
透過自然對話即時客製化客服的行為。 代理人要麼立即套用你的指示，要麼將其保存至 scenario-instructions.md 以供未來參考。
| 你說 | 會發生什麼事 |
|---|---|
| 「從現在開始，每完成一項任務後就提交」 | 作為執行偏好儲存到scenario-instructions.md |
| 「跳過此任務的測試驗證」 | 僅立即套用到目前的任務 |
| 「這次升級用自下而上的策略」 | 影響規劃階段策略 |
| 「別碰伐木計畫」 | 新增偏好設定;代理人排除該專案 |
| 「務必使用檔案範圍命名空間」 | 儲存為編碼標準偏好 |
| 「每完成一項任務後暫停，讓我檢視一下。」 | 儲存為執行風格偏好 |
小提示
要讓指令在整個升級過程中持續存在，可以將其描述為永久偏好：「從現在起，永遠......」或「對於本次升級中的所有任務......」。 代理將指令寫入 scenario-instructions.md。
編輯場景構件
當代理執行升級時，會在.github/upgrades/{scenarioId}/中建立一個工作空間。 升級資料夾包含可編輯的產物，直接控制代理的行為。
scenario-instructions.md
該 scenario-instructions.md 檔案是代理程式升級時的持久記憶體。 代理人總是會將這個檔案載入上下文，所以你在這裡寫的任何東西，都會直接影響代理人做的每一個決策。
新增以下段落以引導經紀人：
## User Preferences
### Technical Preferences
- Always prefer explicit type declarations over `var`
- Use `ILogger<T>` instead of `ILoggerFactory` for dependency injection
- Target .NET 10 for all projects
- Keep Newtonsoft.Json in the shared library (don't migrate to System.Text.Json)
### Execution Style
- **Pace**: Methodical
- **Pause Points**: After assessment, after each task group
### Custom Instructions
#### 02-common-lib
- Skip the database migration for now — it has external dependencies
- Use the connection string from `appsettings.Production.json` for testing
#### 03-data-layer
- Keep existing repository interfaces during migration
- Preserve all Entity Framework conventions
## Key Decisions Log
- 2025-01-15: Keep Newtonsoft.Json in SharedLib — third-party SDK requires it
- 2025-01-16: Skip database project — DBA team will handle separately
plan.md
文件 plan.md 檔案規定了任務及其範圍。 編輯 plan.md ：
- 重新排序任務以改變執行序列。
- 新增代理未計劃的任務。
- 移除不適用的任務。
- 補充筆記，為特定任務提供背景說明。
個別任務檔案
每個任務 tasks/{taskId}/task.md 包含任務規格與工作筆記。 將這些檔案編輯為：
- 精細化任務範圍。
- 加入客服忽略的領域特定背景。
- 提供期望結果的程式碼範例。
這很重要
代理工具則將 tasks.md 管理為唯讀儀表板。 不要直接編輯 tasks.md 。 代理程式會覆寫任何手動變更。 請改為編輯scenario-instructions.md檔案或task.md個別檔案。
創建自訂技能
技能是代理人的主要延伸點。 技能是一個帶有元資料標頭的 Markdown 檔案，用來教導代理如何處理特定的升級、模式或任務。
自訂技能該放置在哪裡
| 地點 | Scope | 何時使用 |
|---|---|---|
.github/skills/my-skill.md |
儲存庫（與團隊共享） | 全隊升級模式 |
.github/upgrades/skills/my-skill.md |
儲存庫（升級專用） | 針對升級場景的專屬技能 |
%UserProfile%/.copilot/skills/my-skill.md |
使用者檔案（個人，所有儲存庫） | 個人偏好與模式 |
小提示
倉庫層級技能（.github/skills/）是最常見的選擇。 他們帶著密碼旅行，整個團隊都能使用。
技能檔案結構
每個技能檔案包含兩部分：一個元資料標頭（代理人用來了解技能何時適用）以及一個 Markdown 主體（代理人遵循的指令）。
---
name: migrating-foobar-v2-to-v3
description: >
Migrate our internal FooBar library from v2 to v3. Activates when
FooBar.v2 NuGet package is detected, or when asked to "upgrade FooBar",
"migrate FooBar", or "update FooBar library".
metadata:
discovery: lazy
traits: .NET | CSharp
---
# Migrating FooBar Library v2 to v3
## Overview
FooBar v3 introduces a new async-first API surface. This skill guides the
agent through replacing synchronous FooBar.v2 calls with their v3 async
equivalents, updating configuration, and verifying behavior.
## Workflow
1. **Identify FooBar.v2 references**
- Search for `PackageReference` elements referencing `FooBar.v2`
- Locate all `using FooBar.V2;` directives
2. **Update package references**
- Replace `FooBar.v2` with `FooBar.v3` in all `.csproj` files
- Run `dotnet restore` to verify resolution
3. **Migrate API calls**
- Replace `FooBarClient.Send(...)` with `await FooBarClient.SendAsync(...)`
- Replace `FooBarConfig.LoadFromFile(...)` with `FooBarConfig.LoadFromJsonAsync(...)`
- Update method signatures to `async Task` where needed
4. **Update configuration**
- Rename `foobar.config` to `foobar.json`
- Migrate XML config entries to JSON format
5. **Verify**
- Build the project: `dotnet build`
- Run existing tests: `dotnet test`
- Verify no remaining references to `FooBar.V2` namespace
## Success Criteria
- [ ] No references to `FooBar.v2` NuGet package remain
- [ ] All `FooBar.V2` namespace usages replaced with `FooBar.V3`
- [ ] Project builds without errors
- [ ] All existing tests pass
## Error Handling
- If `FooBar.v3` is not available in the configured NuGet feeds, instruct
the user to add the internal feed
- If async migration causes deadlocks in legacy synchronous code paths,
wrap calls with `.GetAwaiter().GetResult()` and add a TODO comment
中繼資料欄位
| 領域 | Required | 說明 |
|---|---|---|
name |
是的 | 烤肉盒中的唯一識別碼。 以動名詞開頭（例如， upgrading-， converting-）。 最多64字元。 |
description |
是的 | 決定代理人何時載入該技能。 加入觸發詞語，例如能啟動技能的詞語和模式。 |
metadata.discovery |
No | 技能載入時的控制： preload （隨時可用）、 lazy （描述符合時按需，預設且推薦）、或 scenario （定義工作流程協調器）。 |
metadata.traits |
No | 描述你專案中技術的關鍵詞，例如 .NET、CSharp、VisualBasic 或 DotNetCore。 |
技能開發最佳實務
- 描述要具體： 請包含精確的套件名稱、函式庫名稱，以及使用者可能輸入的自然語言觸發詞。
- 包含明確且逐步的工作流程： 步驟數。 要明確說明要更改哪些檔案、執行哪些指令。
- 包含成功標準： 沒有成功標準，代理人就不知道什麼時候該停下來。 使用勾選框或明確列出可驗證的條件。
- 包含錯誤處理： 預見常見的失敗模式，例如遺失的套件、建置失敗或測試失效。
- 保持技能專注： 每個升級或任務類型只能選一個技能。 一個「將 FooBar v2 升級到 v3」的技能，比「升級所有內部函式庫」要好。
-
帶有動名詞的名字： 請使用
upgrading-foobar-v2-to-v3，而不是foobar-upgrade或foobar-v3。 -
使用
lazy發現功能： 大多數自訂技能都使用lazy發現功能，以避免讓代理的上下文視窗過大。
建立自訂情境
對於想要定義全新升級工作流程的進階使用者，自訂情境可以讓你協調完整的多階段升級流程。 情境是一種 metadata.discovery: scenario 技能，定義了代理人所遵循的階段。
---
name: migrating-soap-to-rest-api
description: >
Migrate legacy WCF/SOAP services to ASP.NET Core REST APIs. Activates
when WCF service references, .svc files, or SOAP clients are detected,
or when asked to "migrate SOAP to REST", "replace WCF", or "convert
web services to REST".
metadata:
discovery: scenario
traits: .NET | CSharp
scenarioTraitsSet: [wcf, soap, web-services]
---
# SOAP to REST API Migration
## Pre-initialization
Gather from the user:
- Which SOAP services to migrate (all or specific ones)
- Whether to maintain backward compatibility with a SOAP facade
- Authentication mechanism for the new REST APIs
- API versioning strategy (URL path, header, query string)
## Assessment
Analyze the solution for:
- `.svc` files and WCF service contracts
- WSDL files and service references
- `System.ServiceModel` usage and binding configurations
- Data contracts and their serialization requirements
- Client proxies consuming SOAP services
## Planning
Create tasks in this order:
1. Create shared DTOs — Convert `[DataContract]` types to POCOs
2. Create REST controllers — One controller per `[ServiceContract]`
3. Map operations to HTTP methods
4. Migrate service implementations
5. Update clients — Replace `ChannelFactory`/generated proxies with `HttpClient`
6. Remove WCF infrastructure
7. Add API documentation — Swagger/OpenAPI via Swashbuckle
## Execution
For each service contract:
1. Create a corresponding controller
2. Create a service interface and implementation
3. Register the service in DI
4. Map WCF operations to REST endpoints
5. Update any in-solution clients to use the new REST endpoints
6. Build and run existing tests
將情境檔案放入 .github/skills/ 或 .github/upgrades/skills/ 讓客服自行發現。
小提示
這個 scenarioTraitsSet 欄位定義了代理人用來將你的情境與解決方案特性匹配的特徵。 這些特質有助於代理人在適當時機提出你的情境建議。
原始碼控制與分支
代理人提出要在 Git 分支工作，但策略完全由你掌控：
- 分支命名： 告訴經紀人該用哪個分支名稱，或讓代理人建議。
- 每個任務分支： 請為每個任務申請獨立分支以進行細緻審查。
- 提交時機： 選擇代理何時提交：完成每個任務後（預設）、僅在完整升級結束時，或按需提交。
- 沒有來源控制： 代理程式也能支援非 Git 資料夾，但建議先備份專案。
聊天指令範例：
- 「使用此分支名稱 'upgrade/dotnet10' 來進行此升級」
- 「為每個任務建立一個分支，這樣我才能分別檢視每個任務。」
- 「除非我明確要求，否則別答應。」
- 「每完成一項任務後，提交一段描述性訊息」
小提示
對於大型多專案升級，每個任務的分支讓你可以獨立檢視並合併各項變更，或回滾單一任務而不會影響其他任務。
技能載入優先權
當代理人發現多項技能時，會用優先順序系統解決。 高優先權來源會覆蓋或補充低優先權來源：
| Priority | 來源 | 地點 |
|---|---|---|
| 5（最高） | 自訂技能（使用者透過 API 提供） | — |
| 4 | 使用者個人資料技能 | %UserProfile%/.copilot/skills/ |
| 3 | 儲存庫升級技術 | .github/upgrades/skills/ |
| 2 | 儲存庫管理技能 | .github/skills/ |
| 1（最低） | 嵌入技能（內建於代理中） | — |
代理人從所有來源收集技能。 當技能範圍重疊時，優先權較高的來源會優先。
discovery欄位控制技能載入的時間。
lazy 指的是按需供應，當需要時，preload 指的是始終可用。
小提示
你不需要替換一個內建的技能來改變行為。 較高優先度的儲存庫技能補充了內建技能，將團隊特定的慣例加入基線行為之上。
