gws-forms
by googleworkspacegws-forms reads and writes Google Forms through the gws CLI for structured workflow automation. Use the gws-forms skill to inspect schemas, create empty forms, update content, and manage form operations with less guesswork.
This skill scores 67/100, which means it is listable but best framed as a limited, workflow-specific install rather than a broadly polished one. Directory users get a real Google Forms command surface with clear resource/method discovery, but they should expect some setup dependency on the shared gws skill and relatively light end-user guidance.
- Concrete triggerability: the skill defines `gws forms <resource> <method> [flags]` and points users to `gws forms --help` and `gws schema forms.<resource>.<method>`.
- Real workflow scope: it covers meaningful Forms operations like `create`, `get`, `batchUpdate`, `setPublishSettings`, `responses`, and `watches`.
- Good constraint signaling: it explains an important create flow limitation and the need to create an empty form first before adding items.
- Depends on `../gws-shared/SKILL.md` for auth, global flags, and security rules, so it is not fully self-contained.
- No install command, supporting references, or examples for common tasks, which increases adoption guesswork for new users.
Overview of gws-forms skill
What gws-forms does
gws-forms is the Google Workspace CLI skill for reading and writing Google Forms through the gws command. It helps you inspect form schemas, create empty forms, update form content in controlled steps, and manage form-related operations without guessing API fields.
Who should use it
The gws-forms skill is best for agents and users who already work in a Google Workspace automation flow and need reliable Forms API execution. It is especially useful when you want repeatable form creation, batch updates, or programmatic inspection instead of manual clicks in the Forms UI.
Why this skill matters
The main value of gws-forms for Workflow Automation is that it exposes the real API workflow, including method discovery and schema-driven input construction. That matters because form creation is not one-shot: forms.create only makes an empty form, then forms.update-style operations add items and settings.
Key limits to know
This skill is not a generic “make a form from a prompt” wrapper. It depends on the gws CLI, requires the shared Google Workspace auth and security setup, and follows the Forms API constraints in the repo. If you need broad conversational drafting rather than precise API actions, a plain prompt may be simpler.
How to Use gws-forms skill
Install and prerequisite setup
For gws-forms install, use the CLI shown in the skill metadata: npx skills add googleworkspace/cli --skill gws-forms. Before running Forms commands, read ../gws-shared/SKILL.md as instructed in the skill file, since auth, global flags, and security rules live there. If that shared file is missing, run gws generate-skills first.
Start by discovering the method
The most reliable gws-forms usage pattern is: inspect first, call second. Use gws forms --help to browse available resources and methods, then run gws schema forms.<resource>.<method> to confirm required parameters, types, and defaults before building flags. This avoids malformed requests and keeps your prompt or task aligned with the actual API shape.
Turn a rough goal into a workable request
A good gws-forms guide input says what you want at the API level, not just the business goal. For example, instead of “make a feedback form,” ask for a title, document title, the intended question types, whether the form should start empty, and whether you need publish settings or response-related actions. That gives the skill enough structure to decide whether to call forms.create, forms.batchUpdate, or another method.
Read these files and outputs first
Start with SKILL.md, then inspect the shared parent skill file and the CLI help/schema output it points to. In this repo, the skill body is compact and there are no helper folders, so SKILL.md plus gws forms --help and gws schema are the main sources of truth. If your workflow depends on adjacent Google Workspace skills, compare their patterns, but do not assume their field names or sequencing apply here.
gws-forms skill FAQ
Is gws-forms mainly for creating forms?
Yes, but only in the API sense. gws-forms supports reading and writing forms, and creation is intentionally staged: create the shell first, then add items or updates afterward. If you expect a single prompt to generate a finished form with every field populated, that is a mismatch with the repository’s workflow.
Do I need the gws CLI to use it?
Yes. The skill explicitly requires the gws binary, and the command surface shown in the skill file is gws forms <resource> <method> [flags]. If your environment cannot run the CLI or authenticate to Google Workspace, the skill will not be usable as intended.
Is this better than a normal prompt?
For API work, yes. A normal prompt can describe a form, but gws-forms skill helps execute the actual resource and method calls with schema-backed parameters, which reduces guesswork and broken requests. Use a prompt when you are brainstorming content; use this skill when you need the form action to happen.
When should I not use it?
Do not use gws-forms if you only need a quick draft of survey questions, if you lack Workspace credentials, or if you need a workflow outside the Forms API scope. It is also not the right choice when you want to skip command inspection and rely on free-form natural language alone.
How to Improve gws-forms skill
Give the skill API-shaped inputs
The best results come from inputs that specify the target resource, method, and desired fields. Include the form title, whether document_title should differ, and whether you are doing a new form, a read, or an update. For example, “Create a form titled X, keep it empty, then add 5 multiple-choice questions” is much stronger than “build a survey.”
Respect create-then-update behavior
A common failure mode is asking for a full form in one step when the API only allows partial data at creation time. The repository notes that forms.create copies only form.info.title and form.info.document_title, and disallows description, items, and settings at creation. Improve output quality by planning the second step up front.
Use schema output to remove ambiguity
If the first attempt fails, re-check gws schema for the exact method signature and param names, then rewrite the request using those fields. This is the fastest way to improve gws-forms usage because it replaces assumptions with the same structure the CLI expects.
Iterate with narrower operations
When a form change is complex, break it into smaller actions: inspect, create, update, verify. That workflow reduces errors in batch updates and makes it easier to spot whether the issue is bad input, unsupported fields, or a mismatch between your intent and the Forms API.