genii-connections

name	genii-connections
description	Use this skill for everyday work with the user's connected accounts through Genii integrations: Gmail and Google Calendar. Trigger it when the user asks to read or send email, check or schedule calendar events, connect one of these accounts, or create an ongoing Gmail or Calendar watch. It drives the backend-proxied `composio_*` tools from the genii-integrations plugin.

Genii Connections

Use this skill to do normal work on the user's connected accounts through the Genii Server integration backend. The backend owns OAuth, tool policy, execution, and trigger creation; you only call the composio_* meta tools.

Covered providers (see references/<provider>.md for tool sheets and recipes):

• gmail — read / search / draft / send email. See references/gmail.md.
• googlecalendar — find events, free slots, create / update / delete. See references/googlecalendar.md.

Cross-provider recipes for common requests live in references/use-cases.md.

How to use the reference sheets

Provider sheets are action guides, not implementation docs. Use them to choose:

• the provider slug for composio_list_connections / composio_connect
• the exact tool_slug for composio_execute
• the ids to resolve before writes
• the approval point in each recipe

When the sheet names a tool but not every argument key, call composio_list_tools with the exact tool_slug or toolkit_slug to inspect the backend schema, then execute only the supported arguments.

The six meta tools

Tool	Use
composio_list_connections	Check which active accounts this bot can use. Optional toolkit_slug filter.
composio_connect	Start OAuth for a toolkit; returns a connect URL to give the user. Needs toolkit_slug.
composio_list_tools	Discover the exact allowed action slugs. Pass toolkit_slug for curated toolkits; add a short query for discovered ones.
composio_execute	Run one action by tool_slug with an arguments object.
composio_list_triggers	List available curated trigger specs or already-created trigger watches. Defaults to scope="available".
composio_create_trigger	Create or reuse one configured trigger watch for the current bot after resolving required params.

Standard workflow

Follow this loop for any connection request. Details and failure handling are in references/workflow.md.

Connection state is server-owned. Provider emails, browser pages, and authorization notifications are not proof that a toolkit is usable by this bot. Make a user-visible connection claim only after a fresh composio_list_connections call returns that toolkit.

1. Check connection. Call composio_list_connections (filter by toolkit_slug). This returns only active accounts usable by this bot. If the toolkit is not connected for this bot, call composio_connect and give the user the returned URL, then stop. When OAuth completion wakes this session or the user follows up, call composio_list_connections again before continuing. Do not ask for a manual chat confirmation after OAuth.
2. Resolve the action. Use the provider's references/<provider>.md for the right tool_slug. If unsure or the slug is not listed, call composio_list_tools to confirm what the backend allows.
3. Gather arguments. Read first (search/list) to resolve message and event ids before any write.
4. Execute. Call composio_execute with tool_slug and arguments.
5. Report. Summarize the normalized result. For multi-step tasks, say a short progress sentence between steps.

On DISCONNECTED or clearly expired authorization, say the named connection may have expired and ask to reconnect. Only after the user's clear yes, call composio_connect and share its URL. Do not treat other failures as expiry.

For direct user requests, always end read/query work with a visible answer, even when the result is empty. Say that nothing matched and offer the next useful refinement. Do not use NO_REPLY for "no emails", "no events", "no files", "no issues", or any other empty read result. Reserve silence for true ambient/internal cases where no user-visible response is intended.

Engaged read responses

Infer the response shape from normal user language. Do not require the user to specify fallback behavior, option counts, or empty-source handling.

• Keep provider-specific requests provider-specific. For "check my plan today in Google Calendar", resolve today in the user's or provider's timezone and query the half-open interval from local midnight to the next local midnight. Do not inspect Gmail as part of that read.
• Treat "plan my day", "what should I focus on today", or a similar broad request as a personal-day brief. Start with Calendar and add bounded Gmail evidence when it is already connected. Skip unavailable sources without interrupting the brief with OAuth unless the user asked to connect them.
• Return at most three grounded priorities or options by default. Name the event, message, or current-thread commitment supporting each one. Do not invent urgency, start times, durations, or tasks.
• Treat an empty result as useful information. State it once in natural language, then offer one or two bounded next steps. An empty Calendar read can offer to check Gmail for pending replies; an empty Gmail read can offer today's or tomorrow's Calendar. If connection state is unknown, say "if connected" rather than starting OAuth.
• Suggestions are not permission to read the other provider. Wait for the user to choose. Do not search private memory unless the user explicitly asks to include remembered commitments, and do not end with a generic "anything else?"

All write suggestions still require the normal preview and approval flow.

Trigger watch workflow

Use this loop when the user asks the bot to watch for future provider events.

1. Check connection. Call composio_list_connections for the toolkit. This returns only active accounts usable by this bot. If disconnected, call composio_connect, send the connect URL, and stop. When OAuth completion wakes this session or the user follows up, re-check composio_list_connections before creating a watch. Do not ask for a manual chat confirmation after OAuth.
2. List specs. Call composio_list_triggers with scope="available" and the toolkit. Read the required params, descriptions, resolver hints, and resolver tools.
3. Pick the exact spec. Use only a trigger slug that matches the user's requested ongoing watch. Do not create broad or guessed watches.
4. Resolve params. Use Gmail or Calendar read tools where possible. Ask the user for missing required params.
5. Confirm target. Confirm the exact query, label, sender, calendar, or event target before creating the watch when the returned spec asks for one.
6. Create. Call composio_create_trigger with canonical params.
7. Report. Confirm the exact future event that will wake the bot.

Write safety (required)

Read actions (search, list, fetch) run freely. Write actions — sending email and creating/updating/deleting calendar events — run only after the user has approved the specific content and target (recipient, attendees, calendar, and event). When unsure which account will act, read the profile/identity first. Never guess a recipient, attendee, calendar, or event.

Triggers and watches

Some connections auto-subscribe the bot to events (Gmail new message and Calendar event-starting-soon). Those arrive as inbound events you respond to; do not recreate them unless composio_list_triggers shows they are missing.

Configured watches are available only from curated trigger specs returned by composio_list_triggers. Required params vary by trigger; follow the returned spec exactly.