gws-docs

Read and write Google Docs.

Quality

45%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/gws-docs/SKILL.md

Quality

Content

57%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill is well-structured with good progressive disclosure and appropriate references to related skills. However, it lacks concrete executable examples for core operations (create, get, batchUpdate) and includes verbose API description text that could be trimmed. Adding at least one complete working example and tightening the resource descriptions would significantly improve it.

Suggestions

Add at least one complete executable example for a common operation (e.g., `gws docs documents create --params title='My Doc'` and `gws docs documents get --params documentId='...'`)

Trim the `batchUpdate` description to essentials — remove the explanation of validation behavior and reply ordering that Claude can discover via `gws schema`

Add a validation/verification step for batchUpdate operations (e.g., 'After batchUpdate, verify changes with a `get` call')

Dimension	Reasoning	Score
Conciseness	Mostly efficient, but the `batchUpdate` description is overly verbose with explanations Claude doesn't need (e.g., 'Each request is validated before being applied. If any request is not valid, then the entire request will fail...'). These read like API docs copy-pasted verbatim rather than distilled for Claude.	2 / 3
Actionability	Provides concrete CLI commands for discovery (`gws docs --help`, `gws schema`), but lacks executable examples of actually performing common operations like creating a doc, getting a doc, or doing a batchUpdate. The user is told to inspect methods but not shown a complete working example.	2 / 3
Workflow Clarity	The discovery workflow (browse → inspect → build flags) is present but implicit. There's no explicit step-by-step for common tasks like creating or editing a document, and no validation/verification steps for batchUpdate operations which can be destructive.	2 / 3
Progressive Disclosure	Good structure with clear references: prerequisite points to shared skill, helper command links to write skill, and discovery section is well-placed. Content is appropriately split with one-level-deep references that are clearly signaled.	3 / 3
	Total	9 / 12 Passed

Description

32%

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is too terse—it identifies the platform (Google Docs) and two high-level actions but lacks specific capabilities, trigger guidance, and natural keyword variations. It would be difficult for Claude to confidently select this skill over other document-related skills in a large skill library.

Suggestions

Add a 'Use when...' clause with explicit triggers, e.g., 'Use when the user asks to create, edit, read, or format a Google Doc, or mentions Google Docs, gdoc, or shared documents.'

List more specific concrete actions such as 'create documents, edit text, insert tables, apply formatting, extract content, and manage sharing permissions.'

Include natural keyword variations users might say, such as 'Google document', 'gdoc', 'Docs', or '.gdoc'.

Dimension	Reasoning	Score
Specificity	Names the domain (Google Docs) and two actions (read and write), but does not list more specific concrete actions like formatting, inserting tables, sharing, or commenting.	2 / 3
Completeness	Answers 'what' at a basic level (read and write Google Docs) but completely lacks any 'when' clause or explicit trigger guidance, which per the rubric caps completeness at 2, and since the 'what' is also minimal, a score of 1 is appropriate.	1 / 3
Trigger Term Quality	Includes 'Google Docs' which is a natural keyword users would say, but misses common variations like 'gdoc', 'Google document', 'Docs API', or related terms like 'edit', 'create', 'share'.	2 / 3
Distinctiveness Conflict Risk	Specifying 'Google Docs' provides some distinctiveness from generic document skills, but could overlap with other Google Workspace skills or general document editing skills without clearer trigger boundaries.	2 / 3
	Total	7 / 12 Passed

Validation

90%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
metadata_field	'metadata' should map string keys to string values	Warning

	Total	10 / 11 Passed

Repository: googleworkspace/cli
Commit: a3768d0

Reviewed: 3 months ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.