@devries-cameron20 / composio Mirror · read-only / commits / 0c139caac
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 16:00 UTC

feat(skills): add public composio agent skill

Kshitij Jhunjhunwala committed Aug 6, 2026 at 15:56 UTC 0c139caac71e394f5a71df74ac4937c1e53ec99d
4 files changed +304
skills/composio/SKILL.md new
+65
@@ -0,0 +1,65 @@
1 +---
2 +name: composio
3 +description: Use when the user mentions Composio, wants to add Composio to an agent or codebase, wants an AI agent to act in real apps such as Gmail, Slack, GitHub, Notion, Calendar, or Linear, or needs help fixing a Composio setup, connection, or tool call.
4 +---
5 +
6 +# Composio
7 +
8 +Composio gives AI agents tools and authenticated access to external apps.
9 +
10 +There are two products. They have different URLs, keys, and setup paths. Decide which one applies before doing anything else, and do not blend them.
11 +
12 +| | Composio For You | Composio Platform |
13 +|---|---|---|
14 +| For | You want your agent to use your apps | You are building a product where your users connect their accounts |
15 +| Surface | An MCP server attached to an AI client | An SDK integrated into a codebase |
16 +| Key | `ck_...` consumer key | `COMPOSIO_API_KEY` project key |
17 +| Dashboard | `dashboard.composio.dev` → For You | `dashboard.composio.dev` → Platform |
18 +
19 +## First decide the product
20 +
21 +Ask one question when the answer is not already clear:
22 +
23 +> Are you setting Composio up for yourself so your coding agent can use your apps, or are you building a product where your own users connect their accounts?
24 +
25 +Skip the question when context is sufficient:
26 +
27 +- The user names an AI client and is not building code → For You.
28 +- The user is inside a codebase or mentions users, tenants, `user_id`, an SDK, or an agent they are building → Platform.
29 +
30 +Read exactly one product guide. Do not read both.
31 +
32 +### 1. Composio For You
33 +
34 +Read [Composio For You](references/for-you.md).
35 +
36 +### 2. Composio Platform
37 +
38 +Read [Composio Platform](references/platform.md).
39 +
40 +### 3. Errors and provider failures
41 +
42 +For provider- and toolkit-level failures shared by both products, read [Errors and provider gotchas](references/errors.md).
43 +
44 +## Finish the work
45 +
46 +Install the dependency, write the configuration, and run the command. Setup is not complete until one real tool call succeeds.
47 +
48 +## Stable rules
49 +
50 +1. Establish which product applies before setup.
51 +2. Never invent a toolkit or tool slug. For Platform sessions, use `COMPOSIO_SEARCH_TOOLS`; for direct CLI work, use `composio search` and inspect with `composio execute --get-schema`.
52 +3. Do not build an OAuth flow. Composio supplies a Connect Link when authentication is required.
53 +4. Use sessions for new Platform integrations. Direct execution is a legacy migration path.
54 +5. Keep credentials in environment variables and out of source control.
55 +6. Get the log ID before diagnosing a failed tool call.
56 +
57 +## Fresh information
58 +
59 +When a detail is not covered by the selected guide, fetch the current markdown documentation and complete the work from it:
60 +
61 +```text
62 +https://docs.composio.dev/docs/<page>.md
63 +https://docs.composio.dev/llms.txt
64 +https://docs.composio.dev/toolkits/<toolkit>.md
65 +```
skills/composio/references/errors.md new
+45
@@ -0,0 +1,45 @@
1 +# Errors and provider gotchas
2 +
3 +These rules apply to both Composio products.
4 +
5 +## Start with the log ID
6 +
7 +Get the Composio log ID or request ID before diagnosing a failure. Framework wrappers often hide the underlying error.
8 +
9 +```bash
10 +composio dev logs tools
11 +composio dev logs triggers
12 +composio connections list
13 +```
14 +
15 +The dashboard Logs page provides the same execution trail.
16 +
17 +## Tool does not exist
18 +
19 +Never guess the slug. In a Platform session, discover it through `COMPOSIO_SEARCH_TOOLS`. In a direct CLI workflow, use `composio search`, then inspect the result with `composio execute <slug> --get-schema`.
20 +
21 +For manual legacy v3 execution, a missing tool is often a toolkit-version problem. Use a verified version or the v3.1 path that defaults to the current version. New session integrations should use runtime discovery instead of manually executing a guessed slug.
22 +
23 +## Authentication failures
24 +
25 +A 401 generally means the provider token was revoked, expired, or invalidated by a password, 2FA, or administrator-policy change. Reconnect the account and retry.
26 +
27 +If an authorization link expired, request a new one. Do not reuse it.
28 +
29 +## Provider constraints
30 +
31 +- Google "App is blocked": remove unnecessary scopes or use a verified custom OAuth app.
32 +- Slack 429s: managed apps share a provider quota; use a custom Slack app for a dedicated rate-limit bucket.
33 +- Microsoft 403s: the tenant may require administrator consent.
34 +- GitHub Apps: OAuth credentials and repository installation are separate steps.
35 +- Session Restriction errors for payment tools are policy restrictions, not plan or connection failures.
36 +
37 +## Production
38 +
39 +Managed auth is intended to make initial development easy. Before launch, use custom OAuth apps for integrations that need the developer's branding, scopes, or dedicated quotas.
40 +
41 +For toolkit-specific details, fetch:
42 +
43 +```text
44 +https://docs.composio.dev/toolkits/<toolkit>.md
45 +```
skills/composio/references/for-you.md new
+45
@@ -0,0 +1,45 @@
1 +# Composio For You
2 +
3 +Use this path when someone wants their own coding agent or AI client to use their own connected apps. This is an MCP setup, not an SDK integration.
4 +
5 +## MCP endpoint
6 +
7 +```text
8 +https://connect.composio.dev/mcp
9 +```
10 +
11 +Do not use the removed `mcp.composio.dev` endpoint or a Platform MCP URL.
12 +
13 +## Authentication
14 +
15 +Claude Desktop and ChatGPT use browser OAuth. Header-based clients use the consumer key from Dashboard → For You → Settings → Sessions & API Key:
16 +
17 +```text
18 +x-consumer-api-key: ck_...
19 +```
20 +
21 +The `ck_...` consumer key and Platform's `COMPOSIO_API_KEY` are not interchangeable.
22 +
23 +## Terminal coding agents
24 +
25 +Terminal agents can use the Composio CLI directly:
26 +
27 +```bash
28 +curl -fsSL https://composio.dev/install | bash
29 +composio login
30 +composio search "<what the user wants>"
31 +composio link <toolkit>
32 +composio execute <TOOL_SLUG> -d '{...}'
33 +```
34 +
35 +Use `composio login --no-wait | jq` when the agent cannot open a browser. Share the returned login URL, then complete login with the returned key.
36 +
37 +## Client configuration
38 +
39 +For any MCP-capable client, configure HTTP transport with the endpoint above and, when required, the `x-consumer-api-key` header. Fetch `https://docs.composio.dev/docs/composio-connect.md` for current client-specific steps.
40 +
41 +## Connect apps naturally
42 +
43 +Do not pre-connect every app. Start the real task. When an app is required, Composio returns an authorization link and the connection persists for future runs.
44 +
45 +Setup is complete only after one real tool call succeeds.
skills/composio/references/platform.md new
+149
@@ -0,0 +1,149 @@
1 +# Composio Platform
2 +
3 +Use this path when the developer is adding Composio to an agent, application, or backend where their users connect accounts.
4 +
5 +The goal is not to complete a canned task. The goal is to make Composio the tool and authentication layer inside the developer's existing system, then prove the integration with one real tool call.
6 +
7 +## 1. Inspect the codebase first
8 +
9 +Before choosing packages or generating files, identify:
10 +
11 +- The package manager and language.
12 +- The existing agent or LLM framework.
13 +- The current user or tenant identifier.
14 +- Where environment variables are loaded.
15 +- The smallest existing execution path where Composio tools belong.
16 +
17 +Extend the existing architecture. Do not create a separate demo agent when the repository already has one.
18 +
19 +## 2. Authenticate the project
20 +
21 +Run from the project directory:
22 +
23 +```bash
24 +curl -fsSL https://composio.dev/install | bash
25 +composio dev init
26 +```
27 +
28 +`composio dev init` logs in when needed, binds the directory to the selected Composio project, and provisions `COMPOSIO_API_KEY` in `.env.local`. If developer mode is off, run `composio dev --mode on` first. When the agent cannot open a browser, use `composio dev init --no-browser` and give the returned URL to the user.
29 +
30 +Select the exact project the user named. Do not use `-y` when multiple projects exist unless the current CLI project context already matches it. There is no bare `composio init` command.
31 +
32 +If the developer already has a key, store it as `COMPOSIO_API_KEY`. Never print it back, place it in a URL, or commit it.
33 +
34 +Dashboard fallback: Platform → project → API Keys.
35 +
36 +## 3. Install only what the codebase needs
37 +
38 +TypeScript:
39 +
40 +```bash
41 +npm install @composio/core
42 +```
43 +
44 +Python:
45 +
46 +```bash
47 +pip install composio
48 +```
49 +
50 +Add a provider package only when the repository's framework requires one, for example `@composio/vercel`, `@composio/openai-agents`, `@composio/mastra`, `@composio/anthropic`, `composio-openai-agents`, or `composio-langchain`.
51 +
52 +Do not introduce a second LLM framework solely for onboarding.
53 +
54 +## 4. Create a session for the current user
55 +
56 +A session is the runtime context for one user. It carries identity, connections, tool scope, and the remote sandbox.
57 +
58 +TypeScript:
59 +
60 +```typescript
61 +import { Composio } from "@composio/core";
62 +
63 +const composio = new Composio();
64 +const session = await composio.sessions.create("user_123");
65 +const tools = await session.tools();
66 +```
67 +
68 +Python:
69 +
70 +```python
71 +from composio import Composio
72 +
73 +composio = Composio()
74 +session = composio.sessions.create(user_id="user_123")
75 +tools = session.tools()
76 +```
77 +
78 +Use the application's stable database ID in production. Never use a shared `default` identity for multiple users.
79 +
80 +Create a session for an agentic run. For a multi-turn conversation, persist the returned session ID and resume it instead of creating a fresh session on every message:
81 +
82 +```typescript
83 +const sessionId = session.sessionId;
84 +const resumedSession = await composio.use(sessionId);
85 +```
86 +
87 +```python
88 +session_id = session.session_id
89 +resumed_session = composio.use(session_id)
90 +```
91 +
92 +## 5. Put Composio into the existing agent
93 +
94 +Pass the session tools to the repository's existing agent or model provider using its native tool integration. Preserve the current prompt, model, streaming, and request lifecycle unless a change is required for tools to execute.
95 +
96 +Sessions expose a small set of meta tools by default. The agent discovers the right integration and tool at runtime rather than loading thousands of schemas into context:
97 +
98 +- `COMPOSIO_SEARCH_TOOLS`
99 +- `COMPOSIO_GET_TOOL_SCHEMAS`
100 +- `COMPOSIO_MULTI_EXECUTE_TOOL`
101 +- `COMPOSIO_MANAGE_CONNECTIONS`
102 +- `COMPOSIO_WAIT_FOR_CONNECTIONS`
103 +- `COMPOSIO_REMOTE_WORKBENCH`
104 +- `COMPOSIO_REMOTE_BASH_TOOL`
105 +
106 +Keep connection management enabled for interactive agents. It is what returns a Connect Link when a user needs to authenticate an app.
107 +
108 +## 6. Prove it with a real call
109 +
110 +Setup is incomplete until a programmatic tool call succeeds from the developer's repository.
111 +
112 +For onboarding:
113 +
114 +1. Use the installed Composio skill and the existing agent path.
115 +2. Ask the developer which integration they want to try unless the repository already makes the choice clear.
116 +3. Let the session discover the actual toolkit and tool slug; never hard-code or guess one.
117 +4. If the integration is not connected, return the Connect Link, wait for authorization, and retry.
118 +5. Run one safe, read-only tool from the existing agent through the project selected during `composio dev init`.
119 +6. Capture the real result and log ID.
120 +
121 +The smoke test must hit Composio. A mocked response, Playground call, schema fetch, or SDK initialization does not count.
122 +
123 +If the repository has no runnable agent loop, add the smallest test entrypoint compatible with its existing LLM provider. Do not require a new hosted model solely for onboarding.
124 +
125 +## 7. Authentication happens when needed
126 +
127 +Do not build OAuth. If a selected app is not connected, `COMPOSIO_MANAGE_CONNECTIONS` returns a Connect Link, the user authorizes in the browser, and the agent retries.
128 +
129 +Start with managed auth. A custom auth config is needed only for custom branding, additional scopes, dedicated provider quotas, or self-hosted/regional requirements.
130 +
131 +## 8. Hand off the useful next steps
132 +
133 +After the first call succeeds, show the developer where to continue:
134 +
135 +- Logs for the exact request, response, duration, and log ID.
136 +- Toolkits to discover integrations.
137 +- Users for stable per-user identities and connections.
138 +- Auth Configs when the product needs custom authentication behavior.
139 +
140 +## Do not
141 +
142 +- Do not stop after linking documentation.
143 +- Do not use a fixed GitHub starring task as the onboarding concept.
144 +- Do not create an auth config as a prerequisite.
145 +- Do not guess tool or toolkit slugs.
146 +- Do not use direct execution for a new agent integration.
147 +- Do not claim success before a real programmatic tool call appears in logs.
148 +
149 +Current documentation index: `https://docs.composio.dev/llms.txt`.