@devries-cameron20 / composio Mirror · read-only / commits / 32e5e7f1a
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

fix(skill): align Platform onboarding with dashboard handoff

Kshitij Jhunjhunwala committed Aug 7, 2026 at 13:28 UTC 32e5e7f1aeef9344e9defce578ec348b6c49ede1
3 files changed +56 -56
skills/composio/SKILL.md
+7 -6
@@ -43,16 +43,17 @@ For provider- and toolkit-level failures shared by both products, read [Errors a
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.
46 +Install the dependency, write the configuration, and run the existing agent path. Setup is not complete until one safe, read-only real tool call returns an actual result and log ID.
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.
51 +2. For Platform, use the existing project `COMPOSIO_API_KEY` from the repository's environment or secret mechanism. Platform onboarding never creates, rotates, or replaces a key and never asks the user to paste one into chat.
52 +3. Never invent a toolkit or tool slug. For Platform sessions, discover tools at runtime. For direct CLI work in the For You path, use `composio search` and inspect with `composio execute --get-schema`.
53 +4. Do not build an OAuth flow. Composio supplies a Connect Link when authentication is required.
54 +5. Use sessions for new Platform integrations. Preserve the application's existing user identity mapping and agent architecture.
55 +6. Keep credentials out of source control, URLs, logs, chat, and command output.
56 +7. Get the log ID before diagnosing a failed tool call.
57
58 ## Fresh information
59
skills/composio/references/errors.md
+17 -3
@@ -2,9 +2,11 @@
2
3 These rules apply to both Composio products.
4
5 -## Start with the log ID
5 +## Start in Dashboard Logs
6
7 -Get the Composio log ID or request ID before diagnosing a failure. Framework wrappers often hide the underlying error.
7 +Open the applicable product's Dashboard Logs first and use the Composio log ID or request ID to inspect the exact execution. Framework wrappers often hide the underlying error.
8 +
9 +CLI diagnostics are optional. Use them only when the CLI is already installed and configured for the applicable product:
10
11 ```bash
12 composio dev logs tools
@@ -22,7 +24,19 @@ For manual legacy v3 execution, a missing tool is often a toolkit-version proble
24
25 ## Authentication failures
26
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.
27 +Identify which boundary returned the 401 before changing anything.
28 +
29 +### Composio API or session 401
30 +
31 +This failure happens while creating or using a session, before a provider tool call succeeds. The project credential may be invalid, masked, a placeholder, or for the wrong dashboard project.
32 +
33 +Stop and re-run the no-output `COMPOSIO_API_KEY` preflight from the Platform guide. Do not print, rotate, replace, or request the key in chat. Direct the developer to Platform → project → Getting Started → Step 1 when the repository does not have the correct unmasked project credential. The next SDK request, not key length, validates it over the network.
34 +
35 +### Provider tool-call 401
36 +
37 +This failure appears on a real tool execution in Dashboard Logs, usually with a Composio log ID. The Composio project credential and session reached the provider, but the selected user's connected-account credential was revoked, expired, or invalidated by a password, 2FA, consent, or administrator-policy change.
38 +
39 +Keep the same project key and user ID. Generate a fresh Connect Link for that integration, reconnect the account, and retry the safe read-only call. Do not replace the Composio project credential.
40
41 If an authorization link expired, request a new one. Do not reuse it.
42
skills/composio/references/platform.md
+32 -47
@@ -16,43 +16,23 @@ Before choosing packages or generating files, identify:
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
19 +## 2. Require the existing project credential
20
21 -Run from the project directory. Install the CLI when it is missing; upgrade it
22 -first when an installed CLI reports that a newer version is available:
21 +The dashboard Getting Started Step 1 supplies the one project credential as `COMPOSIO_API_KEY=ak_*`. Use that credential from `.env.local`, the current process environment, or the repository's existing secret mechanism.
22
24 -```bash
25 -curl -fsSL https://composio.dev/install | bash
26 -composio dev init
27 -```
28 -
29 -`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.
30 -
31 -Before opening the initializer, run `composio dev projects list` and confirm the
32 -exact project is visible. Do this only when initialization is still required; do
33 -not repeat the online project-list check after a local binding already exists. If
34 -the project is missing, stop and ask the developer to sign in to the account or
35 -organization that owns it. Do not accept the selector's default project.
36 -`--no-browser` changes the login step; project selection is still interactive.
23 +Platform onboarding never creates, rotates, or replaces an API key. Never print the value, place it in a command or URL, copy it to another file unnecessarily, or ask the developer to paste it into chat. The key already identifies the dashboard project; do not select or bind a project separately.
24
38 -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.
25 +Complete this preflight before installing packages or changing application code:
26
40 -After initialization, verify both checkpoints without printing the credential:
27 +1. Find how the repository already loads environment variables or secrets.
28 +2. Check for `COMPOSIO_API_KEY` without opening, echoing, or logging the value.
29 +3. Require the value to begin with `ak_`.
30 +4. Reject values containing `*`, mask glyphs, ellipses, angle-bracket templates, or placeholder words such as `example`, `placeholder`, `replace`, or `your_key`.
31 +5. When the credential is in a file, verify that the containing file is ignored by source control. Check the path only; never print the matching line.
32
42 -- `.composio/project.json` names the exact selected project.
43 -- `.env.local` contains a plausible `COMPOSIO_API_KEY` (`ak_...`, at least 10
44 - characters).
33 +These checks catch missing, masked, or placeholder values. They do not prove that a key is authentic, and key length is not validation. The first SDK request is the network validation.
34
46 -Treat an HTTP error, a missing key, a shorter placeholder key, or an SDK 401 as
47 -incomplete setup. Perform these local checks before any SDK or network call. If
48 -either local checkpoint fails, stop: do not install dependencies, call the CLI or
49 -backend again, change application code, or claim success. Use the dashboard
50 -fallback to create or copy a project key, store it in `.env.local`, then retry
51 -the SDK call.
52 -
53 -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.
54 -
55 -Dashboard fallback: Platform → project → API Keys.
35 +If the credential is missing, masked, placeholder-like, or stored in a tracked file, hard stop before package installation or app-code changes. Direct the developer to Platform → project → Getting Started → Step 1, then resume only after the repository's normal secret-loading path supplies an unmasked value. Do not accept the key through chat.
36
37 ## 3. Install only what the codebase needs
38
@@ -72,17 +52,19 @@ Add a provider package only when the repository's framework requires one, for ex
52
53 Do not introduce a second LLM framework solely for onboarding.
54
75 -## 4. Create a session for the current user
55 +## 4. Preserve the current user identity
56
57 A session is the runtime context for one user. It carries identity, connections, tool scope, and the remote sandbox.
58
59 +Trace the application's current authenticated user or tenant ID before creating a session. Pass that same stable ID to Composio. Do not add a parallel user system, replace an existing session model, or use one shared placeholder identity for multiple users.
60 +
61 TypeScript:
62
63 ```typescript
64 import { Composio } from "@composio/core";
65
66 const composio = new Composio();
85 -const session = await composio.sessions.create("user_123");
67 +const session = await composio.sessions.create(existingUserId);
68 const tools = await session.tools();
69 ```
70
@@ -92,11 +74,11 @@ Python:
74 from composio import Composio
75
76 composio = Composio()
95 -session = composio.sessions.create(user_id="user_123")
77 +session = composio.sessions.create(user_id=existing_user_id)
78 tools = session.tools()
79 ```
80
99 -Use the application's stable database ID in production. Never use a shared `default` identity for multiple users.
81 +Do not pass the API key inline. The SDK reads the existing `COMPOSIO_API_KEY`. If this first SDK request returns a Composio API/session 401, stop and follow [Errors and provider gotchas](errors.md); do not modify packages or application code to work around it.
82
83 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:
84
@@ -134,12 +116,12 @@ For onboarding:
116
117 1. Use the installed Composio skill and the existing agent path.
118 2. Ask the developer which integration they want to try unless the repository already makes the choice clear.
137 -3. Let the session discover the actual toolkit and tool slug; never hard-code or guess one.
138 -4. If the integration is not connected, return the Connect Link, wait for authorization, and retry.
139 -5. Run one safe, read-only tool from the existing agent through the project selected during `composio dev init`.
140 -6. Capture the real result and log ID.
119 +3. Let the session discover the actual toolkit and tool slug for that integration; never hard-code or guess one.
120 +4. If the integration is not connected for the existing user ID, return the Connect Link, wait for authorization, and retry.
121 +5. Execute one safe, read-only tool through the existing agent.
122 +6. Require a real result payload and a non-empty `logId` (`log_id` in Python).
123
142 -The smoke test must hit Composio. A mocked response, Playground call, schema fetch, or SDK initialization does not count.
124 +The proof must hit Composio and the selected provider. A mock, Playground call, tool search, schema fetch, session creation, or Connect Link alone does not count as success.
125
126 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.
127
@@ -151,20 +133,23 @@ Start with managed auth. A custom auth config is needed only for custom branding
133
134 ## 8. Hand off the useful next steps
135
154 -After the first call succeeds, show the developer where to continue:
136 +After the first call succeeds, report:
137 +
138 +- Where Composio was added in the existing codebase.
139 +- Which existing application identity supplies Composio's `userId`, and how the resulting session ID is persisted or resumed.
140 +- The integration and exact read-only tool used.
141 +- A safe summary of the actual result and the Composio log ID.
142 +- Where to continue: Platform dashboard → Logs for the request/response, Users for identity and connections, and Toolkits for integrations.
143
156 -- Logs for the exact request, response, duration, and log ID.
157 -- Toolkits to discover integrations.
158 -- Users for stable per-user identities and connections.
159 -- Auth Configs when the product needs custom authentication behavior.
144 +Link the developer to the relevant framework guide from `https://docs.composio.dev/docs/providers` and the selected integration guide at `https://docs.composio.dev/toolkits/<toolkit>`.
145
146 ## Do not
147
148 - Do not stop after linking documentation.
164 -- Do not use a fixed GitHub starring task as the onboarding concept.
149 +- Do not substitute a canned integration task for the developer's choice or repository context.
150 - Do not create an auth config as a prerequisite.
151 - Do not guess tool or toolkit slugs.
152 - Do not use direct execution for a new agent integration.
168 -- Do not claim success before a real programmatic tool call appears in logs.
153 +- Do not claim success before a real programmatic tool call returns a result and log ID.
154
155 Current documentation index: `https://docs.composio.dev/llms.txt`.