Criar competências do Copilot para o Excel (pré-visualização)

Pode criar competências personalizadas para realizar tarefas complexas para agentes de IA e Copilot para Excel. Opcionalmente, estas competências podem utilizar a Biblioteca JavaScript do Office (Office.js).

A documentação de orientação principal para a criação de competências encontra-se em Plug-ins de criação para Copilot Cowork. O contexto do artigo refere-se ao Microsoft Cowork, mas a documentação de orientação aplica-se geralmente a todas as competências personalizadas que podem ser ligadas a um agente em execução no Copilot.

Comece com a secção O que vai criar e, em seguida, avance para Criar um plug-in do zero.

Este artigo fornece apenas orientações suplementares para criar competências que utilizam Office.js para interagir com um livro do Excel.

Suplemento para o Passo 1

Siga estes passos para complementar o Passo 1: Criar a sua primeira competência.

1. No frontmatter YAML de um SKILL.md ficheiro, inclua uma metadata.tags propriedade com uma excel etiqueta e outras etiquetas, conforme necessário. Apresentamos um exemplo a seguir.

   name: my-excel-skill
   description: |
     Use this skill in Excel to ... 
   metadata:
     version: 1.0.0
     tags: excel
   

2. Para a maioria das competências do Excel, o resultado deve estar no livro e não numa interface de chat ou da CLI. Assim, em vez da secção "Formato de Saída" de um SKILL.md ficheiro, tenha uma secção "Saída do Livro". Apresentamos um exemplo a seguir.

   ## Workbook output
   
   Produce a dashboard sheet with the following characteristics:
   
   - It should be named "My Skill Output".
   - ... other characteristics here.
   

3. Inclua uma secção "Armadilhas comuns a evitar" no SKILL.md. Apresentamos um exemplo a seguir.

   ## Common pitfalls to avoid
   
   - Do not search broadly for unrelated sheets or columns.
   - Do not invent missing data.
   - Do not claim to be finished when the current environment can't update the workbook.
   

Suplemento para o Passo 2

1. Crie scripts JavaScript que chamem APIs no Office.js e coloquem-nas na pasta \scripts da competência. Cada script tem de ser executado até à conclusão sem interação adicional por parte do utilizador ou do agente. Qualquer Office.js APIs pode ser chamada, mas, normalmente, o script será composto por uma única chamada assíncrona de Excel.run, como no exemplo editado seguinte.

   await Excel.run(async (context) => {
      ...
      await context.sync();
   });
   

   Importante

   O script não deve chamar Office.onReady ou definir um Office.initialize. O Copilot no Excel cria automaticamente um runtime e inicializa Office.js.

