@sulala/agent-os 0.1.5 → 0.1.7

package/data/agents/briefing_agent.json

@@ -0,0 +1,12 @@
+{
+  "id": "briefing_agent",
+  "name": "Daily Briefing",
+  "description": "Morning-style brief: weather and RSS feeds. Use for 'what's the weather' and 'what's new' from configured feeds. Optionally schedule (e.g. 8:00) for a daily brief.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory", "weather", "rss"],
+  "limits": {
+    "max_turns": 15
+  },
+  "schedule": "0 8 * * *",
+  "schedule_input": "Give me a short morning brief: weather for my location and top items from my RSS feeds."
+}

package/data/agents/dev_agent.json

@@ -0,0 +1,10 @@
+{
+  "id": "dev_agent",
+  "name": "Dev Assistant",
+  "description": "Git status, search the codebase, parse JSON (jq), and fetch APIs. Use when the user asks about git, finding code, or working with JSON/APIs. Operates in the agent workspace.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory", "git", "file-search", "jq", "fetch"],
+  "limits": {
+    "max_turns": 15
+  }
+}

package/data/agents/manager_agent.json

@@ -0,0 +1,11 @@
+{
+  "id": "manager_agent",
+  "name": "Manager Assistant",
+  "description": "Coordinates other agents. You don't have social media, email, or search skills yourself—when the user asks to post to Bluesky/social, send an email, search the web, or do something another agent can do, use the run_agent tool to delegate to the right agent (social_media_agent, writer_agent, research_agent, etc.) and then summarize the result for the user.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory"],
+  "tools": ["run_agent"],
+  "limits": {
+    "max_turns": 15
+  }
+}

package/data/agents/media_agent.json

@@ -0,0 +1,10 @@
+{
+  "id": "media_agent",
+  "name": "Media Assistant",
+  "description": "Upload to YouTube, generate QR codes, and send webhooks (e.g. Slack, Discord). Configure YouTube credentials and webhook URLs in the respective skills.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory", "youtube", "qr-code", "webhook"],
+  "limits": {
+    "max_turns": 15
+  }
+}

package/data/agents/personal_agent.json

@@ -0,0 +1,11 @@
+{
+  "id": "personal_agent",
+  "name": "Personal Assistant",
+  "description": "Personal assistant with long-term memory and tools. Use the memory skill to store explicit user facts (e.g. 'remember that I live in X') and to recall them when the user asks what you remember, where they live, or what they like. Can check weather and search the web.",
+  "personality": "Friendly, supportive, and calm. Respond with empathy and a little warmth. When the user shares something personal or asks for help, be encouraging.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory", "weather", "web-search"],
+  "limits": {
+    "max_turns": 20
+  }
+}

package/data/agents/research_agent.json

@@ -0,0 +1,10 @@
+{
+  "id": "research_agent",
+  "name": "Research Assistant",
+  "description": "Search the web, fetch and summarize URLs, and follow RSS feeds. Use when the user asks to search for something, read a page, or get updates from a feed. Configure web-search API key in the skill if required.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory", "web-search", "fetch", "rss"],
+  "limits": {
+    "max_turns": 15
+  }
+}

package/data/agents/social_media_agent.json

@@ -0,0 +1,10 @@
+{
+  "id": "social_media_agent",
+  "name": "Social Media Assistant",
+  "description": "Post to social networks (e.g. Bluesky), read your timeline, and reply to posts. Configure credentials in the skill (Agents → Edit → Skills, or Settings). Currently supports Bluesky.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory", "bluesky"],
+  "limits": {
+    "max_turns": 15
+  }
+}

package/data/agents/writer_agent.json

@@ -0,0 +1,10 @@
+{
+  "id": "writer_agent",
+  "name": "Writer Assistant",
+  "description": "Draft and send email (Gmail) and translate text. Use when the user wants to send an email or translate content. Gmail requires connection via Portal or skill config.",
+  "model": "gpt-4o-mini",
+  "skills": ["memory", "gmail", "translate"],
+  "limits": {
+    "max_turns": 15
+  }
+}

