gws-slides

Visão geral da skill gws-slides

gws-slides é a skill de Google Slides em googleworkspace/cli para ler e escrever apresentações por meio da CLI gws. Ela é ideal para agentes que precisam inspecionar um deck, criar um novo ou aplicar mudanças estruturadas sem editar slides manualmente no navegador. Se a sua tarefa é “atualizar esta apresentação com segurança a partir de um prompt”, gws-slides é o ponto de partida certo.

O principal valor da skill gws-slides é expor a API do Slides em um fluxo orientado a comandos, em vez de presumir que um prompt genérico consiga adivinhar a estrutura correta da requisição. Isso importa porque atualizações de apresentações costumam ser sensíveis ao schema: títulos, IDs, page resources e operações em lote precisam de parâmetros válidos, ou toda a operação pode falhar. A skill também deixa explícito o pré-requisito: você precisa ter a configuração compartilhada gws-shared em vigor para autenticação, flags globais e regras de segurança.

Para que serve gws-slides

Use gws-slides para Slide Decks quando precisar de ações com suporte da API, como criar uma apresentação, buscar o estado atual de uma apresentação ou aplicar atualizações em lote em páginas e outros recursos da apresentação. Ele funciona melhor para automação, fluxos editoriais repetíveis e tarefas de manutenção conduzidas por agentes do que para copywriting pontual.

Quando ele é uma boa escolha

Escolha a skill gws-slides se você já sabe que quer trabalhar dentro do ecossistema Google Workspace CLI e consegue fornecer um deck ID, um título ou um objetivo de edição concretos. É uma excelente opção quando você precisa de mudanças determinísticas, e não apenas de sugestões sobre o conteúdo dos slides.

Principal limitação que você precisa conhecer

Esta skill não é, por si só, um sistema de “crie a apresentação do zero com design”. Você ainda precisa traduzir seu objetivo para requisições válidas da API do Slides e, para qualquer coisa além da descoberta básica, deve esperar inspecionar o schema do método antes de agir. Se o que você quer é estratégia de layout visual, e não execução via API, uma abordagem de prompting genérica pode ser mais simples.

Como usar a skill gws-slides

Instale o gws-slides corretamente

Para instalar gws-slides, use o fluxo de pacote CLI do repositório: npx skills add googleworkspace/cli --skill gws-slides. Depois da instalação, verifique o pré-requisito indicado em SKILL.md: ../gws-shared/SKILL.md precisa existir para autenticação e regras compartilhadas. Se esse arquivo não estiver presente, o repositório orienta você a executar gws generate-skills.

Leia primeiro os arquivos certos

Comece com skills/gws-slides/SKILL.md e depois leia o arquivo de skill compartilhada que ele referencia. O caminho mais rápido é:

1. SKILL.md para o formato dos comandos e a lista de recursos.
2. ../gws-shared/SKILL.md para autenticação e restrições de segurança.
3. gws slides --help para ver os recursos e métodos disponíveis.
4. gws schema slides.<resource>.<method> antes de montar uma requisição real.

Essa sequência evita a falha mais comum: enviar campos errados para um método válido.

Transforme um objetivo vago em um prompt utilizável

Uma boa solicitação de uso do gws-slides é específica sobre recurso, método e resultado. Em vez de dizer “conserte meus slides”, diga algo como: “Use gws-slides para inspecionar a saída de presentations.get do deck abc123 e depois proponha um plano de batchUpdate para renomear o título e atualizar o texto da primeira página.” Inclua o identificador do deck, a mudança exata e quaisquer restrições, como preservar o layout existente ou evitar remoções de conteúdo.

Trabalhe do schema até o comando

O fluxo da skill começa pelo schema. Use gws schema para descobrir parâmetros obrigatórios, formatos de objeto e valores padrão, e então mapeie a mudança desejada para flags da CLI ou corpos de requisição. Isso é especialmente importante em batchUpdate, onde várias operações são validadas juntas e uma requisição inválida cancela o lote inteiro.

Perguntas frequentes sobre a skill gws-slides

gws-slides é só para usuários avançados?

Não. Ela também funciona para iniciantes, desde que consigam seguir um fluxo de ler o schema antes de agir. A skill é mais estruturada do que um prompt simples, mas é justamente essa estrutura que reduz erros.

Em que gws-slides é diferente de um prompt normal?

Um prompt normal pode descrever como uma apresentação deve ficar. Já o gws-slides pode realmente inspecionar recursos da apresentação e executar mudanças com suporte da API por meio de gws. Isso o torna melhor para edições reais, mas também significa que você precisa fornecer identificadores válidos e detalhes no nível do método.

Quando não devo usar gws-slides?

Não use gws-slides se você só precisa de ideias criativas para slides, copy rascunhada ou um esboço sem caráter técnico. Ele também é uma escolha ruim se você não tem acesso ao ambiente da Google Workspace CLI ou à configuração compartilhada de autenticação necessária.

O que devo verificar antes de instalar?

Confirme que seu fluxo depende de operações da Google Slides API e que você consegue atender ao pré-requisito do arquivo gws-shared. Se o seu repositório ou ambiente não conseguir satisfazer essa dependência, o gws-slides será difícil de usar com confiabilidade.

Como melhorar a skill gws-slides

Dê ao agente o contexto exato do deck

Os prompts mais fortes para gws-slides incluem o presentation ID, o recurso-alvo e a ação pretendida. Se o deck for novo, diga isso; se já existir, informe se a mudança precisa preservar os slides atuais, a ordem ou as speaker notes. Isso reduz a adivinhação e aumenta a chance de o primeiro comando ser válido.

Peça o método da API, não só o resultado

A skill funciona melhor quando você nomeia a operação esperada, como presentations.get ou presentations.batchUpdate. Se você pedir apenas para “atualizar o deck”, o agente precisa inferir o método e pode seguir por um caminho incompleto. Solicitações que deixam claro o método produzem um uso melhor de gws-slides.

Use iteração depois da primeira leitura

Um fluxo prático é inspecionar o deck primeiro e depois refinar a solicitação com base na estrutura retornada. Depois da primeira saída, afine o prompt para a página, o campo ou a operação em lote exata que você quer mudar. Isso costuma ser mais eficaz do que tentar especificar cada detalhe dos slides logo de início.

Fique atento a falhas de validação em batchUpdate

O modo de falha mais comum em gws-slides é um objeto de requisição inválido dentro de um lote. Para evitar isso, monte lotes menores, verifique os nomes dos parâmetros com gws schema e só combine operações quando cada uma já estiver comprovadamente válida.