2. Inclua dois ficheiros markdown como recursos que irão impor alguns limites à forma como a competência interage com o livro.

   1. O primeiro recurso deve dar instruções sobre como o livro existente deve ser limpo ou normalizado antes de a competência adicionar qualquer saída ao mesmo. Estas instruções são específicas do cenário dos endereços de competência e não das melhores práticas genéricas do Excel. Segue-se um exemplo de uma habilidade que cria um dashboard com dados sobre uma rivalidade atlética entre duas faculdades americanas.

      # Workbook data guardrails
      
      Use this reference to improve data quality before the scenario skill generates an output.
      
      ## Core principles
      
      - Start from workbook labels already present in the workbook.
      - Search only for the exact missing sheet or column names the scenario needs.
      - Ask precise questions instead of inventing scores, quotes, colors, or team metadata.
      
      ## Search rules
      
      - Prefer exact names such as `Game Results`, `Player Stats`, `Team Stats`, `Quotes Colors`, `Team Profiles`, `Roster Recruiting`, or `Opponent PPG`.
      - If a required field is missing, ask for the exact replacement label instead of broad keyword guesses.
      - Stop searching once the needed data for this scenario is located.
      
      ## Organization playbook
      
      - If the workbook is messy, ask the user to rename sheets or headers before analysis.
      - Use one sheet for game results, one for player or team stats, and one for branding or quotes when possible.
      - Don't assume one table can serve multiple scenarios.
      
      ## Quality checks
      
      - Confirm the selected school, season range, metric choice, and other custom hooks before generating output.
      - Keep caveats visible for limited games, freshman samples, or incomplete rows.
      - Label synthetic rows clearly when they are used.
      
      

   2. O segundo recurso deve fazer o seguinte.

      • Forneça algumas regras de qualidade gerais que o Copilot deve sempre seguir ao utilizar a competência.
      • Explique quando é que os scripts da competência devem ser chamados e quando não devem ser.
      • Explique o que fazer, e não fazer, se um utilizador tiver invocado a competência em Copilot fora do Excel.

      Apresentamos um exemplo a seguir.

      # Excel vs non-Excel execution guidance
      
      ## When the skill runs inside Excel
      
      - Prefer workbook-native ranges, named tables, and Office.js helpers already available in the current session.
      - Keep the output focused on workbook changes, sheet creation, chart updates, and branded formatting.
      - Use the workbook as the primary source of truth.
      
      ## When the skill runs outside Excel
      
      - Treat the workbook as a data file and provide the exact next steps, schema assumptions, and missing inputs.
      - Avoid claiming that charts or sheets were completed unless the current environment can perform the action.
      - Ask the user to open the workbook in Excel or provide the exact labels needed for the scenario.
      
      ## Quality checks for either environment
      
      - Confirm the execution mode before generating output.
      - State clearly what was completed and what still needs user or workbook action.
      - Never invent missing data or pretend a workbook update succeeded.
      
      ## When to use the scripts folder
      
      - Run `scripts/my-first-script.js` when, and only when, the user asks for ... 
      - Run `scripts/another-script.js` when, and only when, the user asks for ...
      - Use these scripts after the workbook context is ready for shape and sheet generation, not during an analysis-only pass.
      - If the current environment is outside Excel, explain the workbook steps and do not attempt to execute the Office.js scripts.
      

Suplemento para o Passo 4

1. Embora a sua competência chame APIs de Office.js, não precisa de uma "extensions" secção no manifesto. O Copilot no Excel cria automaticamente um runtime, carrega Office.js e executa os scripts na sua competência.

   Observação

   Uma vez que o runtime não está explicitamente configurado num elemento "extensions", não existe nenhuma "extensions.requirements.capabilities" chave no manifesto, pelo que não existe forma de limitar o runtime a uma versão do Excel que suporte um conjunto de requisitos específico. É improvável, mas teoricamente possível, que o canal de um utilizador possa ter uma versão do Excel que não suporte uma API chamada num script na competência. O efeito de tal chamada é indefinido.

2. Uma vez que um plug-in de competências é uma Aplicação para o Microsoft 365 e é implementado com o manifesto unificado e o pacote para o Microsoft 365, pode incluir a sua competência personalizada no mesmo manifesto e pacote que qualquer outro tipo de aplicação para o Microsoft 365, como um Separador do Teams ou um Suplemento do Office. No entanto, não pode partilhar o seu código de Office.js entre a competência e uma destas outras aplicações porque os scripts de competências estão no pacote de aplicações e não estão alojados online. Tem de duplicar o código em dois ou mais ficheiros se precisar de ser executado pela competência e pela outra aplicação.

Suplemento para o Passo 7

É importante desinstalar de forma limpa a competência após cada sessão de teste. Siga estas etapas.

1. Abra o Teams e certifique-se de que tem sessão iniciada com as mesmas credenciais que utilizou para instalar a competência.
2. Selecione o botão aplicações: o sinal de adição numa caixa.
3. No painel Aplicações , selecione Gerir as suas aplicações.
4. Localize o seu suplemento na lista de aplicações. Tem o nome especificado na propriedade name do frontmatter YAML no SKILL.md ficheiro.
5. Selecione o suplemento na lista de aplicações para expandir a linha.
6. Selecione o ícone do caixote do lixo e, em seguida, selecione Remover na linha de comandos.