package/data/skills/bluesky/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: bluesky
+description: Post to Bluesky and read your home timeline (AT Protocol). Use when the user says "post this to Bluesky", "what's on my Bluesky feed", "reply to this post", "post to Bluesky", "my Bluesky timeline".
+credentials:
+  - BLUESKY_HANDLE
+  - BLUESKY_APP_PASSWORD
+metadata:
+  clawdbot:
+    emoji: "🦋"
+    requires:
+      bins:
+        - curl
+        - jq
+---
+
+# Bluesky
+
+Post and read your Bluesky feed via the AT Protocol. Use the **exec** tool with **skill_id: "bluesky"** so `BLUESKY_HANDLE` and `BLUESKY_APP_PASSWORD` are injected from skill config.
+
+## Prerequisites
+
+1. Add the **bluesky** skill to the agent.
+2. Set **Bluesky handle** and **Bluesky app password** in Skills → bluesky → Setup (see **Setup** below).
+3. **jq** must be installed (`brew install jq` or `apt install jq`).
+
+## Setup
+
+1. In Bluesky: **Settings** (gear) → **App passwords** → **Add App Password**. Name it (e.g. "Agent OS"), copy the password once (it won’t be shown again).
+2. Your handle is your Bluesky username (e.g. `yourname.bsky.social`).
+3. In the dashboard: **Skills** → **bluesky** → ⋮ → **Setup** → set **Bluesky handle** and **Bluesky app password** → Save.
+
+Never use your main account password; use only an app password.
+
+### If you get "Invalid identifier or password"
+
+- **Handle:** Use your full handle exactly as shown in Bluesky (e.g. `yourname.bsky.social`). Do not include `@`. The script strips a leading `@` and trims spaces automatically.
+- **App password:** You must create one in Bluesky **Settings → App passwords → Add App Password**. Copy it when shown (it’s not shown again). If you lost it, create a new app password and update the skill config.
+- **No account password:** The app password is a separate, long token (e.g. `xxxx-xxxx-xxxx-xxxx`); do not use your normal Bluesky login password.
+
+## Post a new post
+
+- **skill_id:** `bluesky`
+- **command:** `./scripts/post.sh "Your post text here"`
+
+Post text is the first argument. Max 300 graphemes (Bluesky limit). The script creates a session, then creates the record; the response is the created post URI.
+
+## Get your home timeline
+
+- **skill_id:** `bluesky`
+- **command:** `./scripts/timeline.sh`
+- Optional limit: `./scripts/timeline.sh 30` (default 20)
+
+Returns JSON: `feed[]` with `post` (author, record.text, etc.). Summarize or list the most recent posts for the user.
+
+## Reply to a post (future)
+
+Replies require a `reply` object (parent + root) in the record. The current script only supports top-level posts. For replies, extend the record or add a `reply.sh` script that accepts parent URI and text.
+
+## Tips
+
+- Quote the post text in the command so spaces and punctuation are preserved: `./scripts/post.sh "Hello from the agent!"`
+- Timeline entries have `post.author.displayName`, `post.record.text`, `post.uri`. Use these to summarize the feed.
+- Optional env **BLUESKY_PDS** overrides the PDS URL (default `https://bsky.social`); only set if you use a custom PDS.

package/data/skills/bluesky/config.schema.json

@@ -0,0 +1,17 @@
+{
+  "type": "object",
+  "properties": {
+    "BLUESKY_HANDLE": {
+      "type": "string",
+      "title": "Bluesky handle",
+      "description": "Your Bluesky handle (e.g. yourname.bsky.social). Used with the app password to create a session."
+    },
+    "BLUESKY_APP_PASSWORD": {
+      "type": "string",
+      "format": "password",
+      "title": "Bluesky app password",
+      "description": "App password from Bluesky Settings → App passwords. Do not use your main account password."
+    }
+  },
+  "required": ["BLUESKY_HANDLE", "BLUESKY_APP_PASSWORD"]
+}

package/data/skills/bluesky/scripts/post.sh

