Personalizar la modernización de GitHub Copilot

La modernización de GitHub Copilot es ampliable. El agente proporciona varios puntos de personalización para codificar los patrones de actualización del equipo, aplicar estándares de codificación durante las actualizaciones y definir nuevos flujos de trabajo de actualización.

Información general sobre puntos de personalización

Punto de personalización Ámbito Persistencia Effort
Instrucciones de chat Por sesión o actualización Sesión o guardado en scenario-instructions.md Mínimo
Artefactos de escenario Por cada actualización Duración de la actualización Low
Aptitudes personalizadas Equipo o personal Permanente (incorporado en un repositorio o en el perfil de usuario) Medio
Escenarios personalizados Equipo o personal Permanente Alto

Sugerencia

Comience con instrucciones de chat y modificaciones de artefactos de escenario. Pasa a habilidades personalizadas cuando se encuentre repitiendo las mismas instrucciones entre mejoras.

Personalizar a través del chat

Personalice el comportamiento del agente en tiempo real a través de una conversación natural. El agente aplica la instrucción inmediatamente o la guarda en scenario-instructions.md como referencia futura.

Dice usted ¿Qué ocurre?
"Desde ahora, confirme siempre después de cada tarea" Guardado en scenario-instructions.md como preferencia de ejecución
"Omitir la validación de pruebas para esta tarea" Solo aplicado inmediatamente a la tarea actual
"Utilizar la estrategia de abajo hacia arriba para esta actualización" Afecta a la estrategia en la fase de planificación
"No toque el proyecto de Logging" Añadido a las preferencias; el agente excluye ese proyecto
"Siempre usar espacios de nombres con alcance de archivo" Guardado como preferencia estándar de codificación
"Pausar después de cada tarea para mi revisión" Guardado como preferencia de estilo de ejecución

Sugerencia

Para que una instrucción persista en toda la actualización, escríbala como una preferencia permanente: "Desde ahora, siempre..." o "Para todas las tareas de esta actualización...". El agente escribe la instrucción en scenario-instructions.md.

Edición de artefactos de escenario

Cuando el agente ejecuta una actualización, crea un área de trabajo en .github/upgrades/{scenarioId}/. La carpeta de actualización contiene artefactos editables que controlan directamente el comportamiento del agente.

scenario-instructions.md

El scenario-instructions.md archivo es la memoria persistente del agente para la actualización. El agente siempre carga este archivo en contexto, por lo que cualquier cosa que escriba aquí influye directamente en cada decisión que tome el agente.

Agregue secciones como estas para guiar al agente:

## 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

El plan.md archivo define las tareas y su ámbito. Editar plan.md en:

  • Reordenar las tareas para cambiar la secuencia de ejecución.
  • Agregue tareas que el agente no había planificado.
  • Quite las tareas que no se aplican.
  • Agregue notas para proporcionar contexto para tareas específicas.

Archivos de tareas individuales

Cada tarea de tasks/{taskId}/task.md contiene la especificación de la tarea y las notas de trabajo. Edite estos archivos para:

  • Refinar el ámbito de una tarea.
  • Agregue el contexto específico del dominio que el agente pasó por alto.
  • Proporcione ejemplos de código para el resultado deseado.

Importante

Las herramientas del agente gestionan tasks.md como un panel de solo lectura. No edite tasks.md directamente. El agente sobrescribe los cambios manuales. Edite scenario-instructions.md o bien edite archivos individuales task.md en su lugar.

Creación de aptitudes personalizadas

Las habilidades son el punto de extensión principal del agente. Una aptitud es un archivo Markdown con un encabezado de metadatos que enseña al agente a controlar una actualización, un patrón o una tarea específicos.

Dónde ubicar habilidades personalizadas

Ubicación Ámbito Se utiliza cuando
.github/skills/my-skill.md Repositorio (compartido con equipo) Patrones de actualización para todo el equipo
.github/upgrades/skills/my-skill.md Repositorio (específico de la actualización) Aptitudes específicas para escenarios de actualización
%UserProfile%/.copilot/skills/my-skill.md Perfil de usuario (personal, todos los repositorios) Preferencias y patrones personales

Sugerencia

Las aptitudes de nivel de repositorio (.github/skills/) son la opción más común. Viajan con el código y todo el equipo puede usarlos.

Estructura del archivo de habilidades

Cada archivo de aptitud tiene dos partes: un encabezado de metadatos (que el agente usa para comprender cuándo se aplica la aptitud) y un cuerpo de Markdown (instrucciones que sigue el agente).

---
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

Campos de metadatos

