VS Code

Uma skill portátil para configurar e operar IDEs da família VS Code (VS Code, VS Code Insiders, Cursor, VSCodium, Trae, Qoder, CodeBuddy) através da CLI do produto e arquivos de configuração JSON estruturados. Os padrões usam apenas locais padrão; caminhos explícitos são obtidos de variáveis de ambiente e de um arquivo de configuração para que a skill possa ser executada em qualquer máquina sem edição.

Nota de plataforma: Multiplataforma através do gateway Python scripts/vscode_skill.py. No Windows, ele encaminha para o driver PowerShell vscode-cli.ps1 (a implementação original, 11/11 testes passam). No macOS e Linux, ele implementa info, ext list, settings path/get/set/smoke e python set-interpreter nativamente em Python; todo o resto é delegado ao binário code local.

Início Rápido

Multiplataforma (recomendado)

# Mostra o produto detectado, o caminho da CLI e os locais principais
python scripts/vscode_skill.py info

# Lista extensões instaladas
python scripts/vscode_skill.py ext list

# Mostra o caminho do arquivo de configuração do usuário e as configurações principais atuais
python scripts/vscode_skill.py settings path
python scripts/vscode_skill.py settings get

# Altera o tamanho da fonte nas configurações do usuário (escreve apenas com --Apply)
python scripts/vscode_skill.py settings set \
    --FontSize 16 --FontFamily "JetBrains Mono, Consolas, monospace" --Apply

# Configurações no escopo do projeto
python scripts/vscode_skill.py settings set \
    --Scope project --ProjectPath /path/to/project \
    --FormatOnSave true --Apply

# Interpretador Python para um projeto
python scripts/vscode_skill.py python set-interpreter \
    --ProjectPath /path/to/project --VenvName .venv

Somente Windows (PowerShell)

Os mesmos comandos funcionam diretamente através do vscode-cli.ps1 se você preferir PowerShell:

