CommunityPesquisa e Análise de Dadosgithub.com

detro/quirks

Você pode ter habilidades, mas eu tenho peculiaridades!

O que é quirks?

O ASDF Manager é uma habilidade especializada que permite que agentes de IA gerenciem versões de ferramentas e dependências de projetos usando `asdf`. Essa habilidade lida com a criação e atualização de arquivos `.tool-versions`, instala e atualiza plugins e impõe guardrails de segurança essenciais ao instalar plugins de terceiros, garantindo que apenas plugins confiáveis sejam adicionados. Suporta operações como atualizar todas as ferramentas para suas versões mais recentes, instalar ferramentas específicas, definir versões no projeto ou globalmente e adicionar novos plugins. O fluxo de trabalho inclui detecção do ambiente asdf, busca no índice oficial da comunidade, uma verificação de segurança rigorosa para plugins personalizados com permissão explícita do usuário e instalação/configuração final das versões, seguida de `asdf reshim`. Projetado para ambientes onde asdf é usado para gerenciar múltiplos runtimes (Node.js, Python, Ruby, Go, Elixir, Rust), ele evita o uso quando outros gerenciadores de versão (como mise, fnm, nvm) são preferidos.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add detro/quirks

Installed? Explore more Pesquisa e Análise de Dados skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Gerenciador ASDF

Esta habilidade permite que agentes gerenciem versões de ferramentas e dependências de projetos usando asdf. Ela lida com a criação e atualização de arquivos .tool-versions, instala e atualiza plugins e impõe guardrails de segurança essenciais ao instalar plugins de terceiros.

Quando Usar

  • Quando um projeto utiliza asdf para gerenciar ambientes de execução (ex.: Node.js, Python, Ruby, Go, Elixir, Rust).
  • Quando um arquivo .tool-versions existe no repositório, ou o usuário deseja configurar versionamento de múltiplos runtimes.
  • Quando o usuário pede para "atualizar todas as ferramentas" ou definir uma ferramenta para sua versão "mais recente".
  • Quando o usuário deseja adicionar uma nova ferramenta de desenvolvimento, runtime de linguagem ou utilitário que seja gerenciável via asdf.

Quando Não Usar

  • Quando o projeto está explicitamente configurado para usar outro gerenciador de pacotes/runtime (como mise, fnm, nvm, pyenv, rbenv, gvm ou asdf-vm não está instalado/desejado).
  • Ao instalar pacotes que devem ser gerenciados por gerenciadores de pacotes de nível de sistema (como brew, apt, pacman ou dnf) e que não exigem travamento de versão por projeto.

Entradas

EntradaObrigatórioDescrição
Nome da FerramentaSimO nome do runtime ou ferramenta (ex.: nodejs, python, golang).
VersãoNãoA versão específica para definir ou instalar (ex.: 18.16.0, latest, system).
AçãoSimA operação a ser executada: update-all, install-tool, set-version, ou add-plugin.
GlobalNãoDefina como true para aplicar a configuração globalmente ($HOME/.tool-versions) em vez do diretório do projeto local.

Fluxo de Trabalho

Passo 1: Detectar e Validar o Ambiente ASDF

Antes de executar qualquer comando asdf, verifique se o asdf está instalado e acessível no ambiente shell atual do agente:

  1. Execute which asdf ou asdf --version.
  2. Se o asdf não for encontrado, verifique caminhos de instalação comuns (como $HOME/.asdf/bin/asdf ou /opt/homebrew/bin/asdf). Se estiver instalado, mas não carregado (sourced), oriente o usuário sobre como carregá-lo.
  3. Se o asdf estiver completamente ausente do sistema, a habilidade deve sair antecipadamente e informar o usuário: "Por favor, instale-o a partir de https://asdf-vm.com/guide/getting-started.html"
    • Por quê: A habilidade não pode prosseguir sem o executável principal do asdf instalado. Falhar rapidamente com uma URL de instalação útil garante uma experiência de configuração tranquila para o usuário.

Passo 2: Lidar com solicitações de "Atualizar Todas as Ferramentas"

Quando o usuário solicitar a atualização de todas as ferramentas para suas versões mais recentes:

  1. Localize o arquivo .tool-versions (normalmente na raiz do projeto ou verifique diretórios pais).
  2. Leia a lista de ferramentas definidas no arquivo .tool-versions.
  3. Para cada ferramenta encontrada, execute o seguinte comando para resolver e escrever automaticamente a versão mais recente:
    asdf set <nome-da-ferramenta> latest
    
    • Por quê: Usar asdf set <nome-da-ferramenta> latest é mais preciso e robusto do que editar .tool-versions manualmente, pois aciona o asdf para buscar a versão mais recente real e resolvida, baixar/compilá-la se necessário e escrever a string de versão estática exata de volta no arquivo .tool-versions.