@@ -0,0 +1,48 @@
+#!/bin/sh
+# Post to Bluesky via AT Protocol. BLUESKY_HANDLE and BLUESKY_APP_PASSWORD from skill config.
+# Usage: post.sh "your post text here"
+set -e
+if [ -z "$BLUESKY_HANDLE" ] || [ -z "$BLUESKY_APP_PASSWORD" ]; then
+  echo "BLUESKY_HANDLE and BLUESKY_APP_PASSWORD must be set. Configure in Skills → bluesky → Setup." >&2
+  exit 1
+fi
+# Trim and normalize: handle without leading @, no leading/trailing whitespace
+BLUESKY_HANDLE=$(echo "$BLUESKY_HANDLE" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//;s/^@//')
+BLUESKY_APP_PASSWORD=$(echo "$BLUESKY_APP_PASSWORD" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+if [ -z "$BLUESKY_HANDLE" ] || [ -z "$BLUESKY_APP_PASSWORD" ]; then
+  echo "BLUESKY_HANDLE and BLUESKY_APP_PASSWORD must be non-empty after trimming." >&2
+  exit 1
+fi
+if [ -z "$1" ]; then
+  echo "Usage: post.sh \"post text\"" >&2
+  exit 1
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required for the Bluesky skill." >&2
+  exit 1
+fi
+PDS="${BLUESKY_PDS:-https://bsky.social}"
+# Create session (use jq to build JSON so special chars in password are safe)
+SESSION_BODY=$(jq -n --arg id "$BLUESKY_HANDLE" --arg pw "$BLUESKY_APP_PASSWORD" '{identifier:$id,password:$pw}')
+SESSION=$(curl -sS -X POST "$PDS/xrpc/com.atproto.server.createSession" \
+  -H "Content-Type: application/json" \
+  -d "$SESSION_BODY")
+if ! echo "$SESSION" | jq -e '.accessJwt' >/dev/null 2>&1; then
+  echo "Session failed: $SESSION" >&2
+  echo "Check: (1) Handle is your full handle, e.g. yourname.bsky.social (no @). (2) Use an App password from Bluesky Settings → App passwords, not your account password." >&2
+  exit 1
+fi
+ACCESS_JWT=$(echo "$SESSION" | jq -r '.accessJwt')
+DID=$(echo "$SESSION" | jq -r '.did')
+# createdAt in ISO 8601
+CREATED_AT=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
+# Escape post text for JSON
+TEXT=$(printf '%s' "$1" | jq -Rs .)
+RECORD=$(jq -n --arg text "$1" --arg createdAt "$CREATED_AT" \
+  '{ ("$type"): "app.bsky.feed.post", text: $text, createdAt: $createdAt }')
+BODY=$(jq -n --arg repo "$DID" --argjson record "$RECORD" \
+  '{ repo: $repo, collection: "app.bsky.feed.post", record: $record }')
+curl -sS -X POST "$PDS/xrpc/com.atproto.repo.createRecord" \
+  -H "Authorization: Bearer $ACCESS_JWT" \
+  -H "Content-Type: application/json" \
+  -d "$BODY"

package/data/skills/bluesky/scripts/timeline.sh

@@ -0,0 +1,37 @@
+#!/bin/sh
+# Get Bluesky home timeline. BLUESKY_HANDLE and BLUESKY_APP_PASSWORD from skill config (injected as env by exec).
+# Usage: timeline.sh [limit]
+# Optional: limit (default 20) - number of posts to return.
+set -e
+if [ -z "$BLUESKY_HANDLE" ] || [ -z "$BLUESKY_APP_PASSWORD" ]; then
+  echo "BLUESKY_HANDLE and BLUESKY_APP_PASSWORD must be set. Configure in Skills → bluesky → Setup." >&2
+  exit 1
+fi
+# Trim and normalize: handle without leading @
+BLUESKY_HANDLE=$(echo "$BLUESKY_HANDLE" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//;s/^@//')
+BLUESKY_APP_PASSWORD=$(echo "$BLUESKY_APP_PASSWORD" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+if [ -z "$BLUESKY_HANDLE" ] || [ -z "$BLUESKY_APP_PASSWORD" ]; then
+  echo "BLUESKY_HANDLE and BLUESKY_APP_PASSWORD must be non-empty after trimming." >&2
+  exit 1
+fi
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required. Install with: brew install jq (macOS) or apt install jq (Linux)." >&2
+  exit 1
+fi
+
+LIMIT="${1:-20}"
+PDS="${BLUESKY_PDS:-https://bsky.social}"
+SESSION_BODY=$(jq -n --arg id "$BLUESKY_HANDLE" --arg pw "$BLUESKY_APP_PASSWORD" '{identifier:$id,password:$pw}')
+SESSION=$(curl -sS -X POST "$PDS/xrpc/com.atproto.server.createSession" \
+  -H "Content-Type: application/json" \
+  -d "$SESSION_BODY")
+if ! echo "$SESSION" | jq -e '.accessJwt' >/dev/null 2>&1; then
+  echo "Session failed: $SESSION" >&2
+  echo "Check: (1) Handle is your full handle, e.g. yourname.bsky.social (no @). (2) Use an App password from Bluesky Settings → App passwords, not your account password." >&2
+  exit 1
+fi
+ACCESS_JWT=$(echo "$SESSION" | jq -r '.accessJwt')
+
+curl -sS -G "$PDS/xrpc/app.bsky.feed.getTimeline" \
+  --data-urlencode "limit=$LIMIT" \
+  -H "Authorization: Bearer $ACCESS_JWT"

package/data/skills/date/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: date
+description: Get current date and time (optionally in a timezone). Use when the user asks "what time is it", "current date", "time in Tokyo", "what's the date today".
+metadata:
+  clawdbot:
+    emoji: "🕐"
+    requires:
+      bins:
+        - date
+---
+
+# Date and time
+
+Use the **exec** tool to run `date` or fetch time from an API. No script required.
+
+## Local date and time
+
+```bash
+date
+# e.g. Sat Mar 15 10:30:00 GMT 2025
+```
+
+Custom format (ISO-like):
+
+```bash
+date +"%Y-%m-%d %H:%M:%S %Z"
+```
+
+## Time in another timezone
+
+```bash
+TZ=Europe/Paris date
+TZ=America/New_York date
+TZ=Asia/Tokyo date +"%H:%M %Z"
+```
+
+Common TZ values: `Europe/London`, `Europe/Paris`, `America/Los_Angeles`, `America/New_York`, `Asia/Tokyo`, `UTC`.
+
+## Unix timestamp
+
+```bash
+date +%s
+```
+
+## World time (fallback via curl)
+
+If the user asks for "time in City" and you need a source:
+
+```bash
+curl -s "https://worldtimeapi.org/api/timezone/Europe/Paris" | head -c 500
+```
+
+Returns JSON with `datetime`, `timezone`, etc. Other zones: `America/New_York`, `Asia/Tokyo`. Docs: https://worldtimeapi.org/

package/data/skills/fetch/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: fetch
+description: Fetch content from a URL (GET). Use when the user says "fetch this URL", "read that page", "get content from …", or "what's at this link".
+metadata:
+  clawdbot:
+    emoji: "🔗"
+    requires:
+      bins:
+        - curl
+---
+
+# Fetch URL
+
+Fetch the body of a URL via **curl**. Use the **exec** tool with the commands below. Only use **http** or **https** URLs.
+
+## GET body (plain)
+
+```bash
+curl -sL "https://example.com/page"
+```
+
+- `-s` silent (no progress)
+- `-L` follow redirects
+
+## With a user-agent (some sites need it)
+
+```bash
+curl -sL -A "Mozilla/5.0 (compatible; Agent/1.0)" "https://example.com/page"
+```
+
+## Limit size (avoid huge responses)
+
+```bash
+curl -sL --max-size 1048576 "https://example.com/page"
+# 1 MiB max
+```
+
+## Tips
+
+- URL-encode the URL or quote it in the shell.
+- For JSON APIs, pipe to `head -c 50000` or process with `jq` if needed.
+- Do not POST or send secrets in the URL; use this for read-only GET.

package/data/skills/file-search/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: file-search
+description: Search for files and text in the workspace or the user's computer (grep, find). Use when the user asks "find files containing X", "list all .md files", "search my computer", "find file named Y on my machine", "search in my Downloads".
+metadata:
+  clawdbot:
+    emoji: "🔍"
+    requires:
+      bins:
+        - grep
+        - find
+---
+
+# File search (workspace)
+
+Use **grep** and **find** via the **exec** tool to search inside the **workspace**. Commands run in the agent workspace; restrict paths to the workspace (no `../` escape).
+
+## Find files by name or pattern
+
+```bash
+find . -name "*.md"
+find . -name "*.json" -type f
+find . -iname "*config*"
+```
+
+Limit depth (e.g. current dir + one level):
+
+```bash
+find . -maxdepth 2 -name "*.ts"
+```
+
+## Search file contents (grep)
+
+```bash
+grep -r "search term" .
+grep -rn "function foo" .
+# -n = line numbers
+```
+
+Case-insensitive:
+
+```bash
+grep -ri "TODO" .
+```
+
+Only list matching files (no line content):
+
+```bash
+grep -rl "import React" .
+```
+
+## Combine find + grep
+
+```bash
+find . -name "*.py" -exec grep -l "def main" {} \;
+```
+
+## Search the user's computer (home directory)
+
+When the user says "on my computer", "in my computer", "on my machine", "in my home", "find file named X" (and not in workspace), or "in my Downloads", search their **home directory** using `~` or `$HOME` so it works on **macOS** (/Users/username) and **Linux** (/home/username):
+
+**Find a file by exact name:**
+
+```bash
+find ~ -name "saiko_cv" -type f 2>/dev/null
+find ~ -name "gggg.png" -type f 2>/dev/null
+```
+
+**Find in a specific folder (e.g. Downloads, Desktop):**
+
+```bash
+find ~/Downloads -name "*.png" -type f
+find ~/Desktop -name "saiko_cv*" -type f 2>/dev/null
+```
+
+**Find by name pattern (partial match):**
+
+```bash
+find ~ -iname "*saiko_cv*" -type f 2>/dev/null
+find ~ -iname "*gggg*" -type f 2>/dev/null
+```
+
+Use `-iname` for case-insensitive match. Use `2>/dev/null` to hide permission errors.
+
+## Search entire system or a specific path
+
+When the user asks for "whole system", "entire disk", or an explicit path:
+
+**Portable (home):** use `~` or `$HOME` (works on macOS and Linux).
+
+**Linux:** `/home` or `/home/$(whoami)`.
+
+**macOS:** `/Users` or `~` (e.g. `/Users/saiko`).
+
+```bash
+find ~ -name "*.md" -type f 2>/dev/null
+find /home -name "*.conf" -type f 2>/dev/null
+find / -name "*.conf" -type f 2>/dev/null
+```
+
+**Grep in a path:**
+
+```bash
+grep -r "pattern" ~ 2>/dev/null
+grep -rln "TODO" ~/projects 2>/dev/null
+```
+
+**Limit depth for large trees:**
+
+```bash
+find ~ -maxdepth 5 -name "*.json" -type f
+```
+
+**Tips:**
+
+- **"My computer" or "find file X"** → use `find ~ -name "X"` (or `find ~/Downloads -name "X"` if they say "in Downloads"). Do not search only the workspace.
+- Prefer `~` or `$HOME` so the same command works on macOS and Linux.
+- Add `2>/dev/null` to hide "Permission denied" when searching outside the workspace.
+
+## Tips (workspace-only)
+
+- Use `.` so search is limited to current directory (workspace root when exec runs there).
+- For large trees, consider `-maxdepth` or file-type filters to keep output small.

package/data/skills/file-stats/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: file-stats
+description: Get line count, word count, or first/last lines of a file (wc, head, tail). Use when the user asks "how many lines in this file", "first 20 lines of …", "word count", "last 10 lines", "show the top of the file".
+metadata:
+  clawdbot:
+    emoji: "📊"
+    requires:
+      bins:
+        - wc
+        - head
+        - tail
+---
+
+# File stats (wc, head, tail)
+
+Use **wc**, **head**, and **tail** via the **exec** tool. Path can be relative (workspace) or absolute (e.g. `~/file.txt`).
+
+## Line count
+
+```bash
+wc -l path/to/file
+wc -l < path/to/file
+# Second form outputs only the number (no filename).
+```
+
+## Word count
+
+```bash
+wc -w path/to/file
+wc -w < path/to/file
+```
+
+## Line, word, and byte count
+
+```bash
+wc path/to/file
+# Output: lines words bytes filename
+```
+
+## First N lines (head)
+
+```bash
+head -n 20 path/to/file
+head -20 path/to/file
+head path/to/file
+# Default is 10 lines.
+```
+
+## Last N lines (tail)
+
+```bash
+tail -n 10 path/to/file
+tail -10 path/to/file
+tail path/to/file
+# Default is 10 lines.
+```
+
+## Skip first N lines (tail)
+
+```bash
+tail -n +21 path/to/file
+# Lines 21 to end (skip first 20).
+```
+
+## Tips
+
+- Use `head -c 5000` or `tail -c 5000` for first/last N **bytes** if needed.
+- For "preview" or "first part of file", use `head -n 50`.

package/data/skills/git/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: git
+description: Run read-only git commands in the workspace (status, log, branch, diff). Use when the user asks "what's the git status", "recent commits", "current branch", "show me the diff".
+metadata:
+  clawdbot:
+    emoji: "📂"
+    requires:
+      bins:
+        - git
+---
+
+# Git (read-only)
+
+Run **read-only** git commands in the workspace via the **exec** tool. Do **not** run `git commit`, `git push`, `git reset`, or any command that modifies history or remote. Restrict to status, log, branch, and diff.
+
+## Status
+
+```bash
+git status
+```
+
+Working tree state (clean, modified, untracked).
+
+## Recent commits
+
+```bash
+git log -n 10 --oneline
+git log -n 5 --pretty=format:"%h %s (%an, %ar)"
+```
+
+## Current branch and list branches
+
+```bash
+git branch --show-current
+git branch -a
+```
+
+## Diff (unstaged changes)
+
+```bash
+git diff
+git diff --stat
+```
+
+For a specific file:
+
+```bash
+git diff -- path/to/file
+```
+
+## Last commit message
+
+```bash
+git log -1 --pretty=%B
+```
+
+## Tips
+
+- Commands run in the **workspace** (agent workspace or repo root). Do not pass `skill_id` for git unless the skill dir is the repo; use exec with cwd in the workspace.
+- If the user asks "what branch am I on" or "any uncommitted changes?", use the commands above and summarize the output.

package/data/skills/gmail/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: gmail
+description: Send email via Gmail using your connected account. Uses Sulala Portal for the access token; includes a script to send email from the command line or automation. Requires the Sulala Portal skill for token. Use when the user wants to send email, compose mail, or automate Gmail sending.
+metadata:
+  sulala:
+    requires:
+      skills:
+        - sulala-portal
+---
+
+# Gmail (Sulala Portal)
+
+Send email using your **Gmail account connected in the Sulala Portal**. This skill provides a **script**; use the **exec** tool to run it. No static send-email code in the loader; the skill is script + docs like YouTube Shorts automation.
+
+## Overview
+
+1. **Get an access token** from the Portal (list connections, then `POST connections/{connection_id}/use` for Gmail).
+2. **Send email** by running the script via **exec** (see below).
+
+## Getting the token (Portal)
+
+- **Tool**: `sulala-portal_request`
+- **List connections**: `GET` path `connections` (filter by `provider === "gmail"` in the response).
+- **Get token**: `POST` path `connections/{id}/use`. Use the connection’s `connection_id` from the list (e.g. `conn_gmail_...`). If you get 404, use `connection_id` in the path instead of `id`. Response: `{ connectionId, provider, accessToken, scopes }`.
+
+## Sending email (use exec tool + script — preferred)
+
+Use the **exec** tool to run the skill script. No need to build RFC 2822 or base64url by hand.
+
+1. Get **accessToken** from the Portal (`sulala-portal_request`: list connections, then `POST connections/{connection_id}/use` with the Gmail connection’s `connection_id`).
+2. Call **exec** with:
+   - **skill_id**: `"gmail"` (so the command runs in this skill’s directory).
+   - **command**: `python3 scripts/send_email.py --token "<accessToken>" --to "recipient@example.com" --subject "Subject line" --body "Email body text."`
+
+Example exec call:
+
+```json
+{
+  "skill_id": "gmail",
+  "command": "python3 scripts/send_email.py --token \"<paste accessToken from Portal>\" --to \"sai.ko@mothernode.com\" --subject \"test title\" --body \"test body\""
+}
+```
+
+- **Token**: from `POST connections/{connection_id}/use` (see above).
+- **To**, **Subject**, **Body**: recipient email, subject line, and body text. Escape quotes inside the command string as needed.
+
+Full script options: [references/send-email.md](references/send-email.md).
+
+## Skill layout (like YouTube Shorts automation)
+
+- **scripts/send_email.py** — runnable script: `--token`, `--to`, `--subject`, `--body` or `--body-file`.
+- **references/send-email.md** — how to run the script and get the token.
+- **SKILL.md** — this file: overview, get token, send via exec + script.
+
+No separate config: the Sulala Portal skill provides the gateway and token; this skill adds the script and docs.