Show the app connection picker or setup widget when users ask to connect apps, reopen setup, or need an app that isn't connected yet. Use QM’s authenticated backend for app discovery, consent, and execution without exposing project keys.
88%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Low
Low-risk findings worth noting
Use this skill for app discovery, consent, and execution through QM's authenticated backend. Check availability with GET /v1/composio/toolkits; an absent sandbox API key is expected. Never ask regular users to provision a Composio project key.
Connect them here, then do the work with their skill, which runs over the same connection and carries the app's know-how (Gmail's helper builds drafts that render properly and thread replies; Drive pages shared drives). Don't use this skill's generic tools for them.
| Toolkits | Skill |
|---|---|
gmail, googlecalendar, googletasks | google-workspace |
googledrive, googledocs, googlesheets, googleslides | google-drive-sheets |
dropbox | dropbox |
linear | linear |
zoom | zoom |
Those skills call POST /v1/composio/proxy, which forwards one raw request to the app's own API through the caller's connection, and only reaches those apps' API hosts. Use execute below for every other app.
{"method","url","query"?,"headers"?,"body"?|"bodyBase64"?,"accountId"?} — the same method, URL, query, headers and JSON body as a direct call, without Authorization.409 not_connected names the app to connect: offer the connect option above. 409 choose_account lists matching connections: ask which, then pass accountId.curl -o file). For a non-JSON upload, send bodyBase64 with a content-type header. One request carries about 3 MB of file data; send larger files with the provider's chunked or resumable upload.502 composio_proxy_failed gives cause, providerStatus and providerDetail (the provider's own error); don't automatically retry a write.When the user asks to connect apps, browse integrations, or show setup again in web chat, include the following directive as its own paragraph in your reply, with blank lines around it:
::connect-apps{}Write the directive directly, without a code fence or quotation. The web UI renders only the searchable app picker in place. To display the separate Add to Slack action, use ::add-to-slack{} as its own paragraph instead. Include both directives in separate paragraphs when the user asks for full setup. The Slack action is available to administrators; other users should ask their administrator to install QM. Do not repeat the welcome or celebration. Rendering the widget does not authorize any service or require an SDK call; the user chooses an app and completes provider consent. Do not claim accounts are connected without verified status. For Slack conversations, use ordinary authorization links instead of this web-only directive.
Check connections before work that depends on an app. If the app is in the catalog but not connected, ask for it in your first reply: do any part that doesn't need the app, show the connect option, and stop. Don't finish a long partial answer first.
toolkits lists it. In web chat, use ::link-slack-account{} as its own paragraph for personal Slack access or its connection status. Use ::add-to-slack{} for the separate administrator step of installing the workspace bot, which must be completed first. In Slack conversations, direct the user to QM web Settings (/?view=settings) and Link your Slack account, signed into their existing web account. Never use ::connect-apps{toolkit="slack"} or a generic Slack authorization link. These dedicated widgets do not automatically resume the task; ask the user to reply after connecting.::connect-apps{toolkit="notion"} on its own paragraph, using the exact id from toolkits. It shows a single connect button for that app. After consent the user returns to this conversation, the account is verified, and a message is sent so you can continue the task.authorize (step 3 below) and say you'll pick the task back up when they reply.Each account in connections lists missingScopes: permissions the app's configuration now requests that this connection never got. Providers like X can't upgrade a token in place, so only a fresh consent fixes it.
missingScopes is non-empty, say so in one sentence and offer to reconnect instead of retrying.::connect-apps{toolkit="twitter"}. For a connected app it offers Reconnect and Disconnect, and removes the replaced account itself after a verified reconnect.authorize a new link (step 3 below). Once the new account ID is listed in connections, remove the old one with apps("disconnect", {accountId}), never before.apps("disconnect", {accountId}) on a turn the user started. It only removes their own connections and can't be undone.Use the authenticated QM API from the computer through execute with an explicit sandbox_id. The Composio project key stays in QM's backend. Do not request it from the keychain, install the Composio SDK, use old SDK scripts, or call Composio directly. Existing execute approval and command policies still apply.
const base = process.env.AGENT_API_URL;
const token = process.env.AGENT_API_TOKEN;
async function apps(path, body) {
const response = await fetch(`${base}/v1/composio/${path}`, {
method: body === undefined ? "GET" : "POST",
headers: { "X-Agent-Capability": token, "Content-Type": "application/json" },
...(body === undefined ? {} : { body: JSON.stringify(body) }),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
return result;
}apps("toolkits") and connected accounts with apps("connections"). Follow nextCursor using the cursor query parameter until exhausted. QM derives the account owner from the authenticated run; never supply another user ID.apps("tools?" + new URLSearchParams({toolkit: "gmail", query: "search emails"})). Use actual discovered slugs, input schemas, and concrete versions. Follow pagination. If several accounts match, ask which to use.apps("authorize", {toolkit: "gmail"}). Present the returned url to the user; they consent themselves. Poll connections afterward and only claim success once the returned account ID is listed. For personal Slack identity linking, use the web linking widget described in connect-apps instead of a generic Slack authorization link.apps("execute", {tool: discovered.slug, accountId: account.id, version: discovered.version, arguments: args}). No project key, user ID, custom authentication, or tool-router session is accepted, and raw requests go only through /v1/composio/proxy for the apps above. Inspect successful and error, not just the HTTP status. Never automatically retry an uncertain write.Large pulls (a month of email, a full channel history) fail when one call asks for too much: an oversized page either times out (cause: "timeout") or is rejected by the provider (providerStatus: 413). Page conservatively instead:
ids_only or include_payload: false), then fetch bodies in batches of about 25 for just the messages you need.502, read the JSON body (cause, providerStatus, providerDetail, message); with curl, use --fail-with-body or skip -f so the body survives. Back off and shrink the page rather than repeating the same request.Connected-app calls work only while the turn that issued the token is running. A background job or detached script that outlives its turn gets 403 inactive_run on every call after the turn ends. Do the work as foreground execute calls within a live turn; for recurring or long work, let a cron fire run each batch in the foreground. Have scripts print the HTTP status and body of a failed call instead of folding it into a generic "lookup failed".
The API checks active account ownership and toolkit on every execution. Personal connections are available only in authorized contexts. Shared conversations require explicit sharing; unattended work needs its existing owner-keychain authorization. A denial is not permission to switch credentials, accounts, identities, or access paths.
Do not call Composio's callback completion API from the computer. Callback identity verification belongs to the signed-in browser and trusted QM backend. If verification setup is missing, ask the operator to fix it.
Tools don't transfer files: a local filename passed as an argument uploads nothing. The one exception is X images, below. When Composio is unavailable, use direct OAuth only if independently configured and authorized; do not use it to bypass a denial.
is_html: true) with plain <p> paragraphs and no styling. Plain-text drafts have reached recipients hard-wrapped at about 70 characters.in:sent) shows what was sent. Draft timestamps are creation times, not send times.X's post tool attaches media by ID but can't upload it. Upload the image from the computer first, then post with the returned ID:
const data = (await import("node:fs")).readFileSync("chart.png").toString("base64");
const { mediaId } = await apps("twitter/media", { accountId: account.id, data });Pass mediaId in the post tool's media IDs argument (discover its exact name with tools). Only the caller's own active X connection works. It accepts one PNG, JPEG or WebP image of up to 5 MB per call; for several images, upload each and pass all IDs. GIFs and video aren't supported. Uploading posts nothing and is safe to retry; unattached media expires within a day. A 403 from X (providerStatus) usually means the connection lacks media permission, so offer to reconnect X.
yc-software/qm
c94f65b
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.