Use as competências de Agente com o GitHub Copilot no SQL Server Management Studio

As competências do agente são conjuntos reutilizáveis de instruções que instruem o GitHub Copilot sobre como realizar tarefas específicas. Cada competência é um ficheiro de marcação que defines uma única vez, poupando tempo e garantindo um comportamento consistente em todo o teu fluxo de trabalho. Pensa nas competências como um runbook, não como um grande prompt. Quando usas Agente (pré-visualização), Copilot descobre e aplica automaticamente competências relevantes com base no que estás a pedir.

Note

O modo GitHub Copilot Agent no SQL Server Management Studio (SSMS) está atualmente em pré-visualização.

Ao contrário das instruções personalizadas, que definem preferências gerais para cada resposta, as competências fornecem orientações específicas para tarefas que qualquer agente pode descobrir e utilizar. Define uma competência uma vez e ela aplica-se consistentemente entre as sessões e em toda a equipa.

Pré-requisitos

Como funcionam as competências de Agente

Quando usas o modo Agente, o Copilot analisa as localizações das competências conhecidas no teu repositório e no teu perfil de utilizador. Se a descrição de uma habilidade corresponder à intenção do seu pedido, o Copilot ativa a habilidade e aplica as suas instruções como contexto extra. Quando uma habilidade está ativa, o seu nome aparece no chat para saberes que está a ser aplicada.

O Copilot decide que competências ativar com base no valor do campo description nos metadados iniciais de cada competência. Uma descrição clara e rica em palavras-chave ajuda o Copilot a identificar quando uma competência é relevante.

Localização das competências

Copilot descobre competências nos seguintes locais:

Scope Paths Detalhes
Espaço de trabalho (partilhado com a sua equipa) .github/skills/, .claude/skills/, .agents/skills/ Armazenado na raiz do teu repositório. Comprometido com o controlo de versões para que todos os membros da equipa tenham acesso às mesmas funcionalidades.
Pessoal (apenas o seu perfil) ~/.copilot/skills/, ~/.claude/skills/, ~/.agents/skills/ Aplica-se a todos os teus projetos. Não comprometido com nenhum repositório.

As competências de espaço de trabalho têm prioridade nas convenções específicas de cada projeto. Competências pessoais são úteis para fluxos de trabalho e preferências que acompanham vários projetos.

Cria uma habilidade

Podes criar uma skill a partir do painel de Skills no SSMS ou manualmente no teu sistema de ficheiros.

Cria uma competência a partir do painel de Competências

  1. Na janela Copilot Chat, selecione o ícone Tools.
  2. Selecione o painel de Competências .
  3. No painel de Habilidades, selecione o + botão.
  4. Escolha o âmbito: uma competência de espaço de trabalho (armazenada no repositório) ou uma competência pessoal (armazenada no seu perfil de utilizador).
  5. Introduza um nome para a habilidade. O nome passa a ser o nome do diretório e deve usar apenas letras minúsculas, números e hífens.
  6. O SSMS gera um SKILL.md modelo no novo diretório de competências. Edita o modelo e adiciona as tuas instruções ao ficheiro.

Cria uma competência manualmente

  1. Crie um diretório de competências no local apropriado. Para uma competência de espaço de trabalho, cria .github/skills/ na raiz do teu repositório.
  2. Cria um subdiretório para a tua competência. Cada competência deve ter o seu próprio diretório. Por exemplo: .github/skills/tsql-style-guide/.
  3. Cria um SKILL.md ficheiro dentro do diretório de competências.
  4. Opcionalmente, adicione ficheiros de suporte como scripts, documentos de referência ou exemplos de saída.

Estrutura de diretórios de competências

your-repo/
└── .github/
    └── skills/
        └── index-verification/
        │   ├── SKILL.md          # Required: metadata and instructions
        │   └── references/       # Optional: supplementary documentation
        └── agent-job-failure-triage/
            ├── SKILL.md
            └── examples/         # Optional: example scripts

SKILL.md formato

Cada SKILL.md ficheiro deve conter material inicial YAML seguido de instruções Markdown. O frontmatter fornece os metadados que o Copilot usa para descobrir e ativar a competência.

Propriedades do Frontmatter

Property Obrigatório Description
name Yes Apenas letras minúsculas, números e hífens. Deve corresponder ao nome do diretório principal. Máximo 64 caracteres.
description Yes Descreve o que a habilidade faz e quando a usar. Máximo 1.024 caracteres. Inclua palavras-chave específicas que sinalizem quando a competência é relevante.
license No Nome da licença ou uma referência a um ficheiro de licença incluído na skill.
compatibility No Requisitos ambientais, como o produto pretendido ou as capacidades do sistema necessárias.
metadata No Pares chave-valor arbitrários para outros metadados.
allowed-tools No Lista separada por espaço dos nomes das ferramentas em que a competência está pré-aprovada para uso.