Campo Obligatorio Descripción
name Sí Identificador único en el estuche del kebab. Comience con un verbo de gerundio (por ejemplo, upgrading-, converting-). Máximo de 64 caracteres.
description Sí Determina cuándo carga la habilidad el agente. Incluya frases de desencadenador, como palabras y patrones que deben activar la aptitud.
metadata.discovery No Controla cuándo se carga la aptitud: preload (siempre disponible), lazy (a petición cuando la descripción coincide, el valor predeterminado y el recomendado) o scenario (define un orquestador de flujo de trabajo).
metadata.traits No Palabras clave que describen las tecnologías del proyecto, como .NET, CSharp, VisualBasic o DotNetCore.

Buenas prácticas de desarrollo de habilidades

  • Sea específico en la descripción: Incluya nombres de paquete exactos, nombres de biblioteca y frases desencadenadores de lenguaje natural que los usuarios puedan escribir.
  • Incluya flujos de trabajo claros y paso a paso: Numeración de los pasos. Sea explícito sobre qué archivos se van a cambiar y qué comandos se van a ejecutar.
  • Incluir criterios de éxito: Sin criterios de éxito, el agente no sabe cuándo detener. Utilice casillas de verificación o una lista clara de condiciones verificables.
  • Incluir el control de errores: Anticipa los modos de error comunes, como los paquetes que faltan, los errores de compilación o las pruebas interrumpidas.
  • Mantener las aptitudes centradas: Una aptitud por actualización o tipo de tarea. Una aptitud para "actualizar FooBar v2 a v3" es mejor que "actualizar todas las bibliotecas internas".
  • Nombre con un verbo en gerundio: Use upgrading-foobar-v2-to-v3, no foobar-upgrade o foobar-v3.
  • Use lazy descubrimiento: Use lazy descubrimiento para la mayoría de las habilidades personalizadas y evitar sobrecargar la ventana de contexto del agente.

Creación de escenarios personalizados

Para los usuarios avanzados que desean definir flujos de trabajo de actualización completamente nuevos, los escenarios personalizados le permiten organizar una canalización completa de actualización en varias fases. Un escenario es una habilidad con metadata.discovery: scenario que define las fases que sigue el agente.

---
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

Coloque archivos de escenario en .github/skills/ o .github/upgrades/skills/ para que el agente los detecte.

Sugerencia

El scenarioTraitsSet campo define los rasgos que usa el agente para hacer coincidir el escenario con respecto a las características de la solución. Estos rasgos ayudan al agente a sugerir su escenario cuando corresponda.

Control de código fuente y ramificación

El agente ofrece trabajar en una rama de Git, pero tiene control total sobre la estrategia:

  • Nomenclatura de rama: Indique al agente qué nombre de rama usar o deje que el agente sugiera uno.
  • Ramas por tarea: Solicite una rama independiente por tarea para una revisión pormenorizada.
  • Tiempo de confirmación: Elija cuándo se confirma el agente: después de cada tarea completada (valor predeterminado), solo al final de la actualización completa o a petición.
  • Sin control de código fuente: El agente también funciona con carpetas que no son de Git, pero recomienda realizar primero copias de seguridad del proyecto.

Instrucciones de chat de ejemplo:

  • "Use el nombre de rama 'upgrade/dotnet10' para esta actualización"
  • "Crear una rama por tarea para que pueda revisar cada una por separado"
  • "No te comprometas hasta que te lo pida explícitamente"
  • "Confirmar después de cada tarea con un mensaje descriptivo"

Sugerencia

En el caso de las actualizaciones de varios proyectos de gran tamaño, las ramas por tarea proporcionan flexibilidad para revisar y combinar cada cambio de forma independiente, o revertir una sola tarea sin afectar al resto.

Prioridad de carga de habilidades

Cuando el agente detecta varias aptitudes, las resuelve mediante un sistema de prioridad. Los orígenes de mayor prioridad invalidan o complementan los de prioridad inferior:

Priority Fuente Ubicación
5 (más alto) Aptitudes personalizadas (proporcionadas por el usuario a través de la API) —
4 Aptitudes de perfil de usuario %UserProfile%/.copilot/skills/
3 Aptitudes de actualización del repositorio .github/upgrades/skills/
2 Habilidades de gestión de repositorios .github/skills/
1 (más bajo) Competencias integradas en el agente —

El agente recopila habilidades de todas las fuentes. Cuando las habilidades tienen un alcance superpuesto, las fuentes de mayor prioridad tienen precedencia. El discovery campo controla cuándo se carga la habilidad. lazy significa a petición cuando sea pertinente y preload significa siempre disponible.

Sugerencia

No es necesario reemplazar una aptitud integrada para cambiar el comportamiento. Una habilidad de repositorio de mayor prioridad complementa la habilidad incorporada, añadiendo las convenciones específicas de su equipo además del comportamiento base.

Contenido relacionado

  • Last updated on