feat: improve 88 skills descriptions, examples, and validation

skills/gws-admin-reports/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gws-admin-reports
 version: 1.0.0
-description: "Google Workspace Admin SDK: Audit logs and usage reports."
+description: "Google Workspace Admin SDK reports_v1 skill. Retrieves audit logs, generates usage reports, tracks user activity, monitors login events, and exports admin data for a Google Workspace (G Suite) account. Covers activities, channels, customer usage, entity usage, and per-user usage. Use when the user asks about Google Workspace or G Suite admin tasks such as user activity logs, login history, security events, admin console reports, Google Drive activity, push notifications for account changes, or any G Suite administration reporting need."
 metadata:
   openclaw:
     category: "productivity"
@@ -22,24 +22,24 @@ gws admin-reports <resource> <method> [flags]
 
 ### activities
 
-  - `list` — Retrieves a list of activities for a specific customer's account and application such as the Admin console application or the Google Drive application. For more information, see the guides for administrator and Google Drive activity reports. For more information about the activity report's parameters, see the activity parameters reference guides.
-  - `watch` — Start receiving notifications for account activities. For more information, see Receiving Push Notifications.
+- `list` — Retrieves a list of activities for a specific customer's account and application (e.g., Admin console, Google Drive). Use for audit logs, login history, and security events.
+- `watch` — Start receiving push notifications for account activities.
 
 ### channels
 
-  - `stop` — Stop watching resources through this channel.
+- `stop` — Stop watching resources through this channel.
 
 ### customerUsageReports
 
-  - `get` — Retrieves a report which is a collection of properties and statistics for a specific customer's account. For more information, see the Customers Usage Report guide. For more information about the customer report's parameters, see the Customers Usage parameters reference guides.
+- `get` — Retrieves a report of properties and statistics for a specific customer's account (customer-level usage metrics).
 
 ### entityUsageReports
 
-  - `get` — Retrieves a report which is a collection of properties and statistics for entities used by users within the account. For more information, see the Entities Usage Report guide. For more information about the entities report's parameters, see the Entities Usage parameters reference guides.
+- `get` — Retrieves a report of properties and statistics for entities used by users within the account (entity-level usage metrics).
 
 ### userUsageReport
 
-  - `get` — Retrieves a report which is a collection of properties and statistics for a set of users with the account. For more information, see the User Usage Report guide. For more information about the user report's parameters, see the Users Usage parameters reference guides.
+- `get` — Retrieves a report of properties and statistics for a set of users within the account (per-user usage metrics).
 
 ## Discovering Commands
 
@@ -55,3 +55,47 @@ gws schema admin-reports.<resource>.<method>
 
 Use `gws schema` output to build your `--params` and `--json` flags.
 
+## Examples
+
+### Retrieve Admin Console activity logs for a user
+
+```bash
+# Inspect the method first
+gws schema admin-reports.activities.list
+
+# List Admin console activities for a specific user
+gws admin-reports activities list \
+  --params '{"userKey": "user@example.com", "applicationName": "admin", "startTime": "2024-01-01T00:00:00Z", "endTime": "2024-01-31T23:59:59Z"}'
+```
+
+### Retrieve login history (login audit log)
+
+```bash
+gws admin-reports activities list \
+  --params '{"userKey": "all", "applicationName": "login", "maxResults": 100}'
+```
+
+### Get customer-level usage report
+
+```bash
+gws admin-reports customerUsageReports get \
+  --params '{"date": "2024-01-15"}'
+```
+
+### Set up push notifications for account activities (watch workflow)
+
+```bash
+# 1. Inspect the watch method
+gws schema admin-reports.activities.watch
+
+# 2. Start watching — supply a channel ID, token, and your webhook address
+gws admin-reports activities watch \
+  --params '{"userKey": "all", "applicationName": "admin"}' \
+  --json '{"id": "my-channel-01", "type": "web_hook", "address": "https://your-endpoint.example.com/notifications", "token": "my-secret-token"}'
+
+# 3. Validate: confirm your endpoint receives the sync message Google sends on registration
+
+# 4. Stop watching when done (use the channel id and resourceId returned in step 2)
+gws admin-reports channels stop \
+  --json '{"id": "my-channel-01", "resourceId": "<resourceId-from-watch-response>"}'
+```

