Skip to content

docs(skills): add COOKBOOK.md pattern for hand-written recipes alongside generated SKILL.md #420

@bishnubista

Description

@bishnubista

Problem

SKILL.md files are auto-generated by gws generate-skills and contain API method listings. However, some services have non-obvious usage patterns that require hand-written guidance — particularly around:

  • Google Docs tabs: reading specific tabs (includeTabsContent), creating tabs (addDocumentTab vs the invalid createTab), writing to specific tabs (tabId in location/range)
  • Formatted content insertion: the insert-then-style pattern with insertText + updateParagraphStyle
  • +write limitations: no tab targeting, plain text only

These patterns are hard to discover from gws schema output alone and typically require trial-and-error.

Proposal

Add a COOKBOOK.md file alongside SKILL.md in skill directories that need hand-written recipes:

```
skills/gws-docs/
SKILL.md ← auto-generated (unchanged)
COOKBOOK.md ← hand-written recipes (new)
```

Benefits:

  • Safe from regenerationgws generate-skills won't overwrite it
  • Composable — other skills can adopt the same pattern as needed
  • Discoverable — agents can check for COOKBOOK.md alongside SKILL.md

Optional follow-up: teach generate_skills.rs to append a "See also: COOKBOOK.md" link when one exists.

Scope

Starting with gws-docs as a proof of concept. The cookbook covers:

  1. Tab CRUD operations (read, create, write, rename, delete)
  2. Formatted content insertion (headings, bold/italic, paragraph styles)
  3. Valid batchUpdate request types reference table
  4. +write helper limitations and workarounds

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions