gws-forms

Visão geral do skill gws-forms

O que o gws-forms faz

gws-forms é o skill de Google Workspace CLI para ler e escrever Google Forms por meio do comando gws. Ele ajuda você a inspecionar schemas de formulários, criar formulários vazios, atualizar o conteúdo do formulário em etapas controladas e gerenciar operações relacionadas a formulários sem precisar adivinhar campos da API.

Quem deve usar

O gws-forms skill é mais indicado para agentes e usuários que já trabalham em um fluxo de automação do Google Workspace e precisam de execução confiável da Forms API. Ele é especialmente útil quando você quer criação repetível de formulários, atualizações em lote ou inspeção programática em vez de cliques manuais na interface do Forms.

Por que este skill importa

O principal valor de gws-forms for Workflow Automation é expor o fluxo real da API, incluindo descoberta de métodos e construção de entradas orientada por schema. Isso importa porque criar um formulário não é uma ação única: forms.create só gera um formulário vazio, e depois operações no estilo forms.update adicionam itens e configurações.

Limites importantes que você precisa conhecer

Este skill não é um wrapper genérico de “crie um formulário a partir de um prompt”. Ele depende da CLI gws, exige a configuração compartilhada de autenticação e segurança do Google Workspace e segue as restrições da Forms API no repositório. Se você precisa de uma redação ampla em modo conversacional, em vez de ações precisas de API, um prompt simples pode ser mais adequado.

Como usar o skill gws-forms

Instalação e configuração prévia

Para gws-forms install, use a CLI mostrada nos metadados do skill: npx skills add googleworkspace/cli --skill gws-forms. Antes de rodar comandos de Forms, leia ../gws-shared/SKILL.md como orientado no arquivo do skill, porque a autenticação, as flags globais e as regras de segurança ficam lá. Se esse arquivo compartilhado não existir, execute gws generate-skills primeiro.

Comece descobrindo o método

O padrão mais confiável de gws-forms usage é: inspecionar primeiro, chamar depois. Use gws forms --help para navegar pelos recursos e métodos disponíveis e, em seguida, rode gws schema forms.<resource>.<method> para confirmar parâmetros obrigatórios, tipos e padrões antes de montar as flags. Isso evita requisições malformadas e mantém seu prompt ou tarefa alinhado com a forma real da API.

Transforme um objetivo vago em uma requisição viável

Uma boa entrada para gws-forms guide diz o que você quer no nível da API, e não apenas o objetivo de negócio. Por exemplo, em vez de “crie um formulário de feedback”, peça um título, o título do documento, os tipos de perguntas desejados, se o formulário deve começar vazio e se você precisa de configurações de publicação ou ações relacionadas a respostas. Isso dá ao skill estrutura suficiente para decidir se deve chamar forms.create, forms.batchUpdate ou outro método.

Leia estes arquivos e saídas primeiro

Comece com SKILL.md, depois examine o arquivo do skill pai compartilhado e a saída de ajuda/schema da CLI a que ele aponta. Neste repositório, o corpo do skill é enxuto e não há pastas auxiliares, então SKILL.md junto com gws forms --help e gws schema são as principais fontes de verdade. Se o seu fluxo depende de skills adjacentes do Google Workspace, compare os padrões entre eles, mas não assuma que os nomes de campos ou a sequência de operações aplicam-se aqui.

Perguntas frequentes sobre o skill gws-forms

O gws-forms é principalmente para criar formulários?

Sim, mas apenas no sentido da API. gws-forms suporta leitura e escrita de formulários, e a criação é intencionalmente em etapas: primeiro cria-se a estrutura básica, depois adicionam-se itens ou atualizações. Se você espera que um único prompt gere um formulário pronto com todos os campos preenchidos, isso não combina com o fluxo do repositório.

Preciso da CLI gws para usá-lo?

Sim. O skill exige explicitamente o binário gws, e a superfície de comando mostrada no arquivo do skill é gws forms <resource> <method> [flags]. Se o seu ambiente não consegue executar a CLI ou autenticar no Google Workspace, o skill não será utilizável como foi projetado.

Isso é melhor do que um prompt normal?

Para trabalho com API, sim. Um prompt comum pode descrever um formulário, mas o gws-forms skill ajuda a executar as chamadas reais de recurso e método com parâmetros apoiados por schema, reduzindo suposições e requisições quebradas. Use um prompt quando estiver explorando ideias de conteúdo; use este skill quando precisar que a ação no formulário realmente aconteça.

Quando eu não devo usar?

Não use gws-forms se você só precisa de um rascunho rápido de perguntas de pesquisa, se não tiver credenciais do Workspace ou se precisar de um fluxo fora do escopo da Forms API. Ele também não é a melhor escolha quando você quer pular a inspeção de comandos e depender apenas de linguagem natural livre.

Como melhorar o skill gws-forms

Dê ao skill entradas no formato da API

Os melhores resultados vêm de entradas que especificam o recurso alvo, o método e os campos desejados. Inclua o título do formulário, se document_title deve ser diferente e se você está criando um formulário novo, fazendo uma leitura ou executando uma atualização. Por exemplo, “Crie um formulário com o título X, mantenha-o vazio e depois adicione 5 perguntas de múltipla escolha” é muito mais forte do que “monte uma pesquisa”.

Respeite o comportamento de criar primeiro e atualizar depois

Um modo comum de falha é pedir um formulário completo em uma única etapa quando a API só permite dados parciais na criação. O repositório observa que forms.create copia apenas form.info.title e form.info.document_title, e não aceita descrição, itens nem configurações na criação. Melhore a qualidade da saída planejando a segunda etapa com antecedência.

Use a saída do schema para eliminar ambiguidades

Se a primeira tentativa falhar, confira novamente gws schema para ver a assinatura exata do método e os nomes dos parâmetros e então reescreva a solicitação usando esses campos. Essa é a forma mais rápida de melhorar gws-forms usage, porque troca suposições pela mesma estrutura que a CLI espera.

Itere com operações mais específicas

Quando a alteração em um formulário for complexa, divida em ações menores: inspecionar, criar, atualizar, verificar. Esse fluxo reduz erros em atualizações em lote e facilita identificar se o problema é entrada ruim, campos sem suporte ou incompatibilidade entre sua intenção e a Forms API.