pwsh -File $PSScriptRoot\scripts\vscode-cli.ps1 info
pwsh -File $PSScriptRoot\scripts\vscode-cli.ps1 ssh open `
    --HostName devbox --LinuxPath /home/user/project

Valores de --Product:

auto (padrão): detecta VS Code primeiro, depois VS Code Insiders.
vscode: usa code / code.cmd.
vscode-insiders: usa code-insiders / code-insiders.cmd.
Qualquer slug de produto configurado, como cursor, vscodium, trae-cn, qoder ou codebuddy-cn: usa products.<slug>.cliPath, userDataPath e extensionsPath do arquivo de configuração.

Defina o produto padrão explicitamente com VSCODE_SKILL_PRODUCT ou através do arquivo de configuração (veja Configuração).

Produtos Compatíveis com VS Code

A detecção automática embutida é mais forte para VS Code e VS Code Insiders. Cursor, VSCodium, Trae, Qoder e CodeBuddy são tratados através do caminho de configuração genérica de produto, a menos que sua CLI já seja detectável através de um wrapper específico do ambiente.

Esta skill reivindica apenas a superfície de configuração compatível com VS Code para produtos derivados:

Configurações de usuário e projeto, incluindo .vscode/settings.json.
Projetos .vscode/tasks.json, .vscode/launch.json e .vscode/extensions.json.
Atalhos de teclado, snippets, perfis, extensões, templates, seleção de interpretador Python e fluxos de abertura remota onde a CLI do produto local suporta.

Não use esta skill para suporte a chat AI proprietário, contas, configurações de modelo, lojas de agentes, marketplaces específicos de produto, estado SQLite oculto, tokens ou arquivos de runtime internos. Para Qoder e CodeBuddy em particular, mantenha o suporte apenas à camada de editor/configuração compatível com VS Code, a menos que o usuário forneça documentação oficial específica do produto e solicite um adaptador separado.

Configuração

Caminhos e preferências por máquina são resolvidos nesta ordem:

Variável de ambiente (maior prioridade).
Arquivo de configuração em $VSCODE_SKILL_CONFIG se definido, caso contrário o padrão da plataforma:
- Windows: %APPDATA%\vscode-skill\config.json
- macOS / Linux: $XDG_CONFIG_HOME/vscode-skill/config.json ou ~/.config/vscode-skill/config.json
Padrões internos (menor prioridade).

Variáveis de Ambiente

Variável	Propósito	Padrão
`VSCODE_SKILL_HOME`	Local de instalação da skill	diretório pai do script em execução
`VSCODE_SKILL_CONFIG`	Sobrescreve o caminho do arquivo de configuração	padrão da plataforma acima
`VSCODE_SKILL_TEMP`	Sobrescreve o diretório temporário para testes	`$TEMP/vscode-skill`
`VSCODE_SKILL_PRODUCT`	Valor padrão de `--Product`	`auto`
`VSCODE_CODE_CLI`	Caminho explícito para a CLI do VS Code	detectado automaticamente
`VSCODE_INSIDERS_CLI`	Caminho explícito para a CLI do VS Code Insiders	detectado automaticamente
`VSCODE_EXTENSIONS_DIR`	Sobrescreve o diretório de instalação de extensões para qualquer produto	padrão do produto ou configuração
`VSCODE_USER_DATA`	Sobrescreve o diretório de dados do usuário (raro)	padrão da plataforma

Esquema do Arquivo de Configuração

Copie config.example.json da raiz da skill para o seu local de configuração e edite. Todas as chaves são opcionais.

{
  "product": "auto",
  "tempDir": null,
  "products": {
    "vscode": {
      "cliPath": "C:\\Users\\you\\scoop\\apps\\vscode\\current\\bin\\code.cmd"
    },
    "vscode-insiders": {
      "cliPath": "C:\\Users\\you\\scoop\\apps\\vscode-insiders\\current\\bin\\code-insiders.cmd"
    },
    "cursor": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\cursor\\resources\\app\\bin\\cursor.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\Cursor\\User",
      "extensionsPath": "C:\\Users\\you\\.cursor\\extensions"
    },
    "vscodium": {
      "cliPath": "C:\\Users\\you\\scoop\\apps\\vscodium\\current\\bin\\codium.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\VSCodium\\User",
      "extensionsPath": "C:\\Users\\you\\.vscode-oss\\extensions"
    },
    "trae-cn": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\Trae CN\\bin\\trae-cn.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\Trae CN\\User",
      "extensionsPath": "C:\\Users\\you\\.trae-cn\\extensions"
    },
    "qoder": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\Qoder\\bin\\qoder.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\Qoder\\User",
      "extensionsPath": "C:\\Users\\you\\.qoder\\extensions"
    },
    "codebuddy-cn": {
      "cliPath": "C:\\Users\\you\\AppData\\Local\\Programs\\CodeBuddy CN\\bin\\codebuddy.cmd",
      "userDataPath": "C:\\Users\\you\\AppData\\Roaming\\CodeBuddy CN\\User",
      "extensionsPath": "C:\\Users\\you\\.codebuddycn\\extensions"
    }
  },
  "ssh": {
    "defaultHost": "localhost",
    "defaultUser": "you"
  },
  "wsl": {
    "defaultDistro": "Ubuntu-24.04"
  }
}

Execute pwsh -File scripts/init-config.ps1 para escrever um arquivo de configuração inicial no local padrão.

Disciplina de Escopo

Antes de escrever qualquer estado do IDE, classifique-o em um dos três escopos e confirme com o usuário quando ambíguo:

Inspeção somente leitura: info, ext list/locate, settings get/path. Sempre seguro.
Configuração de projeto: .vscode\settings.json, tasks.json, launch.json, extensions.json, snippets de projeto. Digno de commit; não inclua temas pessoais, fontes, informações de conta ou caminhos absolutos específicos da máquina.
Configuração de usuário / global: settings.json do usuário, keybindings.json, snippets de usuário, configurações de perfil, extensões instaladas. Sempre informe o produto alvo, arquivo, chave, valor antigo (quando legível), novo valor e caminho de reversão antes de aplicar.

Regras:

settings set requer --Apply explícito; sem ele, o comando apenas valida as entradas.
ext install chama a CLI do produto com --install-extension. Se a galeria falhar, o script não tenta novamente silenciosamente com Open VSX; uma mensagem de aviso clara é impressa e o chamador decide.
As configurações de projeto escritas por esta skill nunca devem incluir python.defaultInterpreterPath apontando para um venv local da máquina, a menos que o projeto seja destinado a ser reproduzível nessa máquina específica.

Referência de Configurações

Caminhos comuns de configurações do usuário:

VS Code: %APPDATA%\Code\User\settings.json
VS Code Insiders: %APPDATA%\Code - Insiders\User\settings.json

Chaves comuns (todas configuráveis através de settings set):

Chave	Flag	Tipo
`editor.fontFamily`	`--FontFamily`	string
`editor.fontSize`	`--FontSize`	int
`editor.lineHeight`	`--LineHeight`	number
`workbench.colorTheme`	`--ColorTheme`	string
`workbench.iconTheme`	`--IconTheme`	string
`workbench.productIconTheme`	`--ProductIconTheme`	string
`editor.wordWrap`	`--WordWrap`	string
`editor.tabSize`	`--TabSize`	int
`editor.formatOnSave`	`--FormatOnSave`	bool
`files.autoSave`	`--AutoSave`	string
`editor.minimap.enabled`	`--Minimap`	bool
`python.defaultInterpreterPath`	(definido via `python set-interpreter`)	string

Para chaves arbitrárias, passe --SettingKey <key> --SettingValue <value>. Os valores são convertidos: true/false → bool, inteiro/float → number, {...} / [...] → JSON, caso contrário string.

Arquivos JSON podem usar o estilo JSON-com-Comments do VS Code; o analisador JSON padrão do script lida apenas com JSON puro. Arquivos contendo comentários devem ser editados através do editor ou de uma ferramenta compatível com JSONC.

Comandos

pwsh -File scripts/vscode-cli.ps1 info
pwsh -File scripts/vscode-cli.ps1 ext list
pwsh -File scripts/vscode-cli.ps1 ext locate --Id ms-python.python
pwsh -File scripts/vscode-cli.ps1 ext install --Id ms-python.python
pwsh -File scripts/vscode-cli.ps1 ext install --Path D:\downloads\some-extension.vsix

pwsh -File scripts/vscode-cli.ps1 settings path
pwsh -File scripts/vscode-cli.ps1 settings get
pwsh -File scripts/vscode-cli.ps1 settings set --FontSize 16 --Apply
pwsh -File scripts/vscode-cli.ps1 settings set --Scope project --ProjectPath D:\projects\demo --FormatOnSave true --Apply
pwsh -File scripts/vscode-cli.ps1 settings smoke

pwsh -File scripts/vscode-cli.ps1 python make-venvs --ProjectPath D:\projects\demo
pwsh -File scripts/vscode-cli.ps1 python set-interpreter --ProjectPath D:\projects\demo --VenvName .venv
pwsh -File scripts/vscode-cli.ps1 python verify --ProjectPath D:\projects\demo --ExpectedVenvName .venv

pwsh -File scripts/vscode-cli.ps1 ssh smoke --HostName localhost
pwsh -File scripts/vscode-cli.ps1 ssh open --HostName devbox --LinuxPath /home/user/project
pwsh -File scripts/vscode-cli.ps1 wsl list
pwsh -File scripts/vscode-cli.ps1 wsl open --Distro Ubuntu-24.04 --LinuxPath /home/user/project

Ordem de resolução da CLI: env explícito (VSCODE_CODE_CLI / VSCODE_INSIDERS_CLI) → config.products.<product>.cliPath → Get-Command code.cmd (PATH) → Get-Command code (PATH) → %LOCALAPPDATA%\Programs\Microsoft VS Code\bin\code.cmd (padrão Windows). Produtos genéricos falham claramente quando products.<product>.cliPath está ausente; eles nunca são mapeados silenciosamente para VS Code.

Templates e Conteúdo Empacotado

A skill inclui conteúdo curado sob references/:

settings-index.md — 80 configurações mais usadas com tipo, padrão, escopo.
settings-precedence.md — Modelo de precedência de 11 camadas + comportamento de workspace multi-raiz.
tasks-templates.md + templates/tasks/*.json — 10 tasks.json prontos para Node, TypeScript, Python, Go, Rust, Docker, Make.
launch-templates.md + templates/launch/*.json — 9 launch.json prontos para as mesmas linguagens mais Chrome.
extension-packs.md — 8 stacks curados (frontend-web, backend-python, backend-node, data-science, systems, devops, polyglot-baseline, ai-coding).
keybindings-cheatsheet.md — 50 atalhos mais reatribuídos.

# Lista templates de tarefas disponíveis
python scripts/vscode_skill.py tasks list

# Gera .vscode/tasks.json a partir de um template (recusa sobrescrever sem --Force)
python scripts/vscode_skill.py tasks init --Template python-pytest --ProjectPath /path/to/project --Apply

# Mesma estrutura para templates de depuração
python scripts/vscode_skill.py launch init --Template python-current-file --ProjectPath /path/to/project --Apply

# Stacks de extensão curados
python scripts/vscode_skill.py extensions stacks
python scripts/vscode_skill.py extensions recommend --Stack frontend-web
python scripts/vscode_skill.py extensions install --Stack backend-python
python scripts/vscode_skill.py extensions pin --Stack polyglot-baseline --ProjectPath /path/to/project

Perfis, Sincronização de Configurações, Workspaces Multi-raiz

# Inspeciona perfis (somente leitura)
python scripts/vscode_skill.py profile list
python scripts/vscode_skill.py profile show --Profile <name>

# Verifica se o armazenamento de sincronização de configurações existe localmente (não lê cargas)
python scripts/vscode_skill.py settings-sync status

# Utilitários para workspace multi-raiz
python scripts/vscode_skill.py workspace info --ProjectPath /path/to/project
python scripts/vscode_skill.py workspace folder-settings-get --ProjectPath /path --Folder frontend
python scripts/vscode_skill.py workspace folder-settings-set --ProjectPath /path --Folder frontend --SettingKey editor.defaultFormatter --SettingValue dbaeumer.vscode-eslint --Apply

A Sincronização de Configurações nunca é ativada ou desativada programaticamente — a skill apenas informa se a pasta de armazenamento de sincronização existe. Ative/desative através da UI de Contas do VS Code para evitar vazamentos acidentais de dados.

Desenvolvimento Remoto

ssh open constrói uma URI vscode-remote://ssh-remote+<host><path> e inicia a CLI resolvida com --folder-uri.
wsl open constrói uma URI vscode-remote://wsl+<distro><path> similarmente.
ssh smoke executa ssh -V, ssh -G <host> e Test-NetConnection para confirmar a camada inferior; ele não garante que a extensão Remote-SSH esteja instalada ou que o servidor do VS Code tenha iniciado.

Para diagnóstico remoto mais aprofundado, verifique Ajuda → Alternar Ferramentas de Desenvolvedor, o canal de saída da extensão Remote-SSH ou a entrada workspaceStorage do produto relevante.

Testes

O run_vscode_skill_tests.py incluído executa verificações seguras de não-escrita por padrão:

python -X utf8 scripts/run_vscode_skill_tests.py --basic

Grupos opcionais (requerem o ambiente correspondente):

python -X utf8 scripts/run_vscode_skill_tests.py --include-python-venv
python -X utf8 scripts/run_vscode_skill_tests.py --include-workspace
python -X utf8 scripts/run_vscode_skill_tests.py --include-ssh
python -X utf8 scripts/run_vscode_skill_tests.py --include-wsl

# Tudo de uma vez
python -X utf8 scripts/run_vscode_skill_tests.py --all

# Sobrescrever caminhos do produto para teste (não afeta a configuração principal)
$env:VSCODE_CODE_CLI = "C:\custom\path\code.cmd"
$env:VSCODE_SKILL_PRODUCT = "cursor"
python -X utf8 scripts/run_vscode_skill_tests.py --basic

# Testa múltiplos slugs (definir VSCODE_CODE_CLI também para clássico)
python -X utf8 scripts/run_vscode_skill_tests.py --product cursor --basic

Variáveis de ambiente (VSCODE_CODE_CLI, VSCODE_INSIDERS_CLI, VSCODE_SKILL_PRODUCT) têm efeito durante os testes, substituindo o produto padrão e caminhos da CLI. As flags --product e --code-cli substituem ainda mais.

Dependências

A skill requer Python 3.10+ ou PowerShell 7+.

A skill não impõe dependências Python de terceiros.

Licença

MIT

Duanzhoutao/vscode-skill

O que é vscode-skill?

Perguntar na sua IA favorita

Documentação