gws-forms

Descripción general de gws-forms

Qué hace gws-forms

gws-forms es la skill de Google Workspace CLI para leer y escribir Google Forms mediante el comando gws. Sirve para inspeccionar esquemas de formularios, crear formularios vacíos, actualizar el contenido del formulario en pasos controlados y gestionar operaciones relacionadas con Forms sin tener que adivinar campos de la API.

Quién debería usarlo

La gws-forms skill es ideal para agentes y usuarios que ya trabajan en un flujo de automatización de Google Workspace y necesitan una ejecución fiable de la Forms API. Resulta especialmente útil cuando quieres crear formularios de forma repetible, hacer actualizaciones en lote o inspeccionar formularios de manera programática en lugar de usar clics manuales en la interfaz de Forms.

Por qué importa esta skill

El valor principal de gws-forms for Workflow Automation es que expone el flujo real de la API, incluida la detección de métodos y la construcción de entradas guiada por el esquema. Eso importa porque crear un formulario no es una sola acción: forms.create solo genera un formulario vacío, y después hay que añadir elementos y ajustes con operaciones del estilo forms.update.

Límites clave que conviene conocer

Esta skill no es un envoltorio genérico para “crear un formulario a partir de un prompt”. Depende del CLI gws, requiere la configuración compartida de autenticación y seguridad de Google Workspace, y sigue las restricciones de la Forms API documentadas en el repositorio. Si necesitas redacción amplia y conversacional, en lugar de acciones de API precisas, un prompt simple puede ser más práctico.

Cómo usar la skill gws-forms

Instalación y configuración previa

Para gws-forms install, usa el comando del CLI que aparece en los metadatos de la skill: npx skills add googleworkspace/cli --skill gws-forms. Antes de ejecutar comandos de Forms, lee ../gws-shared/SKILL.md tal como indica el archivo de la skill, ya que ahí están la autenticación, las banderas globales y las reglas de seguridad. Si ese archivo compartido no existe, ejecuta primero gws generate-skills.

Empieza descubriendo el método

El patrón más fiable de gws-forms usage es: inspeccionar primero, invocar después. Usa gws forms --help para explorar los recursos y métodos disponibles, y luego ejecuta gws schema forms.<resource>.<method> para confirmar parámetros obligatorios, tipos y valores predeterminados antes de construir las banderas. Así evitas solicitudes mal formadas y mantienes tu prompt o tarea alineado con la forma real de la API.

Convierte un objetivo difuso en una solicitud viable

Una buena entrada para gws-forms guide dice qué quieres a nivel de API, no solo el objetivo de negocio. Por ejemplo, en vez de “haz un formulario de comentarios”, pide un título, el título del documento, los tipos de preguntas previstos, si el formulario debe empezar vacío y si necesitas opciones de publicación o acciones relacionadas con respuestas. Eso le da a la skill la estructura suficiente para decidir si debe llamar a forms.create, forms.batchUpdate u otro método.

Lee primero estos archivos y salidas

Empieza con SKILL.md, luego revisa el archivo de la skill padre compartida y la salida de ayuda/esquema del CLI que allí se indica. En este repositorio, el cuerpo de la skill es compacto y no hay carpetas auxiliares, así que SKILL.md junto con gws forms --help y gws schema son las principales fuentes de verdad. Si tu flujo depende de skills vecinas de Google Workspace, compara sus patrones, pero no des por hecho que sus nombres de campos o su secuencia se aplican aquí.

Preguntas frecuentes sobre gws-forms

¿gws-forms es principalmente para crear formularios?

Sí, pero solo en el sentido de la API. gws-forms admite leer y escribir formularios, y la creación está pensada de forma escalonada: primero se crea la estructura básica y luego se añaden elementos o actualizaciones. Si esperas que un solo prompt genere un formulario terminado con todos los campos ya rellenados, eso no encaja con el flujo del repositorio.

¿Necesito el CLI gws para usarlo?

Sí. La skill exige explícitamente el binario gws, y la superficie de comandos que muestra el archivo de la skill es gws forms <resource> <method> [flags]. Si tu entorno no puede ejecutar el CLI o autenticarse en Google Workspace, la skill no se podrá usar como está pensada.

¿Esto es mejor que un prompt normal?

Para trabajo con API, sí. Un prompt normal puede describir un formulario, pero gws-forms skill ayuda a ejecutar las llamadas reales a recursos y métodos con parámetros respaldados por el esquema, lo que reduce las suposiciones y las solicitudes rotas. Usa un prompt cuando estés ideando contenido; usa esta skill cuando necesites que la acción sobre el formulario ocurra de verdad.

¿Cuándo no debería usarlo?

No uses gws-forms si solo necesitas un borrador rápido de preguntas para una encuesta, si no tienes credenciales de Workspace o si necesitas un flujo fuera del alcance de la Forms API. Tampoco es la opción correcta cuando quieres saltarte la inspección de comandos y depender solo de lenguaje natural libre.

Cómo mejorar la skill gws-forms

Dale entradas con forma de API

Los mejores resultados llegan con entradas que especifican el recurso objetivo, el método y los campos deseados. Incluye el título del formulario, si document_title debe ser distinto y si vas a crear un formulario nuevo, leer uno existente o actualizarlo. Por ejemplo, “Crea un formulario titulado X, déjalo vacío y luego añade 5 preguntas de opción múltiple” es mucho más sólido que “arma una encuesta”.

Respeta el comportamiento de crear y luego actualizar

Un fallo común es pedir un formulario completo en un solo paso cuando la API solo permite datos parciales en la creación. El repositorio señala que forms.create solo copia form.info.title y form.info.document_title, y no admite descripción, elementos ni settings en la creación. Mejora la calidad del resultado planificando desde el principio el segundo paso.

Usa la salida del esquema para quitar ambigüedad

Si el primer intento falla, vuelve a comprobar gws schema para ver la firma exacta del método y los nombres de los parámetros, y reescribe la solicitud con esos campos. Esta es la forma más rápida de mejorar gws-forms usage, porque reemplaza suposiciones por la misma estructura que espera el CLI.

Itera con operaciones más pequeñas

Cuando un cambio en un formulario es complejo, divídelo en acciones más pequeñas: inspeccionar, crear, actualizar, verificar. Ese flujo reduce errores en las actualizaciones en lote y facilita detectar si el problema es una entrada incorrecta, campos no compatibles o una discrepancia entre tu intención y la Forms API.