integrations

Name: integrations
Author: butterbase-ai

533stars40forks

How to install integrations?

butterbase-ai/butterbase-skills/integrations

$npx -y skills add butterbase-ai/butterbase-skills --skill integrations

Installs into the current project.

Summary

Use BEFORE recommending or installing any third-party SaaS SDK for email (Resend, SendGrid, Postmark, Mailgun), SMS (Twilio), messaging (Slack), calendar (Google Calendar), CRM (HubSpot, Salesforce), docs (Notion), or project management (Linear, GitHub). Butterbase covers most of

Files · 1

View on GitHub

SKILL.md

1	# Butterbase Integrations (Composio)
2
3	The `manage_integrations` MCP tool gives every Butterbase app access to Composio's toolkit catalog. Before installing a third-party SDK for any of the use cases below, check whether Composio covers it.
4
5	## Decision rule
6
7	```
8	User wants: send email / Slack message / create calendar event / post GitHub issue / etc.
9
10	Step 1: manage_integrations(app_id, action: "list_available", search: "<keyword>")
11	Step 2: If a toolkit covers it → use the Composio path (configure → list_tools → execute_action)
12	Step 3: If no toolkit covers it OR latency is critical → fall back to a direct API call in a function
13	```
14
15	## Common toolkit map
16
17	\| Use case \| Composio toolkit \| Replaces \|
18	\|---\|---\|---\|
19	\| Send email \| `gmail` \| Resend, SendGrid, Postmark, Mailgun \|
20	\| Read inbox / search \| `gmail` \| Custom IMAP, Nylas \|
21	\| Create calendar event \| `google_calendar` \| Cal.com API, custom OAuth \|
22	\| Post Slack message \| `slack` \| Slack Web API \|
23	\| Create GitHub issue / PR \| `github` \| Octokit \|
24	\| Notion page / database row \| `notion` \| Notion API \|
25	\| Linear ticket \| `linear` \| Linear SDK \|
26	\| HubSpot contact / deal \| `hubspot` \| HubSpot API \|
27	\| Salesforce record \| `salesforce` \| Salesforce REST \|
28
29	Always call `list_available` first — the catalog grows.
30
31	## Flow
32
33	```
34	1. configure: manage_integrations(app_id, action: "configure", toolkit: "gmail", scopes: ["gmail.send"])
35	2. list_tools: manage_integrations(app_id, action: "list_tools", toolkit: "gmail")
36	→ returns [{ name: "GMAIL_SEND_EMAIL", parameters: {...} }, ...]
37	3. execute_action: manage_integrations(
38	app_id, action: "execute_action",
39	tool_name: "GMAIL_SEND_EMAIL",
40	params: { to, subject, body },
41	user_id: "<end-user uuid>" // omit for service-level
42	)
43	```
44
45	## Per-user OAuth vs. service-level
46
47	- Service-level (omit `user_id`): the integration runs as the app owner. Use for system notifications, internal automation.
48	- Per-user (set `user_id`): the integration runs as the specified end-user. The user must have completed Composio's OAuth flow. Use for "send on behalf of user."
49
50	## When NOT to use Composio
51
52	- ❌ Latency-critical hot path (Composio adds a round-trip). Use a direct API call from a function.
53	- ❌ Toolkit doesn't exist yet (check `list_available`). Fall back to a direct API call.
54	- ❌ The user needs a custom auth flow that Composio doesn't support.
55
56	## Documentation
57
58	For the catalog and per-toolkit scope reference, WebFetch `https://docs.butterbase.ai/integrations` or call `butterbase_docs` with `topic: "integrations"`.
59
60	## Anti-patterns
61
62	- ❌ Recommending Resend / SendGrid without checking `manage_integrations list_available` first.
63	- ❌ Writing OAuth code yourself when a Composio toolkit covers the provider.
64	- ❌ Using service-level when the action should be attributed to a specific end-user.

People who liked this also viewed

6 picks

Type

integrations

533stars40forks

View on GitHub

How to install integrations?

butterbase-ai/butterbase-skills/integrations

$npx -y skills add butterbase-ai/butterbase-skills --skill integrations

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Butterbase Integrations (Composio)
2
3	The `manage_integrations` MCP tool gives every Butterbase app access to Composio's toolkit catalog. Before installing a third-party SDK for any of the use cases below, check whether Composio covers it.
4
5	## Decision rule
6
7	```
8	User wants: send email / Slack message / create calendar event / post GitHub issue / etc.
9
10	Step 1: manage_integrations(app_id, action: "list_available", search: "<keyword>")
11	Step 2: If a toolkit covers it → use the Composio path (configure → list_tools → execute_action)
12	Step 3: If no toolkit covers it OR latency is critical → fall back to a direct API call in a function
13	```
14
15	## Common toolkit map
16
17	\| Use case \| Composio toolkit \| Replaces \|
18	\|---\|---\|---\|
19	\| Send email \| `gmail` \| Resend, SendGrid, Postmark, Mailgun \|
20	\| Read inbox / search \| `gmail` \| Custom IMAP, Nylas \|
21	\| Create calendar event \| `google_calendar` \| Cal.com API, custom OAuth \|
22	\| Post Slack message \| `slack` \| Slack Web API \|
23	\| Create GitHub issue / PR \| `github` \| Octokit \|
24	\| Notion page / database row \| `notion` \| Notion API \|
25	\| Linear ticket \| `linear` \| Linear SDK \|
26	\| HubSpot contact / deal \| `hubspot` \| HubSpot API \|
27	\| Salesforce record \| `salesforce` \| Salesforce REST \|
28
29	Always call `list_available` first — the catalog grows.
30
31	## Flow
32
33	```
34	1. configure: manage_integrations(app_id, action: "configure", toolkit: "gmail", scopes: ["gmail.send"])
35	2. list_tools: manage_integrations(app_id, action: "list_tools", toolkit: "gmail")
36	→ returns [{ name: "GMAIL_SEND_EMAIL", parameters: {...} }, ...]
37	3. execute_action: manage_integrations(
38	app_id, action: "execute_action",
39	tool_name: "GMAIL_SEND_EMAIL",
40	params: { to, subject, body },
41	user_id: "<end-user uuid>" // omit for service-level
42	)
43	```
44
45	## Per-user OAuth vs. service-level
46
47	- Service-level (omit `user_id`): the integration runs as the app owner. Use for system notifications, internal automation.
48	- Per-user (set `user_id`): the integration runs as the specified end-user. The user must have completed Composio's OAuth flow. Use for "send on behalf of user."
49
50	## When NOT to use Composio
51
52	- ❌ Latency-critical hot path (Composio adds a round-trip). Use a direct API call from a function.
53	- ❌ Toolkit doesn't exist yet (check `list_available`). Fall back to a direct API call.
54	- ❌ The user needs a custom auth flow that Composio doesn't support.
55
56	## Documentation
57
58	For the catalog and per-toolkit scope reference, WebFetch `https://docs.butterbase.ai/integrations` or call `butterbase_docs` with `topic: "integrations"`.
59
60	## Anti-patterns
61
62	- ❌ Recommending Resend / SendGrid without checking `manage_integrations list_available` first.
63	- ❌ Writing OAuth code yourself when a Composio toolkit covers the provider.
64	- ❌ Using service-level when the action should be attributed to a specific end-user.

People who liked this also viewed

6 picks

Type