@ngxtm/devkit 3.15.0 → 3.17.0

package/skills/google-calendar-automation/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: google-calendar-automation
+description: "Automate Google Calendar events, scheduling, availability checks, and attendee management via Rube MCP (Composio). Create events, find free slots, manage attendees, and list calendars programmatica..."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# Google Calendar Automation via Rube MCP
+
+Automate Google Calendar workflows including event creation, scheduling, availability checks, attendee management, and calendar browsing through Composio's Google Calendar toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Google Calendar connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `googlecalendar`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `googlecalendar`
+3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Create and Manage Events
+
+**When to use**: User wants to create, update, or delete calendar events
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_LIST_CALENDARS` - Identify target calendar ID [Prerequisite]
+2. `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` - Get current time with proper timezone [Optional]
+3. `GOOGLECALENDAR_FIND_FREE_SLOTS` - Check availability before booking [Optional]
+4. `GOOGLECALENDAR_CREATE_EVENT` - Create the event [Required]
+5. `GOOGLECALENDAR_PATCH_EVENT` - Update specific fields of an existing event [Alternative]
+6. `GOOGLECALENDAR_UPDATE_EVENT` - Full replacement update of an event [Alternative]
+7. `GOOGLECALENDAR_DELETE_EVENT` - Delete an event [Optional]
+
+**Key parameters**:
+- `calendar_id`: Use 'primary' for main calendar, or specific calendar ID
+- `start_datetime`: ISO 8601 format 'YYYY-MM-DDTHH:MM:SS' (NOT natural language)
+- `timezone`: IANA timezone name (e.g., 'America/New_York', NOT 'EST' or 'PST')
+- `event_duration_hour`: Hours (0+)
+- `event_duration_minutes`: Minutes (0-59 only; NEVER use 60+)
+- `summary`: Event title
+- `attendees`: Array of email addresses (NOT names)
+- `location`: Free-form text for event location
+
+**Pitfalls**:
+- `start_datetime` must be ISO 8601; natural language like 'tomorrow' is rejected
+- `event_duration_minutes` max is 59; use `event_duration_hour=1` instead of `event_duration_minutes=60`
+- `timezone` must be IANA identifier; abbreviations like 'EST', 'PST' are NOT valid
+- `attendees` only accepts email addresses, not names; resolve names first
+- Google Meet link creation defaults to true; may fail on personal Gmail accounts (graceful fallback)
+- Organizer is auto-added as attendee unless `exclude_organizer=true`
+
+### 2. List and Search Events
+
+**When to use**: User wants to find or browse events on their calendar
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_LIST_CALENDARS` - Get available calendars [Prerequisite]
+2. `GOOGLECALENDAR_FIND_EVENT` - Search by title/keyword with time bounds [Required]
+3. `GOOGLECALENDAR_EVENTS_LIST` - List events in a time range [Alternative]
+4. `GOOGLECALENDAR_EVENTS_INSTANCES` - List instances of a recurring event [Optional]
+
+**Key parameters**:
+- `query` / `q`: Free-text search (matches summary, description, location, attendees)
+- `timeMin`: Lower bound (RFC3339 with timezone offset, e.g., '2024-01-01T00:00:00-08:00')
+- `timeMax`: Upper bound (RFC3339 with timezone offset)
+- `singleEvents`: true to expand recurring events into instances
+- `orderBy`: 'startTime' (requires singleEvents=true) or 'updated'
+- `maxResults`: Results per page (max 2500)
+
+**Pitfalls**:
+- **Timezone warning**: UTC timestamps (ending in 'Z') don't align with local dates; use local timezone offsets instead
+- Example: '2026-01-19T00:00:00Z' covers 2026-01-18 4pm to 2026-01-19 4pm in PST
+- Omitting `timeMin`/`timeMax` scans the full calendar and can be slow
+- `pageToken` in response means more results; paginate until absent
+- `orderBy='startTime'` requires `singleEvents=true`
+
+### 3. Manage Attendees and Invitations
+
+**When to use**: User wants to add, remove, or update event attendees
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_FIND_EVENT` or `GOOGLECALENDAR_EVENTS_LIST` - Find the event [Prerequisite]
+2. `GOOGLECALENDAR_PATCH_EVENT` - Add attendees (replaces entire attendees list) [Required]
+3. `GOOGLECALENDAR_REMOVE_ATTENDEE` - Remove a specific attendee by email [Required]
+
+**Key parameters**:
+- `event_id`: Unique event identifier (opaque string, NOT the event title)
+- `attendees`: Full list of attendee emails (PATCH replaces entire list)
+- `attendee_email`: Email to remove
+- `send_updates`: 'all', 'externalOnly', or 'none'
+
+**Pitfalls**:
+- `event_id` is a technical identifier, NOT the event title; always search first to get the ID
+- `PATCH_EVENT` attendees field replaces the entire list; include existing attendees to avoid removing them
+- Attendee names cannot be resolved; always use email addresses
+- Use `GMAIL_SEARCH_PEOPLE` to resolve names to emails before managing attendees
+
+### 4. Check Availability and Free/Busy Status
+
+**When to use**: User wants to find available time slots or check busy periods
+
+**Tool sequence**:
+1. `GOOGLECALENDAR_LIST_CALENDARS` - Identify calendars to check [Prerequisite]
+2. `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` - Get current time with timezone [Optional]
+3. `GOOGLECALENDAR_FIND_FREE_SLOTS` - Find free intervals across calendars [Required]
+4. `GOOGLECALENDAR_FREE_BUSY_QUERY` - Get raw busy periods for computing gaps [Fallback]
+5. `GOOGLECALENDAR_CREATE_EVENT` - Book a confirmed slot [Required]
+
+**Key parameters**:
+- `items`: List of calendar IDs to check (e.g., ['primary'])
+- `time_min`/`time_max`: Query interval (defaults to current day if omitted)
+- `timezone`: IANA timezone for interpreting naive timestamps
+- `calendarExpansionMax`: Max calendars (1-50)
+- `groupExpansionMax`: Max members per group (1-100)
+
+**Pitfalls**:
+- Maximum span ~90 days per Google Calendar freeBusy API limit
+- Very long ranges or inaccessible calendars yield empty/invalid results
+- Only calendars with at least freeBusyReader access are visible
+- Free slots responses may normalize to UTC ('Z'); check offsets
+- `GOOGLECALENDAR_FREE_BUSY_QUERY` requires RFC3339 timestamps with timezone
+
+## Common Patterns
+
+### ID Resolution
+- **Calendar name -> calendar_id**: `GOOGLECALENDAR_LIST_CALENDARS` to enumerate all calendars
+- **Event title -> event_id**: `GOOGLECALENDAR_FIND_EVENT` or `GOOGLECALENDAR_EVENTS_LIST`
+- **Attendee name -> email**: `GMAIL_SEARCH_PEOPLE`
+
+### Timezone Handling
+- Always use IANA timezone identifiers (e.g., 'America/Los_Angeles')
+- Use `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` to get current time in user's timezone
+- When querying events for a local date, use timestamps with local offset, NOT UTC
+- Example: '2026-01-19T00:00:00-08:00' for PST, NOT '2026-01-19T00:00:00Z'
+
+### Pagination
+- `GOOGLECALENDAR_EVENTS_LIST` returns `nextPageToken`; iterate until absent
+- `GOOGLECALENDAR_LIST_CALENDARS` also paginates; use `page_token`
+
+## Known Pitfalls
+
+- **Natural language dates**: NOT supported; all dates must be ISO 8601 or RFC3339
+- **Timezone mismatch**: UTC timestamps don't align with local dates for filtering
+- **Duration limits**: `event_duration_minutes` max 59; use hours for longer durations
+- **IANA timezones only**: 'EST', 'PST', etc. are NOT valid; use 'America/New_York'
+- **Event IDs are opaque**: Always search to get event_id; never guess or construct
+- **Attendees as emails**: Names cannot be used; resolve with GMAIL_SEARCH_PEOPLE
+- **PATCH replaces attendees**: Include all desired attendees in the array, not just new ones
+- **Conference limitations**: Google Meet may fail on personal accounts (graceful fallback)
+- **Rate limits**: High-volume searches can trigger 403/429; throttle between calls
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List calendars | `GOOGLECALENDAR_LIST_CALENDARS` | `max_results` |
+| Create event | `GOOGLECALENDAR_CREATE_EVENT` | `start_datetime`, `timezone`, `summary` |
+| Update event | `GOOGLECALENDAR_PATCH_EVENT` | `calendar_id`, `event_id`, fields to update |
+| Delete event | `GOOGLECALENDAR_DELETE_EVENT` | `calendar_id`, `event_id` |
+| Search events | `GOOGLECALENDAR_FIND_EVENT` | `query`, `timeMin`, `timeMax` |
+| List events | `GOOGLECALENDAR_EVENTS_LIST` | `calendarId`, `timeMin`, `timeMax` |
+| Recurring instances | `GOOGLECALENDAR_EVENTS_INSTANCES` | `calendarId`, `eventId` |
+| Find free slots | `GOOGLECALENDAR_FIND_FREE_SLOTS` | `items`, `time_min`, `time_max`, `timezone` |
+| Free/busy query | `GOOGLECALENDAR_FREE_BUSY_QUERY` | `timeMin`, `timeMax`, `items` |
+| Remove attendee | `GOOGLECALENDAR_REMOVE_ATTENDEE` | `event_id`, `attendee_email` |
+| Get current time | `GOOGLECALENDAR_GET_CURRENT_DATE_TIME` | `timezone` |
+| Get calendar | `GOOGLECALENDAR_GET_CALENDAR` | `calendar_id` |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/google-drive-automation/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: google-drive-automation
+description: "Automate Google Drive file operations (upload, download, search, share, organize) via Rube MCP (Composio). Upload/download files, manage folders, share with permissions, and search across drives pr..."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# Google Drive Automation via Rube MCP
+
+Automate Google Drive workflows including file upload/download, search, folder management, sharing/permissions, and organization through Composio's Google Drive toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Google Drive connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `googledrive`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `googledrive`
+3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Upload and Download Files
+
+**When to use**: User wants to upload files to or download files from Google Drive
+
+**Tool sequence**:
+1. `GOOGLEDRIVE_FIND_FILE` - Locate target folder for upload [Prerequisite]
+2. `GOOGLEDRIVE_UPLOAD_FILE` - Upload a file (max 5MB) [Required]
+3. `GOOGLEDRIVE_RESUMABLE_UPLOAD` - Upload large files [Fallback]
+4. `GOOGLEDRIVE_DOWNLOAD_FILE` - Download a file by ID [Required]
+5. `GOOGLEDRIVE_DOWNLOAD_FILE_OPERATION` - Track long-running downloads [Fallback]
+6. `GOOGLEDRIVE_GET_FILE_METADATA` - Verify file after upload/download [Optional]
+
+**Key parameters**:
+- `file_to_upload`: Object with `name`, `mimetype`, and `s3key` (file must be in internal storage)
+- `folder_to_upload_to`: Target folder ID (optional; uploads to root if omitted)
+- `file_id`: ID of file to download
+- `mime_type`: Export format for Google Workspace files only (omit for native files)
+
+**Pitfalls**:
+- `GOOGLEDRIVE_UPLOAD_FILE` requires `file_to_upload.s3key`; files must already be in internal storage
+- For non-Google formats (Excel, PDF), do NOT set `mime_type`; it causes errors for native files
+- Download responses provide a temporary URL at `data.downloaded_file_content.s3url`, not inline bytes
+- Use `GOOGLEDRIVE_RESUMABLE_UPLOAD` for files >5MB or when basic uploads fail
+
+### 2. Search and List Files
+
+**When to use**: User wants to find specific files or browse Drive contents
+
+**Tool sequence**:
+1. `GOOGLEDRIVE_FIND_FILE` - Search by name, content, type, date, or folder [Required]
+2. `GOOGLEDRIVE_LIST_FILES` - Browse files with folder scoping [Alternative]
+3. `GOOGLEDRIVE_LIST_SHARED_DRIVES` - Enumerate shared drives [Optional]
+4. `GOOGLEDRIVE_GET_FILE_METADATA` - Get detailed file info [Optional]
+5. `GOOGLEDRIVE_GET_ABOUT` - Check storage quota and supported formats [Optional]
+
+**Key parameters**:
+- `q`: Drive query string (e.g., "name contains 'report'", "mimeType = 'application/pdf'")
+- `corpora`: Search scope ('user', 'domain', 'drive', 'allDrives')
+- `fields`: Response fields to include (e.g., 'files(id,name,mimeType)')
+- `orderBy`: Sort key ('modifiedTime desc', 'name', 'quotaBytesUsed desc')
+- `pageSize`: Results per page (max 1000)
+- `pageToken`: Pagination cursor from `nextPageToken`
+- `folder_id`: Scope search to a specific folder
+
+**Pitfalls**:
+- 403 PERMISSION_DENIED if OAuth scopes insufficient for shared drives
+- Pagination required; files are in `response.data.files`; follow `nextPageToken` until exhausted
+- `corpora="domain"` may trigger 400; try `"allDrives"` with `includeItemsFromAllDrives=true`
+- Query complexity limits: >5-10 OR clauses may error "The query is too complex"
+- Wildcards (*) NOT supported in `name`; use `contains` for partial matching
+- 'My Drive' is NOT searchable by name; use `folder_id='root'` for root folder
+- User email searches: use `'user@example.com' in owners` (NOT `owner:user@example.com`)
+
+### 3. Share Files and Manage Permissions
+
+**When to use**: User wants to share files or manage access permissions
+
+**Tool sequence**:
+1. `GOOGLEDRIVE_FIND_FILE` - Locate the file to share [Prerequisite]
+2. `GOOGLEDRIVE_ADD_FILE_SHARING_PREFERENCE` - Set sharing permission [Required]
+3. `GOOGLEDRIVE_LIST_PERMISSIONS` - View current permissions [Optional]
+4. `GOOGLEDRIVE_GET_PERMISSION` - Inspect a specific permission [Optional]
+5. `GOOGLEDRIVE_UPDATE_PERMISSION` - Modify existing permission [Optional]
+6. `GOOGLEDRIVE_DELETE_PERMISSION` - Revoke access [Optional]
+
+**Key parameters**:
+- `file_id`: ID of file to share
+- `type`: 'user', 'group', 'domain', or 'anyone'
+- `role`: 'owner', 'organizer', 'fileOrganizer', 'writer', 'commenter', 'reader'
+- `email_address`: Required for type='user' or 'group'
+- `domain`: Required for type='domain'
+- `transfer_ownership`: Required when role='owner'
+
+**Pitfalls**:
+- Invalid type/email combinations trigger 4xx errors
+- Using `type='anyone'` or powerful roles is risky; get explicit user confirmation
+- Org policies may block certain sharing types, causing 403
+- Permission changes may take time to propagate
+- Use `GMAIL_SEARCH_PEOPLE` to resolve contact names to emails before sharing
+
+### 4. Create and Organize Folders
+
+**When to use**: User wants to create folder structures or move files between folders
+
+**Tool sequence**:
+1. `GOOGLEDRIVE_FIND_FILE` - Check if folder already exists [Prerequisite]
+2. `GOOGLEDRIVE_CREATE_FOLDER` - Create a new folder [Required]
+3. `GOOGLEDRIVE_GET_FILE_METADATA` - Verify created folder [Optional]
+4. `GOOGLEDRIVE_MOVE_FILE` - Move files between folders [Optional]
+5. `GOOGLEDRIVE_UPDATE_FILE_PUT` - Update file metadata/parents [Alternative]
+
+**Key parameters**:
+- `name`: Folder name
+- `parent_id`: Parent folder ID (NOT name); omit for root
+- `file_id`: File to move
+- `add_parents`: Destination folder ID for move
+- `remove_parents`: Source folder ID to remove from
+
+**Pitfalls**:
+- `GOOGLEDRIVE_CREATE_FOLDER` requires `parent_id` as an ID, not a folder name
+- Using `parent_id="root"` creates at top level; for nested paths, chain folder IDs
+- `GOOGLEDRIVE_FIND_FILE` returns ~100 items/page; follow `nextPageToken` for large drives
+- Move operations can leave items with multiple parents; use `remove_parents` for true moves
+- Always verify parent folder exists before creating children
+
+## Common Patterns
+
+### ID Resolution
+- **File/folder name -> ID**: `GOOGLEDRIVE_FIND_FILE` with `q` parameter
+- **Root folder**: Use `folder_id='root'` or `'root' in parents`
+- **Shared drive -> driveId**: `GOOGLEDRIVE_LIST_SHARED_DRIVES`
+- **Contact name -> email**: `GMAIL_SEARCH_PEOPLE` (for sharing)
+
+### Query Syntax
+Google Drive uses a specific query language:
+- Name search: `"name contains 'report'"` or `"name = 'exact.pdf'"`
+- Type filter: `"mimeType = 'application/pdf'"` or `"mimeType = 'application/vnd.google-apps.folder'"`
+- Folder scoping: `"'FOLDER_ID' in parents"`
+- Date filter: `"modifiedTime > '2024-01-01T00:00:00'"`
+- Combine with `and`/`or`/`not`: `"name contains 'report' and trashed = false"`
+- Boolean filters: `"sharedWithMe = true"`, `"starred = true"`, `"trashed = false"`
+
+### Pagination
+- Follow `nextPageToken` until absent for complete results
+- Set `pageSize` explicitly (default 100, max 1000)
+- De-duplicate results if running multiple searches
+
+### Export Formats
+For Google Workspace files, set `mime_type` to export:
+- **Docs**: `application/pdf`, `text/plain`, `text/html`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
+- **Sheets**: `text/csv`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
+- **Slides**: `application/pdf`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`
+
+## Known Pitfalls
+
+- **Internal storage required**: Upload requires files in internal S3 storage (s3key)
+- **Export vs download**: Set `mime_type` ONLY for Google Workspace files; omit for native files
+- **Temporary URLs**: Downloaded content via `s3url` is temporary; fetch promptly
+- **Query complexity**: >5-10 OR clauses may error; split complex searches into multiple queries
+- **Shared drive scoping**: Missing drive permissions yield empty results; verify access first
+- **No wildcards**: Use `contains` operator instead of `*` for partial name matching
+- **Folder creation chains**: Always pass folder IDs (not names) as `parent_id`
+- **Multiple parents**: Move operations may leave items with multiple parents; use `remove_parents`
+- **Rate limits**: Heavy searches/exports can trigger 403/429; implement backoff
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Search files | `GOOGLEDRIVE_FIND_FILE` | `q`, `corpora`, `pageSize` |
+| List files | `GOOGLEDRIVE_LIST_FILES` | `folderId`, `q`, `orderBy` |
+| Upload file | `GOOGLEDRIVE_UPLOAD_FILE` | `file_to_upload`, `folder_to_upload_to` |
+| Resumable upload | `GOOGLEDRIVE_RESUMABLE_UPLOAD` | file data |
+| Download file | `GOOGLEDRIVE_DOWNLOAD_FILE` | `file_id`, `mime_type` (Workspace only) |
+| File metadata | `GOOGLEDRIVE_GET_FILE_METADATA` | `fileId`, `fields` |
+| Create folder | `GOOGLEDRIVE_CREATE_FOLDER` | `name`, `parent_id` |
+| Move file | `GOOGLEDRIVE_MOVE_FILE` | `file_id`, `add_parents`, `remove_parents` |
+| Share file | `GOOGLEDRIVE_ADD_FILE_SHARING_PREFERENCE` | `file_id`, `role`, `type`, `email_address` |
+| List permissions | `GOOGLEDRIVE_LIST_PERMISSIONS` | `fileId` |
+| Update permission | `GOOGLEDRIVE_UPDATE_PERMISSION` | file_id, permission_id |
+| Delete permission | `GOOGLEDRIVE_DELETE_PERMISSION` | file_id, permission_id |
+| List shared drives | `GOOGLEDRIVE_LIST_SHARED_DRIVES` | `pageSize` |
+| Drive info | `GOOGLEDRIVE_GET_ABOUT` | (none) |
+| Create shortcut | `GOOGLEDRIVE_CREATE_SHORTCUT_TO_FILE` | target file_id |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/googlesheets-automation/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: googlesheets-automation
+description: "Automate Google Sheets operations (read, write, format, filter, manage spreadsheets) via Rube MCP (Composio). Read/write data, manage tabs, apply formatting, and search rows programmatically."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# Google Sheets Automation via Rube MCP
+
+Automate Google Sheets workflows including reading/writing data, managing spreadsheets and tabs, formatting cells, filtering rows, and upserting records through Composio's Google Sheets toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Google Sheets connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `googlesheets`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `googlesheets`
+3. If connection is not ACTIVE, follow the returned auth link to complete Google OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Read and Write Data
+
+**When to use**: User wants to read data from or write data to a Google Sheet
+
+**Tool sequence**:
+1. `GOOGLESHEETS_SEARCH_SPREADSHEETS` - Find spreadsheet by name if ID unknown [Prerequisite]
+2. `GOOGLESHEETS_GET_SHEET_NAMES` - Enumerate tab names to target the right sheet [Prerequisite]
+3. `GOOGLESHEETS_BATCH_GET` - Read data from one or more ranges [Required]
+4. `GOOGLESHEETS_BATCH_UPDATE` - Write data to a range or append rows [Required]
+5. `GOOGLESHEETS_VALUES_UPDATE` - Update a single specific range [Alternative]
+6. `GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND` - Append rows to end of table [Alternative]
+
+**Key parameters**:
+- `spreadsheet_id`: Alphanumeric ID from the spreadsheet URL (between '/d/' and '/edit')
+- `ranges`: A1 notation array (e.g., 'Sheet1!A1:Z1000'); always use bounded ranges
+- `sheet_name`: Tab name (case-insensitive matching supported)
+- `values`: 2D array where each inner array is a row
+- `first_cell_location`: Starting cell in A1 notation (omit to append)
+- `valueInputOption`: 'USER_ENTERED' (parsed) or 'RAW' (literal)
+
+**Pitfalls**:
+- Mis-cased or non-existent tab names error "Sheet 'X' not found"
+- Empty ranges may omit `valueRanges[i].values`; treat missing as empty array
+- `GOOGLESHEETS_BATCH_UPDATE` values must be a 2D array (list of lists), even for a single row
+- Unbounded ranges like 'A:Z' on sheets with >10,000 rows may cause timeouts; always bound with row limits
+- Append follows the detected `tableRange`; use returned `updatedRange` to verify placement
+
+### 2. Create and Manage Spreadsheets
+
+**When to use**: User wants to create a new spreadsheet or manage tabs within one
+
+**Tool sequence**:
+1. `GOOGLESHEETS_CREATE_GOOGLE_SHEET1` - Create a new spreadsheet [Required]
+2. `GOOGLESHEETS_ADD_SHEET` - Add a new tab/worksheet [Required]
+3. `GOOGLESHEETS_UPDATE_SHEET_PROPERTIES` - Rename, hide, reorder, or color tabs [Optional]
+4. `GOOGLESHEETS_GET_SPREADSHEET_INFO` - Get full spreadsheet metadata [Optional]
+5. `GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE` - Check if a specific tab exists [Optional]
+
+**Key parameters**:
+- `title`: Spreadsheet or sheet tab name
+- `spreadsheetId`: Target spreadsheet ID
+- `forceUnique`: Auto-append suffix if tab name exists (default true)
+- `properties.gridProperties`: Set row/column counts, frozen rows
+
+**Pitfalls**:
+- Sheet names must be unique within a spreadsheet
+- Default sheet names are locale-dependent ('Sheet1' in English, 'Hoja 1' in Spanish)
+- Don't use `index` when creating multiple sheets in parallel (causes 'index too high' errors)
+- `GOOGLESHEETS_GET_SPREADSHEET_INFO` can return 403 if account lacks access
+
+### 3. Search and Filter Rows
+
+**When to use**: User wants to find specific rows or apply filters to sheet data
+
+**Tool sequence**:
+1. `GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW` - Find first row matching exact cell value [Required]
+2. `GOOGLESHEETS_SET_BASIC_FILTER` - Apply filter/sort to a range [Alternative]
+3. `GOOGLESHEETS_CLEAR_BASIC_FILTER` - Remove existing filter [Optional]
+4. `GOOGLESHEETS_BATCH_GET` - Read filtered results [Optional]
+
+**Key parameters**:
+- `query`: Exact text value to match (matches entire cell content)
+- `range`: A1 notation range to search within
+- `case_sensitive`: Boolean for case-sensitive matching (default false)
+- `filter.range`: Grid range with sheet_id for basic filter
+- `filter.criteria`: Column-based filter conditions
+- `filter.sortSpecs`: Sort specifications
+
+**Pitfalls**:
+- `GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW` matches entire cell content, not substrings
+- Sheet names with spaces must be single-quoted in ranges (e.g., "'My Sheet'!A:Z")
+- Bare sheet names without ranges are not supported for lookup; always specify a range
+
+### 4. Upsert Rows by Key
+
+**When to use**: User wants to update existing rows or insert new ones based on a unique key column
+
+**Tool sequence**:
+1. `GOOGLESHEETS_UPSERT_ROWS` - Update matching rows or append new ones [Required]
+
+**Key parameters**:
+- `spreadsheetId`: Target spreadsheet ID
+- `sheetName`: Tab name
+- `keyColumn`: Column header name used as unique identifier (e.g., 'Email', 'SKU')
+- `headers`: List of column names for the data
+- `rows`: 2D array of data rows
+- `strictMode`: Error on mismatched column counts (default true)
+
+**Pitfalls**:
+- `keyColumn` must be an actual header name, NOT a column letter (e.g., 'Email' not 'A')
+- If `headers` is NOT provided, first row of `rows` is treated as headers
+- With `strictMode=true`, rows with more values than headers cause an error
+- Auto-adds missing columns to the sheet
+
+### 5. Format Cells
+
+**When to use**: User wants to apply formatting (bold, colors, font size) to cells
+
+**Tool sequence**:
+1. `GOOGLESHEETS_GET_SPREADSHEET_INFO` - Get numeric sheetId for target tab [Prerequisite]
+2. `GOOGLESHEETS_FORMAT_CELL` - Apply formatting to a range [Required]
+3. `GOOGLESHEETS_UPDATE_SHEET_PROPERTIES` - Change frozen rows, column widths [Optional]
+
+**Key parameters**:
+- `spreadsheet_id`: Spreadsheet ID
+- `worksheet_id`: Numeric sheetId (NOT tab name); get from GET_SPREADSHEET_INFO
+- `range`: A1 notation (e.g., 'A1:F1') - preferred over index fields
+- `bold`, `italic`, `underline`, `strikethrough`: Boolean formatting options
+- `red`, `green`, `blue`: Background color as 0.0-1.0 floats (NOT 0-255 ints)
+- `fontSize`: Font size in points
+
+**Pitfalls**:
+- Requires numeric `worksheet_id`, not tab title; get from spreadsheet metadata
+- Color channels are 0-1 floats (e.g., 1.0 for full red), NOT 0-255 integers
+- Responses may return empty reply objects ([{}]); verify formatting via readback
+- Format one range per call; batch formatting requires separate calls
+
+## Common Patterns
+
+### ID Resolution
+- **Spreadsheet name -> ID**: `GOOGLESHEETS_SEARCH_SPREADSHEETS` with `query`
+- **Tab name -> sheetId**: `GOOGLESHEETS_GET_SPREADSHEET_INFO`, extract from sheets metadata
+- **Tab existence check**: `GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE`
+
+### Rate Limits
+Google Sheets enforces strict rate limits:
+- Max 60 reads/minute and 60 writes/minute
+- Exceeding limits causes errors; batch operations where possible
+- Use `GOOGLESHEETS_BATCH_GET` and `GOOGLESHEETS_BATCH_UPDATE` for efficiency
+
+### Data Patterns
+- Always read before writing to understand existing layout
+- Use `GOOGLESHEETS_UPSERT_ROWS` for CRM syncs, inventory updates, and dedup scenarios
+- Append mode (omit `first_cell_location`) is safest for adding new records
+- Use `GOOGLESHEETS_CLEAR_VALUES` to clear content while preserving formatting
+
+## Known Pitfalls
+
+- **Tab names**: Locale-dependent defaults; 'Sheet1' may not exist in non-English accounts
+- **Range notation**: Sheet names with spaces need single quotes in A1 notation
+- **Unbounded ranges**: Can timeout on large sheets; always specify row bounds (e.g., 'A1:Z10000')
+- **2D arrays**: All value parameters must be list-of-lists, even for single rows
+- **Color values**: Floats 0.0-1.0, not integers 0-255
+- **Formatting IDs**: `FORMAT_CELL` needs numeric sheetId, not tab title
+- **Rate limits**: 60 reads/min and 60 writes/min; batch to stay within limits
+- **Delete dimension**: `GOOGLESHEETS_DELETE_DIMENSION` is irreversible; double-check bounds
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| Search spreadsheets | `GOOGLESHEETS_SEARCH_SPREADSHEETS` | `query`, `search_type` |
+| Create spreadsheet | `GOOGLESHEETS_CREATE_GOOGLE_SHEET1` | `title` |
+| List tabs | `GOOGLESHEETS_GET_SHEET_NAMES` | `spreadsheet_id` |
+| Add tab | `GOOGLESHEETS_ADD_SHEET` | `spreadsheetId`, `title` |
+| Read data | `GOOGLESHEETS_BATCH_GET` | `spreadsheet_id`, `ranges` |
+| Read single range | `GOOGLESHEETS_VALUES_GET` | `spreadsheet_id`, `range` |
+| Write data | `GOOGLESHEETS_BATCH_UPDATE` | `spreadsheet_id`, `sheet_name`, `values` |
+| Update range | `GOOGLESHEETS_VALUES_UPDATE` | `spreadsheet_id`, `range`, `values` |
+| Append rows | `GOOGLESHEETS_SPREADSHEETS_VALUES_APPEND` | `spreadsheetId`, `range`, `values` |
+| Upsert rows | `GOOGLESHEETS_UPSERT_ROWS` | `spreadsheetId`, `sheetName`, `keyColumn`, `rows` |
+| Lookup row | `GOOGLESHEETS_LOOKUP_SPREADSHEET_ROW` | `spreadsheet_id`, `query` |
+| Format cells | `GOOGLESHEETS_FORMAT_CELL` | `spreadsheet_id`, `worksheet_id`, `range` |
+| Set filter | `GOOGLESHEETS_SET_BASIC_FILTER` | `spreadsheetId`, `filter` |
+| Clear values | `GOOGLESHEETS_CLEAR_VALUES` | `spreadsheet_id`, range |
+| Delete rows/cols | `GOOGLESHEETS_DELETE_DIMENSION` | `spreadsheet_id`, `sheet_name`, dimension |
+| Spreadsheet info | `GOOGLESHEETS_GET_SPREADSHEET_INFO` | `spreadsheet_id` |
+| Update tab props | `GOOGLESHEETS_UPDATE_SHEET_PROPERTIES` | `spreadsheetId`, properties |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/skills/grafana-dashboards/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: grafana-dashboards
-description: Create and manage production Grafana dashboards for real-time visualization of system and application metrics. Use when building monitoring dashboards, visualizing metrics, or creating operational observability interfaces.
+description: "Create and manage production Grafana dashboards for real-time visualization of system and application metrics. Use when building monitoring dashboards, visualizing metrics, or creating operational ..."
+risk: unknown
+source: community
 ---
 
 # Grafana Dashboards

package/skills/graphql/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: graphql
-description: "GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper controls, clients can craft queries that bring down your server.  This skill covers schema design, resolvers, DataLoader for N+1 prevention, federation for microservices, and client integration with Apollo/urql. Key insight: GraphQL is a contract. The schema is the API documentation. Design it carefully."
+description: "GraphQL gives clients exactly the data they need - no more, no less. One endpoint, typed schema, introspection. But the flexibility that makes it powerful also makes it dangerous. Without proper co..."
 source: vibeship-spawner-skills (Apache 2.0)
+risk: unknown
 ---
 
 # GraphQL
@@ -66,3 +67,6 @@ Normalized cache with type policies
 ## Related Skills
 
 Works well with: `backend`, `postgres-wizard`, `nextjs-app-router`, `react-patterns`
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.