Adding a lot of skills for Hermes Gerhard

agents/gerhard-hermes/skills/productivity/airtable/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: airtable
+description: Airtable REST API via curl. Records CRUD, filters, upserts.
+version: 1.1.0
+author: community
+license: MIT
+prerequisites:
+  env_vars: [AIRTABLE_API_KEY]
+  commands: [curl]
+metadata:
+  hermes:
+    tags: [Airtable, Productivity, Database, API]
+    homepage: https://airtable.com/developers/web/api/introduction
+---
+
+# Airtable — Bases, Tables & Records
+
+Work with Airtable's REST API directly via `curl` using the `terminal` tool. No MCP server, no OAuth flow, no Python SDK — just `curl` and a personal access token.
+
+## Prerequisites
+
+1. Create a **Personal Access Token (PAT)** at https://airtable.com/create/tokens (tokens start with `pat...`).
+2. Grant these scopes (minimum):
+   - `data.records:read` — read rows
+   - `data.records:write` — create / update / delete rows
+   - `schema.bases:read` — list bases and tables
+3. **Important:** in the same token UI, add each base you want to access to the token's **Access** list. PATs are scoped per-base — a valid token on the wrong base returns `403`.
+4. Store the token in `~/.hermes/.env` (or via `hermes setup`):
+   ```
+   AIRTABLE_API_KEY=pat_your_token_here
+   ```
+
+> Note: legacy `key...` API keys were deprecated Feb 2024. Only PATs and OAuth tokens work now.
+
+## API Basics
+
+- **Endpoint:** `https://api.airtable.com/v0`
+- **Auth header:** `Authorization: Bearer $AIRTABLE_API_KEY`
+- **All requests** use JSON (`Content-Type: application/json` for any POST/PATCH/PUT body).
+- **Object IDs:** bases `app...`, tables `tbl...`, records `rec...`, fields `fld...`. IDs never change; names can. Prefer IDs in automations.
+- **Rate limit:** 5 requests/sec/base. `429` → back off. Burst on a single base will be throttled.
+
+Base curl pattern:
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+`-s` suppresses curl's progress bar — keep it set for every call so the tool output stays clean for Hermes. Pipe through `python3 -m json.tool` (always present) or `jq` (if installed) for readable JSON.
+
+## Field Types (request body shapes)
+
+| Field type | Write shape |
+|---|---|
+| Single line text | `"Name": "hello"` |
+| Long text | `"Notes": "multi\nline"` |
+| Number | `"Score": 42` |
+| Checkbox | `"Done": true` |
+| Single select | `"Status": "Todo"` (name must already exist unless `typecast: true`) |
+| Multi-select | `"Tags": ["urgent", "bug"]` |
+| Date | `"Due": "2026-04-01"` |
+| DateTime (UTC) | `"At": "2026-04-01T14:30:00.000Z"` |
+| URL / Email / Phone | `"Link": "https://…"` |
+| Attachment | `"Files": [{"url": "https://…"}]` (Airtable fetches + rehosts) |
+| Linked record | `"Owner": ["recXXXXXXXXXXXXXX"]` (array of record IDs) |
+| User | `"AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}` |
+
+Pass `"typecast": true` at the top level of a create/update body to let Airtable auto-coerce values (e.g. create a new select option on the fly, convert `"42"` → `42`).
+
+## Common Queries
+
+### List bases the token can see
+```bash
+curl -s "https://api.airtable.com/v0/meta/bases" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### List tables + schema for a base
+```bash
+curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+Use this BEFORE mutating — confirms exact field names and IDs, surfaces `options.choices` for select fields, and shows primary-field names.
+
+### List records (first 10)
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### Get a single record
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### Filter records (filterByFormula)
+Airtable formulas must be URL-encoded. Let Python stdlib do it — never hand-encode:
+```bash
+FORMULA="{Status}='Todo'"
+ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+Useful formula patterns:
+- Exact match: `{Email}='user@example.com'`
+- Contains: `FIND('bug', LOWER({Title}))`
+- Multiple conditions: `AND({Status}='Todo', {Priority}='High')`
+- Or: `OR({Owner}='alice', {Owner}='bob')`
+- Not empty: `NOT({Assignee}='')`
+- Date comparison: `IS_AFTER({Due}, TODAY())`
+
+### Sort + select specific fields
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+Square brackets in query params MUST be URL-encoded (`%5B` / `%5D`).
+
+### Use a named view
+```bash
+curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+Views apply their saved filter + sort server-side.
+
+## Common Mutations
+
+### Create a record
+```bash
+curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"fields":{"Name":"New task","Status":"Todo","Priority":"High"}}' | python3 -m json.tool
+```
+
+### Create up to 10 records in one call
+```bash
+curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "typecast": true,
+    "records": [
+      {"fields": {"Name": "Task A", "Status": "Todo"}},
+      {"fields": {"Name": "Task B", "Status": "In progress"}}
+    ]
+  }' | python3 -m json.tool
+```
+Batch endpoints are capped at **10 records per request**. For larger inserts, loop in batches of 10 with a short sleep to respect 5 req/sec/base.
+
+### Update a record (PATCH — merges, preserves unchanged fields)
+```bash
+curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"fields":{"Status":"Done"}}' | python3 -m json.tool
+```
+
+### Upsert by a merge field (no ID needed)
+```bash
+curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "performUpsert": {"fieldsToMergeOn": ["Email"]},
+    "records": [
+      {"fields": {"Email": "user@example.com", "Status": "Active"}}
+    ]
+  }' | python3 -m json.tool
+```
+`performUpsert` creates records whose merge-field values are new, patches records whose merge-field values already exist. Great for idempotent syncs.
+
+### Delete a record
+```bash
+curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+### Delete up to 10 records in one call
+```bash
+curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \
+  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool
+```
+
+## Pagination
+
+List endpoints return at most **100 records per page**. If the response includes `"offset": "..."`, pass it back on the next call. Loop until the field is absent:
+
+```bash
+OFFSET=""
+while :; do
+  URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100"
+  [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET"
+  RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY")
+  echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]'
+  OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))')
+  [ -z "$OFFSET" ] && break
+done
+```
+
+## Typical Hermes Workflow
+
+1. **Confirm auth.** `curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Authorization: Bearer $AIRTABLE_API_KEY"` — expect `200`.
+2. **Find the base.** List bases (step above) OR ask the user for the `app...` ID directly if the token lacks `schema.bases:read`.
+3. **Inspect the schema.** `GET /v0/meta/bases/$BASE_ID/tables` — cache the exact field names and primary-field name locally in the session before mutating anything.
+4. **Read before you write.** For "update X where Y", `filterByFormula` first to resolve the `rec...` ID, then `PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID`. Never guess record IDs.
+5. **Batch writes.** Combine related creates into one 10-record POST to stay under the 5 req/sec budget.
+6. **Destructive ops.** Deletions can't be undone via API. If the user says "delete all Xs", echo back the filter + record count and confirm before firing.
+
+## Pitfalls
+
+- **`filterByFormula` MUST be URL-encoded.** Field names with spaces or non-ASCII also need encoding (`{My Field}` → `%7BMy%20Field%7D`). Use Python stdlib (pattern above) — never hand-escape.
+- **Empty fields are omitted from responses.** A missing `"Assignee"` key doesn't mean the field doesn't exist — it means this record's value is empty. Check the schema (step 3) before concluding a field is missing.
+- **PATCH vs PUT.** `PATCH` merges supplied fields into the record. `PUT` replaces the record entirely and clears any field you didn't include. Default to `PATCH`.
+- **Single-select options must exist.** Writing `"Status": "Shipping"` when `Shipping` isn't in the field's option list errors with `INVALID_MULTIPLE_CHOICE_OPTIONS` unless you pass `"typecast": true` (which auto-creates the option).
+- **Per-base token scoping.** A `403` on one base while another works means the token's Access list doesn't include that base — not a scope or auth issue. Send the user to https://airtable.com/create/tokens to grant it.
+- **Rate limits are per base, not per token.** 5 req/sec on `baseA` and 5 req/sec on `baseB` is fine; 6 req/sec on `baseA` alone will throttle. Monitor the `Retry-After` header on `429`.
+
+## Important Notes for Hermes
+
+- **Always use the `terminal` tool with `curl`.** Do NOT use `web_extract` (it can't send auth headers) or `browser_navigate` (needs UI auth and is slow).
+- **`AIRTABLE_API_KEY` flows from `~/.hermes/.env` into the subprocess automatically** when this skill is loaded — no need to re-export it before each `curl` call.
+- **Escape curly braces in formulas carefully.** In a heredoc body, `{Status}` is literal. In a shell argument, `{Status}` is safe outside `{...}` brace-expansion context — but pass dynamic strings through `python3 urllib.parse.quote` before splicing into a URL.
+- **Pretty-print with `python3 -m json.tool`** (always present) rather than `jq` (optional). Only reach for `jq` when you need filtering/projection.
+- **Pagination is per-page, not global.** Airtable's 100-record cap is a hard limit; there is no way to bump it. Loop with `offset` until the field is absent.
+- **Read the `errors` array** on non-2xx responses — Airtable returns structured error codes like `AUTHENTICATION_REQUIRED`, `INVALID_PERMISSIONS`, `MODEL_ID_NOT_FOUND`, `INVALID_MULTIPLE_CHOICE_OPTIONS` that tell you exactly what's wrong.

agents/gerhard-hermes/skills/productivity/google-workspace/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: google-workspace
-description: Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration for Hermes. Uses Hermes-managed OAuth2 setup, prefers the Google Workspace CLI (`gws`) when available for broader API coverage, and falls back to the Python client libraries otherwise.
+description: "Gmail, Calendar, Drive, Docs, Sheets via gws CLI or Python."
 version: 1.0.0
 author: Nous Research
 license: MIT

agents/gerhard-hermes/skills/productivity/google-workspace/scripts/setup.py

@@ -289,6 +289,7 @@ def exchange_auth_code(code: str):
         sys.exit(1)
 
     pending_auth = _load_pending_auth()
+    raw_callback = code
     code, returned_state = _extract_code_and_state(code)
     if returned_state and returned_state != pending_auth["state"]:
         print("ERROR: OAuth state mismatch. Run --auth-url again to start a fresh session.")
@@ -298,19 +299,13 @@ def exchange_auth_code(code: str):
     from google_auth_oauthlib.flow import Flow
     from urllib.parse import parse_qs, urlparse
 
-    # Extract granted scopes from the callback URL if present
-    if returned_state and "scope" in parse_qs(urlparse(code).query if isinstance(code, str) and code.startswith("http") else {}):
-        granted_scopes = parse_qs(urlparse(code).query)["scope"][0].split()
-    else:
-        # Try to extract from code_or_url parameter
-        if isinstance(code, str) and code.startswith("http"):
-            params = parse_qs(urlparse(code).query)
-            if "scope" in params:
-                granted_scopes = params["scope"][0].split()
-            else:
-                granted_scopes = SCOPES
-        else:
-            granted_scopes = SCOPES
+    # Extract granted scopes from the callback URL if the user pasted the full redirect URL.
+    granted_scopes = list(SCOPES)
+    if isinstance(raw_callback, str) and raw_callback.startswith("http"):
+        params = parse_qs(urlparse(raw_callback).query)
+        scope_val = (params.get("scope") or [""])[0].strip()
+        if scope_val:
+            granted_scopes = scope_val.split()
 
     flow = Flow.from_client_secrets_file(
         str(CLIENT_SECRET_PATH),

agents/gerhard-hermes/skills/productivity/linear/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: linear
-description: Manage Linear issues, projects, and teams via the GraphQL API. Create, update, search, and organize issues. Uses API key auth (no OAuth needed). All operations via curl — no dependencies.
+description: "Linear: manage issues, projects, teams via GraphQL + curl."
 version: 1.0.0
 author: Hermes Agent
 license: MIT

agents/gerhard-hermes/skills/productivity/maps/SKILL.md

@@ -1,11 +1,6 @@
 ---
 name: maps
-description: >
-  Location intelligence — geocode a place, reverse-geocode coordinates,
-  find nearby places (46 POI categories), driving/walking/cycling
-  distance + time, turn-by-turn directions, timezone lookup, bounding
-  box + area for a named place, and POI search within a rectangle.
-  Uses OpenStreetMap + Overpass + OSRM. Free, no API key.
+description: "Geocode, POIs, routes, timezones via OpenStreetMap/OSRM."
 version: 1.2.0
 author: Mibayy
 license: MIT

agents/gerhard-hermes/skills/productivity/maps/scripts/maps_client.py

@@ -926,13 +926,18 @@ def cmd_timezone(args):
                 os_ = offset_info.get("seconds", 0)
                 sign = "+" if oh >= 0 else "-"
                 utc_offset = f"{sign}{abs(oh):02d}:{om:02d}"
+                if os_:
+                    utc_offset = f"{utc_offset}:{os_:02d}"
             elif tz_data.get("standardUtcOffset"):
                 offset_info2 = tz_data["standardUtcOffset"]
                 if isinstance(offset_info2, dict):
                     oh = offset_info2.get("hours", 0)
                     om = abs(offset_info2.get("minutes", 0))
+                    os_ = offset_info2.get("seconds", 0)
                     sign = "+" if oh >= 0 else "-"
                     utc_offset = f"{sign}{abs(oh):02d}:{om:02d}"
+                    if os_:
+                        utc_offset = f"{utc_offset}:{os_:02d}"
             timezone_src = "timeapi.io"
     except (RuntimeError, KeyError, TypeError):
         pass  # API may be down; continue to fallback

agents/gerhard-hermes/skills/productivity/nano-pdf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nano-pdf
-description: Edit PDFs with natural-language instructions using the nano-pdf CLI. Modify text, fix typos, update titles, and make content changes to specific pages without manual editing.
+description: "Edit PDF text/typos/titles via nano-pdf CLI (NL prompts)."
 version: 1.0.0
 author: community
 license: MIT

agents/gerhard-hermes/skills/productivity/notion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notion
-description: Notion API for creating and managing pages, databases, and blocks via curl. Search, create, update, and query Notion workspaces directly from the terminal.
+description: "Notion API via curl: pages, databases, blocks, search."
 version: 1.0.0
 author: community
 license: MIT

agents/gerhard-hermes/skills/productivity/ocr-and-documents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ocr-and-documents
-description: Extract text from PDFs and scanned documents. Use web_extract for remote URLs, pymupdf for local text-based PDFs, marker-pdf for OCR/scanned docs. For DOCX use python-docx, for PPTX see the powerpoint skill.
+description: "Extract text from PDFs/scans (pymupdf, marker-pdf)."
 version: 2.3.0
 author: Hermes Agent
 license: MIT

agents/gerhard-hermes/skills/productivity/powerpoint/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: powerpoint
-description: "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill."
+description: "Create, read, edit .pptx decks, slides, notes, templates."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 
 # Powerpoint Skill
 
+## When to use
+
+Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill.
+
 ## Quick Reference
 
 | Task | Guide |