Passo 3: Pesquisar e Adicionar Plugins (Verificação do Índice da Comunidade)

Quando o usuário solicitar a instalação de uma ferramenta/plugin:

  1. Primeiro, verifique se o plugin já está instalado executando:
    asdf plugin list
    
    Se já estiver instalado, pule para o Passo 5.
  2. Se o plugin não estiver instalado, verifique se ele existe no índice oficial da comunidade asdf:
    asdf plugin list all
    
    Filtre ou pesquise a saída pelo nome da ferramenta desejada.
    • Por quê: Verificar o índice da comunidade garante que instalaremos apenas plugins selecionados e revisados. Plugins de terceiros fora do índice oficial têm o poder de executar scripts de hook personalizados e compilar/instalar binários não confiáveis no sistema host.

Passo 4: Verificação de Segurança Rigorosa para Plugins Personalizados/Não-Comunitários

Se a ferramenta solicitada NÃO estiver presente na saída do índice oficial da comunidade (asdf plugin list all):

  1. Oriente o Agente a pesquisar online (ex.: via mecanismos de busca, GitHub ou documentação) para encontrar a URL do repositório fonte correto e legítimo para o plugin asdf.
  2. NÃO prossiga para instalar o plugin personalizado sem permissão explícita do usuário. Esta é uma fronteira de segurança crítica.
  3. Formule uma solicitação de permissão estruturada para o usuário contendo:
    • Um aviso claro de que o plugin não está na lista oficial de repositórios da comunidade asdf.
    • A URL exata do repositório encontrada para o plugin (ex.: https://github.com/alguem/asdf-minhaferramenta).
    • Um aviso sobre as implicações de segurança dos plugins de terceiros (que podem executar código shell arbitrário durante a instalação/uso).
    • Uma solicitação explícita pedindo permissão para prosseguir com a instalação.
  4. Se e somente se o usuário consentir, prossiga para adicionar o plugin personalizado usando a URL verificada:
    asdf plugin add <nome-da-ferramenta> <url-do-plugin>
    

Passo 5: Instalar e Definir a Versão da Ferramenta

Uma vez que o plugin esteja instalado/adicionado:

  1. Se o usuário solicitou uma versão específica, instale-a:
    asdf install <nome-da-ferramenta> <versão>
    
    Caso contrário, instale a versão mais recente:
    asdf install <nome-da-ferramenta> latest
    
  2. Escreva a versão na configuração do projeto:
    • Para versionamento local do projeto (padrão):
      asdf set <nome-da-ferramenta> <versão-ou-latest>
      
    • Para versionamento global de nível de usuário:
      asdf set -u <nome-da-ferramenta> <versão-ou-latest>
      
  3. Execute asdf reshim após a instalação para garantir que todos os shims sejam atualizados e o executável recém-instalado esteja imediatamente utilizável.

Validação

  • Execute asdf current para verificar se as versões de ferramentas recém-definidas estão ativas e resolvem corretamente no diretório.
  • Garanta que o arquivo .tool-versions corresponda às ferramentas e versões configuradas.
  • Verifique se plugins personalizados adicionados fora do índice oficial foram instalados apenas após confirmação explícita do usuário.

Armadilhas Comuns

ArmadilhaSolução
asdf: comando não encontrado no shell do agenteO asdf provavelmente está instalado, mas não carregado (sourced) no shell ativo. Localize asdf.sh (ex.: em /opt/homebrew/opt/asdf/libexec/asdf.sh ou $HOME/.asdf/asdf.sh) e carregue-o, ou adicione /shims ao $PATH dinamicamente no contexto do agente.
O executável da ferramenta não funciona após instalaçãoExecute asdf reshim para regenerar os wrappers do diretório de shims para que o shell possa localizar o novo binário.
A instalação falha devido à falta de ferramentas de compilaçãoLinguagens como Ruby, Python e Erlang compiladas a partir do código fonte usando asdf exigem dependências de construção locais (como gcc, openssl, make, libyaml, etc.). Informe ao usuário quais dependências estão faltando com base nos logs de construção.
O shell não interativo trava em prompts interativosGaranta que os comandos asdf sejam executados de forma não interativa ou que as dependências sejam pré-satisfeitas.

Referências

Habilidades Relacionadas