Gerir competências a partir do painel de Competências

Selecione o ícone Tools na janela Copilot Chat para abrir o painel Skills. O painel mostra todas as habilidades que o Copilot descobre na sua sessão atual.

A partir do painel, pode:

  • Editar: Abra o ficheiro SKILL.md de qualquer skill diretamente no editor, no menu ....
  • Abrir a localização do ficheiro: Salta para o diretório de habilidades no disco.
  • Pesquisar: Filtrar competências por nome ou palavra-chave.

O painel também mostra diagnósticos para quaisquer erros de configuração de competências, para que possa identificar e corrigir rapidamente problemas.

Dicas para escrever competências eficazes

  • Seja SKILL.md conciso: Tente menos de 300 linhas. Transferir material de referência detalhado para ficheiros separados em subdiretórios relevantes.
  • Escreva uma descrição rica em palavras-chave: Copilot usa o description para decidir quando ativar a habilidade. Inclua as tarefas, objetos e cenários específicos onde a habilidade se aplica.
  • Utilize passos numerados em procedimentos: As instruções passo a passo são mais fáceis de o modelo seguir do que o texto corrido.
  • Inclua exemplos de resultados esperados: Mostre código de exemplo, formatos de tabela ou blocos de comentários para que o modelo saiba como é "feito".
  • Defina limites explícitos: Diga à habilidade o que não deve fazer. Por exemplo, "Não recomendo colocar índices em tabelas com mais de 10 milhões de linhas sem antes reportar o volume de escrita."
  • Material de apoio de referência: Armazene conteúdos e scripts relacionados em ficheiros dentro de references\, scripts\, ou examples\ e aponte para conteúdos específicos da competência.

Exemplos de competências SQL

Os exemplos seguintes demonstram como escrever competências para tarefas comuns do SQL Server. Usa-os como ponto de partida e adapta-os às convenções da tua equipa.

Verificação do índice

Revise os índices existentes antes de recomendar novos para evitar duplicação.

---
name: index-verification
description: Use when an index recommendation has been generated and must be validated before implementation. Verifies workload benefit, redundancy, write overhead, storage impact, and existing index coverage.
---

# Index Verification

## Use this skill when

- A missing index recommendation exists
- An agent generated an index recommendation
- Query tuning suggests adding an index
- A user asks whether an index should be created

## Never assume

- Missing index DMVs are recommendations, not requirements.
- Do not recommend index creation until validation is complete.

## Verification Checklist

### 1. Check Existing Indexes

Determine whether:

- An equivalent index already exists
- A wider index already covers the workload
- Included columns already satisfy the query
- The recommendation duplicates another recommendation

### 2. Estimate Read Benefit

Evaluate:

- Query execution frequency
- Current execution cost
- Expected seek/selectivity improvement
- Number of affected queries

### 3. Evaluate Write Cost

Determine:

- Insert impact
- Update impact
- Delete impact
- Additional maintenance cost

### 4. Evaluate Storage Impact

Estimate:

- Index size on disk
- Memory pressure
- Replication impact

### 5. Make Recommendation

Return one of:

- Create index
- Modify existing index
- Consolidate with existing recommendation
- Reject recommendation

## Avoid

- Blindly trusting missing-index DMVs
- Creating overlapping indexes
- Recommending indexes for one-off queries
- Ignoring write-heavy workloads

## Output Format

Format output as a table: index name, columns, type, and recommendation (create / modify / consolidate / reject).

Triagem de falhas de trabalho de agentes

Analise o histórico de trabalhos falhados do SQL Agent e faça recomendações para resolver o problema raiz.

---
name: agent-job-failure-triage
description: Use when an automated job, workflow, maintenance task, or agent execution fails. Determines root cause and appropriate remediation while avoiding unsafe recovery actions.
---
# Agent Job Failure Triage

## Objective

Identify root cause before attempting remediation.

## First Rule

Never retry repeatedly without understanding why the job failed.

## Investigation Order

### 1. Collect Failure Details

Gather:

- Job name
- Error message
- Start time
- End time
- Retry history

### 2. Classify Failure

Determine whether failure is:

- Resource-related
- Permission-related
- Configuration-related
- Data-related
- Dependency-related
- Other or unknown

### 3. Check Recent Changes

Investigate:

- Deployments
- Configuration changes
- Schema changes
- Security changes
- Infrastructure changes

### 4. Determine Blast Radius

Identify:

- Data modified by job
- Schema modified by job
- Affected users or departments
- Downstream jobs
- SLA impact
- Data correctness risk

## Safe Actions

- Collect logs
- Validate dependencies
- Escalate when root cause is unknown

## Unsafe Actions

- Retry job
- Disable job
- Force-completing jobs
- Disabling validation checks
- Modifying production data to "make it pass"
- Restarting the SQL Agent service

Conteúdo relacionado

  • Last updated on