lewiswigmore/agent-skills

Guia de Extensão para VS Code

Crie, desenvolva e publique extensões para o VS Code.

Quando Usar

• Extensão do VS Code, desenvolvimento de extensão, plugin vscode
• Criar uma nova extensão do VS Code do zero
• Adicionar comandos, atalhos de teclado ou configurações a uma extensão
• Publicar no Marketplace do VS Code

Início Rápido

# Estruturar nova extensão (recomendado)
npm install -g yo generator-code
yo code

# Ou configuração manual mínima
mkdir my-extension && cd my-extension
npm init -y && npm install -D typescript @types/vscode

Estrutura do Projeto

my-extension/
├── package.json          # Manifesto da extensão (CRÍTICO)
├── src/extension.ts      # Ponto de entrada
├── out/                  # JS compilado (gitignore)
├── images/icon.png       # PNG 128x128 para o Marketplace
└── .vscodeignore         # Excluir arquivos do VSIX

Compilação e Empacotamento

npm run compile      # Compilar uma vez
npm run watch        # Modo de observação (F5 para iniciar depuração)
npx @vscode/vsce package   # Cria o arquivo .vsix

Critérios de Conclusão

• Extensão ativa sem erros
• Todos os comandos registrados e funcionando
• Tamanho do pacote < 5MB (use .vscodeignore)
• README.md inclui links do Marketplace/GitHub

Solução Rápida de Problemas

Sintoma	Correção
Extensão não carrega	Verifique activationEvents (detectado automaticamente desde VS Code 1.74 para comandos/views contribuídos)
Comando não encontrado	Corresponda o ID do comando em package.json/código
Atalho não funciona	Remova a cláusula when, verifique conflitos

Tópico	Referência
Personalização de IA	references/ai-customization.md
Prompts de Revisão	references/code-review-prompts.md
Exemplos de Código	references/code-samples.md
TreeView	references/treeview.md
Webview	references/webview.md
Testes	references/testing.md
Publicação	references/publishing.md
Solução de Problemas	references/troubleshooting.md

Melhores Práticas

Consistência de Nomenclatura

Unifique o nome do pacote, chaves de configuração, IDs de comando e IDs de visualização antes de publicar:

Item	Exemplo
Nome do pacote	copilot-scheduler
Chave de configuração	copilotScheduler.enabled
ID do comando	copilotScheduler.createTask
ID da visualização	copilotSchedulerTasks

Tratamento Centralizado de Notificações

type NotificationMode = "sound" | "silentToast" | "silentStatus";

function getNotificationMode(): NotificationMode {
  const config = vscode.workspace.getConfiguration("myExtension");
  return config.get<NotificationMode>("notificationMode", "sound");
}

function notifyInfo(message: string, timeoutMs = 4000): void {
  const mode = getNotificationMode();
  switch (mode) {
    case "silentStatus":
      vscode.window.setStatusBarMessage(message, timeoutMs);
      break;
    case "silentToast":
      void vscode.window.withProgress(
        { location: vscode.ProgressLocation.Notification, title: message },
        async () => {},
      );
      break;
    default:
      void vscode.window.showInformationMessage(message);
  }
}

function notifyError(message: string, timeoutMs = 6000): void {
  const mode = getNotificationMode();
  if (mode === "silentStatus") {
    vscode.window.setStatusBarMessage(`⚠ ${message}`, timeoutMs);
    console.error(message);
    return;
  }
  void vscode.window.showErrorMessage(message);
}

Exponha uma configuração notificationMode para que os usuários possam controlar como as notificações são exibidas.