skills/gws-calendar-agenda/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gws-calendar-agenda
 version: 1.0.0
-description: "Google Calendar: Show upcoming events across all calendars."
+description: "Google Calendar agenda viewer: lists upcoming events, meetings, and appointments across all calendars using the gws CLI. Use when the user wants to check their schedule, see what's on their calendar, view today's or tomorrow's events, browse this week's agenda, or ask 'what do I have today?', 'what meetings are coming up?', or 'show my appointments'. Supports filtering by calendar name/ID and adjustable day ranges. Read-only — never creates or modifies events."
 metadata:
   openclaw:
     category: "productivity"

skills/gws-calendar-insert/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gws-calendar-insert
 version: 1.0.0
-description: "Google Calendar: Create a new event."
+description: "Google Calendar: Creates a new calendar event using the gws CLI. Use when a user wants to schedule a meeting, add an appointment, book time, block off time, set up a call, or add something to their Google Calendar (gcal). Supports setting an event title/summary, start and end times (ISO 8601/RFC3339), location, description, and one or more attendees. Common trigger phrases include 'schedule a meeting', 'create an event', 'add to my calendar', 'book time with', or 'set up an appointment'."
 metadata:
   openclaw:
     category: "productivity"

skills/gws-calendar/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gws-calendar
 version: 1.0.0
-description: "Google Calendar: Manage calendars and events."
+description: "Google Calendar CLI skill via the `gws` tool. Manages calendars and events: create events, check availability, schedule meetings, view upcoming appointments, set reminders, manage access control, and query free/busy time across calendars. Use when asked to schedule a meeting, book time, create a calendar invite, check gcal, view appointments, check availability, manage a calendar, or interact with Google Calendar in any way."
 metadata:
   openclaw:
     category: "productivity"
@@ -106,3 +106,51 @@ gws schema calendar.<resource>.<method>
 
 Use `gws schema` output to build your `--params` and `--json` flags.
 
+## Example Workflows
+
+### List upcoming events on the primary calendar
+
+```bash
+# 1. Inspect the method to learn required params and available flags
+gws schema calendar.events.list
+
+# 2. List events from now, ordered by start time
+gws calendar events list \
+  --params calendarId=primary \
+  --params timeMin=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
+  --params orderBy=startTime \
+  --params singleEvents=true \
+  --params maxResults=10
+```
+
+### Create a new event
+
+```bash
+# 1. Inspect the insert method for required fields
+gws schema calendar.events.insert
+
+# 2. Create the event with a JSON body
+gws calendar events insert \
+  --params calendarId=primary \
+  --json '{
+    "summary": "Team standup",
+    "start": {"dateTime": "2024-06-10T09:00:00-07:00"},
+    "end":   {"dateTime": "2024-06-10T09:30:00-07:00"},
+    "attendees": [{"email": "colleague@example.com"}]
+  }'
+```
+
+### Query free/busy availability
+
+```bash
+# 1. Inspect the freebusy.query method
+gws schema calendar.freebusy.query
+
+# 2. Check availability for a calendar over a time window
+gws calendar freebusy query \
+  --json '{
+    "timeMin": "2024-06-10T00:00:00Z",
+    "timeMax": "2024-06-10T23:59:59Z",
+    "items":   [{"id": "primary"}]
+  }'
+```

skills/gws-chat-send/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gws-chat-send
 version: 1.0.0
-description: "Google Chat: Send a message to a space."
+description: "Google Chat: Send a plain-text message to a Google Chat space. Use when the user wants to send a message, post to a chat space, notify a team in Google Chat, or write to a gchat room. Supports plain-text messages only; for cards or threaded replies use the raw API."
 metadata:
   openclaw:
     category: "productivity"

skills/gws-chat/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gws-chat
 version: 1.0.0
