gws-drive

Visão geral da skill gws-drive

O que a gws-drive faz

gws-drive é a skill de Google Drive para a Google Workspace CLI. Ela ajuda você a gerenciar arquivos, pastas, shared drives e fluxos de trabalho relacionados à Drive API pela linha de comando, com orientações específicas da skill para evitar suposições sobre nomes de recursos, campos obrigatórios e restrições de permissão.

Quem deve usar

Use a skill gws-drive se você trabalha com Backend Development, automação ou ops e precisa repetir ações no Drive em scripts ou fluxos de trabalho de agentes. Ela é mais útil quando você quer um processo apoiado por CLI para tarefas no Drive em vez de um prompt isolado, especialmente para uploads, operações sensíveis a metadados e consultas orientadas por API.

O que importa antes de instalar

O principal valor da gws-drive não é amplitude, e sim confiabilidade: ela direciona o agente para os recursos certos do Drive e para o formato correto da requisição. O maior obstáculo para adoção é a autenticação e a configuração compartilhada, porque a skill depende do ambiente mais amplo gws e das instruções compartilhadas de gws-shared para flags e regras de segurança.

Como usar a skill gws-drive

Instalação e verificação de pré-requisitos

Instale a skill gws-drive no contexto da Google Workspace CLI e confirme primeiro o pré-requisito compartilhado: ../gws-shared/SKILL.md. Os metadados da skill também esperam que o binário gws esteja disponível, então verifique se a CLI funciona antes de tentar qualquer fluxo no Drive. Um caminho prático de instalação é rodar gws drive --help depois da configuração e comparar a saída com a lista de recursos da skill.

Comece pelo formato de entrada certo

O padrão de uso da gws-drive é gws drive <resource> <method> [flags], então seu prompt deve nomear o recurso de destino, a ação e as restrições exatas de saída. Um bom input seria algo como: “Liste os shared drives aos quais tenho acesso, retorne só name e id, e exclua itens na lixeira.” Um input fraco seria: “Verifique o Drive.” Se você estiver usando o guia gws-drive para Backend Development, inclua identificadores, pastas pai e qualquer suposição sobre permissões ou escopo logo de início.

Leia estes arquivos primeiro

Comece com SKILL.md e depois examine ../gws-shared/SKILL.md, porque ele governa autenticação, flags globais e comportamento de segurança. Neste recorte do repositório, não há scripts auxiliares nem pastas de suporte para aproveitar, então o próprio arquivo da skill é a principal fonte de verdade. Preste atenção especial às seções de recursos da API e ao comando auxiliar +upload, porque eles mostram o fluxo pretendido em vez de obrigar você a inferi-lo a partir de documentos genéricos do Drive.

Fluxo de trabalho que gera melhores resultados

Use um fluxo de três etapas: defina o recurso, refine o método e depois adicione apenas as flags que afetam a resposta da API. Por exemplo, uma solicitação para buscar informações da conta do Drive deve mencionar que a chamada about.get exige fields, enquanto trabalhos de upload devem passar pelo comando auxiliar quando você quiser metadados automáticos. Essa é a principal disciplina de uso da gws-drive: peça a menor resposta útil, não a mais ampla possível.

FAQ da skill gws-drive

A gws-drive serve só para o básico do Drive?

Não. A gws-drive cobre os recursos principais do Drive e também comportamentos específicos da API que importam em automação, como about.get exigir fields e o tratamento de access proposal com restrições de aprovador. Isso a torna mais adequada do que um prompt genérico quando a tarefa depende do formato correto da API, e não apenas de uma explicação geral sobre o Drive.

Quando não devo usar esta skill?

Pule a skill gws-drive se você só precisa de uma dica manual e pontual sobre o Drive ou se ainda não tem a CLI gws e a configuração de auth compartilhada prontas. Ela também é uma escolha ruim quando sua tarefa está fora das operações do Drive, porque a skill é otimizada para construção de requisições e execução via CLI, não para orientação geral sobre o Workspace.

Ela é amigável para iniciantes?

Sim, desde que você consiga descrever um objetivo concreto no Drive. A skill reduz a adivinhação ao mostrar o padrão recurso-método e os principais cuidados, mas iniciantes ainda precisam informar um arquivo, pasta, shared drive ou cenário de permissão específico. Sem isso, o agente pode gerar um comando vago ou escolher uma chamada de API ampla demais.

Qual é a maior diferença em relação a um prompt normal?

Um prompt normal pode explicar conceitos do Drive; a gws-drive entrega um fluxo de trabalho ancorado na CLI real e nos recursos da API. Isso faz diferença quando você precisa de um comando determinístico, de uma seleção válida de campos ou de uma operação sensível a permissões que não deve falhar na primeira execução.

Como melhorar a skill gws-drive

Dê ao agente o contexto exato do Drive

Os melhores resultados vêm de nomear o recurso, a ação e o escopo em uma única frase. Exemplo: “Use gws-drive para listar arquivos na pasta abc123, retorne id, name, mimeType e modifiedTime, e não inclua itens na lixeira.” Isso é muito mais forte do que pedir para “encontrar documentos”, porque reduz a ambiguidade da busca e evita saída desnecessária da API.

Declare restrições que mudam a chamada da API

Mencione se você precisa de shared drives, de uma pasta específica, de um access proposal ou de informações no nível da conta. Para a gws-drive, esses detalhes importam porque recursos diferentes têm permissões e requisitos de resposta diferentes. Se você omitir isso, o primeiro resultado costuma falhar por fields ausente, falta de acesso de aprovador ou uma consulta ampla demais.

Itere do comando para o resultado

Se a primeira saída vier ampla demais, refine o pedido removendo a saída opcional e adicionando os identificadores exatos de que você precisa. Se falhar, verifique se o problema é auth, pré-requisitos ausentes de gws-shared ou uma combinação incompatível de recurso e método. O fluxo mais rápido no guia gws-drive é corrigir o formato do comando antes de mudar a tarefa em si.