-description: "Google Chat: Manage Chat spaces and messages."
+description: "Google Chat: Create and configure Chat spaces, send and read messages, list space members, manage custom emojis, upload attachments, and search conversations in Google Workspace. Use when the user mentions Google Chat, gchat, Google Workspace Chat, chat rooms, DMs, group messages, or needs to create/delete spaces, send messages, list members, or find direct message threads."
 metadata:
   openclaw:
     category: "productivity"
@@ -28,10 +28,12 @@ gws chat <resource> <method> [flags]
 
 ### customEmojis
 
-  - `create` — Creates a custom emoji. Custom emojis are only available for Google Workspace accounts, and the administrator must turn custom emojis on for the organization. For more information, see [Learn about custom emojis in Google Chat](https://support.google.com/chat/answer/12800149) and [Manage custom emoji permissions](https://support.google.com/a/answer/12850085).
-  - `delete` — Deletes a custom emoji. By default, users can only delete custom emoji they created. [Emoji managers](https://support.google.com/a/answer/12850085) assigned by the administrator can delete any custom emoji in the organization. See [Learn about custom emojis in Google Chat](https://support.google.com/chat/answer/12800149). Custom emojis are only available for Google Workspace accounts, and the administrator must turn custom emojis on for the organization.
-  - `get` — Returns details about a custom emoji. Custom emojis are only available for Google Workspace accounts, and the administrator must turn custom emojis on for the organization. For more information, see [Learn about custom emojis in Google Chat](https://support.google.com/chat/answer/12800149) and [Manage custom emoji permissions](https://support.google.com/a/answer/12850085).
-  - `list` — Lists custom emojis visible to the authenticated user. Custom emojis are only available for Google Workspace accounts, and the administrator must turn custom emojis on for the organization. For more information, see [Learn about custom emojis in Google Chat](https://support.google.com/chat/answer/12800149) and [Manage custom emoji permissions](https://support.google.com/a/answer/12850085).
+> **Note:** Custom emojis are only available for Google Workspace accounts, and the administrator must turn custom emojis on for the organization. See [Learn about custom emojis](https://support.google.com/chat/answer/12800149) and [Manage custom emoji permissions](https://support.google.com/a/answer/12850085).
+
+  - `create` — Creates a custom emoji.
+  - `delete` — Deletes a custom emoji. By default, users can only delete custom emoji they created. [Emoji managers](https://support.google.com/a/answer/12850085) assigned by the administrator can delete any custom emoji in the organization.
+  - `get` — Returns details about a custom emoji.
+  - `list` — Lists custom emojis visible to the authenticated user.
 
 ### media
 
@@ -69,5 +71,38 @@ gws chat --help
 gws schema chat.<resource>.<method>
 ```
 
-Use `gws schema` output to build your `--params` and `--json` flags.
+Use `gws schema` output to build your `--params` and `--json` flags. For example:
+
+```bash
+# 1. Inspect the schema for listing spaces
+gws schema chat.spaces.list
+# Output shows available params: pageSize, filter, etc.
 
+# 2. Build the command from the schema output
+gws chat spaces list --params '{"pageSize": 10}'
+
+# 3. Get details about a specific space
+gws chat spaces get --params '{"name": "spaces/SPACE_ID"}'
+```
+
+## Common Usage Examples
+
+```bash
+# List all Chat spaces you are a member of
+gws chat spaces list --params '{"pageSize": 25}'
+
+# Create a new named space
+gws chat spaces create --json '{"displayName": "Project Alpha", "spaceType": "SPACE"}'
+
+# Set up a space and invite members by email
+gws chat spaces setup --json '{
+  "space": {"displayName": "Team Standup"},
+  "memberships": [
+    {"member": {"name": "users/alice@example.com", "type": "HUMAN"}},
+    {"member": {"name": "users/bob@example.com", "type": "HUMAN"}}
+  ]
+}'
+
+# Find an existing direct message thread with a user
+gws chat spaces findDirectMessage --params '{"name": "users/alice@example.com"}'
+```