Preface¶
The most common bottleneck when writing Agents often lies not with the model itself, but in how to connect to other software. Sending a Gmail, replying to a message on Slack, opening a GitHub Issue—each time you integrate a service, you have to read its API documentation, go through OAuth, handle token refresh, and manage multi-user isolation. As more applications are added, this work will overwhelm the actual business logic.
What Composio does is wrap this layer into a unified CLI and SDK: search for tools, connect accounts, execute actions, and listen for events. The official team has also turned this usage into an Agent Skill, allowing programming assistants that support SKILL.md such as Cursor, Claude Code, and Codex CLI to follow the same workflow when they need to operate external applications, instead of re-reading documentation every time.
This article introduces the composio Skill maintained by ComposioHQ: what it is, what is in the repository, how to install it, how to use the CLI to directly call tools, and how to integrate third-party applications into your own Agent using the SDK. The commands and configurations in this article are cross-checked against the official Skill text, the repository README, and docs.composio.dev.
What Is This¶
composio is an official Agent Skill released by Composio, hosted in the ComposioHQ/skills repository under the MIT license. The Skill directory is located at skills/composio/, with the entry file SKILL.md positioned as:
Use 1000+ external apps via Composio - either directly through the CLI or by building AI agents and apps with the SDK
In one sentence: Use 1000+ external applications through Composio, with two parallel paths—execute directly via the CLI in your terminal, or integrate with the SDK in your own Agent/application.
Composio itself is an Agent execution platform. Its official documentation and SDK repository state that it provides 1000+ pre-authenticated toolkits, user-isolated sessions, hosted OAuth, Triggers, and a local CLI for coding Agents. Services like Gmail, Slack, GitHub, Notion, and Linear are called toolkits in Composio; specific actions (such as creating a GitHub Issue) are called tools, with slugs similar to GITHUB_CREATE_ISSUE.
The Skill repository contains more than just a brief introduction, with the following structure:
skills/
└── composio/
├── SKILL.md # Main entry: when to enable, CLI / SDK two paths
├── AGENTS.md # Full version automatically merged from rule files
└── rules/ # Themed rules (CLI, Tool Router, Triggers, etc.)
SKILL.md handles routing: first determine whether the user is “directly operating external applications” or “writing code for integration”, then point to the corresponding rules. AGENTS.md combines all the rules into a single file for easy one-time reading. The repository README notes that there are currently 14+ rules covering Tool Router and Triggers, with examples provided in both TypeScript and Python.
Core Features¶
According to the “When to Apply” section of SKILL.md, this Skill will be enabled for the following types of tasks: accessing external applications such as Gmail / Slack / GitHub / Notion; automating with external services (sending emails, creating issues, sending messages); connecting third-party tools to AI Agents or applications; multi-user applications needing separate account connections per user.
After verification, the capabilities can be divided into four parts.
1. Execute directly via CLI without writing integration code first¶
The main workflow provided by the Skill is search → link → execute: first search for tools in natural language, connect the user’s account to the corresponding application when necessary, then execute via the tool slug. The official CLI documentation also lists composio search, composio execute, and composio link as the three most commonly used commands. The CLI also supports composio proxy (use hosted authentication to call the service’s native API) and composio run (write multi-step workflows with inline TypeScript).
2. Use SDK for user-isolated sessions for Agents¶
When writing code, the official recommended entry point is composio.create(user_id) (also written as composio.sessions.create(user_id=...) on the Python side). Each user gets one session, and all connections and tool calls are tied to this ID. session.tools() provides the Agent with a small set of meta tools for discovery, connection, and execution, instead of shoving thousands of tool schemas into the context at once. The same session can also be exposed as an MCP endpoint via session.mcp.url for use by MCP clients such as Cursor and Claude Desktop.
3. Hosted OAuth and per-user connections¶
The default path in the official documentation is for Composio to host authentication: when the Agent needs a toolkit during runtime, it initiates a connection, and the user opens the Connect Link to complete authorization. OAuth redirects, token exchange, and refresh are handled by the platform; after connecting once, subsequent sessions can reuse the already linked account. In multi-tenant scenarios, the Skill’s Tool Router rules explicitly require: do not share one session across multiple users.
4. Triggers: Drive workflows with external events¶
The Skill covers creating trigger instances, subscribing to events during development, validating webhooks in production environments, and enabling/disabling lifecycles. The CLI can listen to real-time events. The current official CLI documentation places event streaming under composio dev listen; the Skill rule file still lists the top-level composio listen. It is more reliable to follow the current CLI documentation, and refer to the local composio --help for the exact commands.
Installation and Enabling¶
You need to distinguish two things: installing the Skill into AI programming tools, and installing the Composio CLI (and optional official plugins) onto your local machine. The former teaches Agents “how to use Composio”, while the latter is the actual runtime that sends requests and goes through OAuth.
1. Install the composio Skill¶
The installation command given in the repository README is:
npx skills add composiohq/skills
The equivalent写法 on officialskills.sh is to specify the repository and skill name:
npx skills add https://github.com/ComposioHQ/skills --skill composio
Both commands point to the same repository. npx skills add is the universal installer in the Agent Skills ecosystem, which can link SKILL.md to the skills directory of various tools. According to the Cursor documentation and skills CLI conventions, common installation locations are as follows (refer to each tool’s official instructions for accuracy):
- Cursor: project-level .cursor/skills/ or .agents/skills/, user-level ~/.cursor/skills/ or ~/.agents/skills/
- Claude Code: project-level .claude/skills/, user-level ~/.claude/skills/
- Codex CLI: project-level .agents/skills/, user-level ~/.codex/skills/
After installation, restart the Agent, or reload the skills as instructed by the tool you are using. You can also copy the entire skills/composio/ directory to the above path, ensuring the directory name matches name: composio in SKILL.md.
2. Install and log in to the Composio CLI¶
Both the Skill and the official CLI documentation require that you have the CLI on your local machine and have logged in. The official installation command is:
curl -fsSL https://composio.dev/install | sh
SKILL.md uses | bash with the same installation script address. The installer will place the release package in ~/.composio, create an entry point at ~/.local/bin/composio, and modify your shell startup file to add the CLI to your PATH. It supports Linux x64 / ARM64, macOS Intel / Apple Silicon; Windows requires installation in WSL. After installation, open a new terminal and log in:
composio login
composio whoami
composio --version
composio login uses OAuth, and after logging in, you will have an interactive organization/project selection; add -y to skip the selector and use the session defaults. whoami is used to confirm your org_id, project_id, and user_id; the official documentation states that the API key will not be displayed here, and you should not hardcode these values into code.
When the Agent cannot open a browser directly, the Skill provides a two-step login:
composio login --no-wait | jq
# Send the login URL in the output to the user, who completes authorization in the browser:
composio login --key "<cli_key>" --no-wait
The official documentation also provides native plugin installation for Codex / Claude Code:
composio setup --target auto
auto will detect installed Agents on your local machine. If only one is present, you can use --target codex or --target claude. Add --yes for non-interactive environments. This plugin and the composio Skill in ComposioHQ/skills are two separate lines: the plugin teaches Agents to call the local CLI; the Skill in the repository additionally includes complete rules for SDK, Tool Router, and Triggers. You can use both sets if needed.
3. Initialize the SDK in your project¶
When using the SDK path, first execute in your project directory:
composio init
The current official CLI documentation lists project context initialization under composio dev init. Refer to your local CLI help for accuracy. Obtain your API key from the Composio Dashboard, and use an environment variable locally:
COMPOSIO_API_KEY=your_composio_api_key
The TypeScript SDK requires Node.js 22.22.3 or higher, and is ESM-only, using import instead of require(). The Python SDK requires Python 3.10 or higher.
# TypeScript
pnpm install @composio/core@latest
# Python
pip install composio
Install the corresponding provider package according to the Agent framework you are using. Common TypeScript package names: @composio/vercel, @composio/openai-agents, @composio/langchain, @composio/claude-agent-sdk. Common Python package names: composio-openai-agents, composio-langchain, composio-langgraph, composio-crewai, composio-claude-agent-sdk. Pass the provider into the Composio constructor, instead of only installing the core package and calling tools formatted for another framework.
Typical Usage¶
1. CLI: search → link → execute¶
The following commands come from the Skill’s CLI rules and official CLI documentation, and can be run directly in a logged-in terminal.
First search for tools by use case. The search results include connection status, showing whether the account has been linked to the corresponding application. Do not truncate the output of composio search with head, as truncation may hide more suitable matches:
composio search "send an email"
composio search "create github issue"
composio search "summarize my unread gmail"
Link if you have not connected yet. By default, it will open a browser and wait until the account becomes ACTIVE; add --no-wait for Agent or script scenarios, print JSON (including redirect_url) and exit immediately:
composio link gmail
composio link github
composio link slack
Before executing, you can view the parameter schema, then call with JSON data. The Skill rules use the long option --data, while the official CLI documentation and SKILL.md use -d:
composio execute GMAIL_SEND_EMAIL --help
composio execute GMAIL_FETCH_EMAILS --get-schema
composio execute GMAIL_SEND_EMAIL -d '{"recipient_email":"you@example.com","subject":"Hello","body":"Test"}'
composio execute GITHUB_CREATE_AN_ISSUE -d '{"owner":"acme","repo":"my-repo","title":"Bug report"}'
composio execute GMAIL_FETCH_EMAILS \
-d '{ query: "is:unread newer_than:1d", max_results: 10 }'
To execute on behalf of a specific user, add --user-id (the CLI’s default user context is the project’s test_user_id):
composio execute GMAIL_SEND_EMAIL --user-id "user_123" -d '{"recipient_email":"them@example.com","subject":"Hi"}'
If you are unsure of the slug, first look up the toolkit / tool instead of making up the name:
composio manage toolkits info "gmail"
composio manage tools info "GMAIL_SEND_EMAIL"
composio search "send email"
The current official CLI documentation also lists similar queries under composio dev toolkits .... Refer to your local help text for accuracy.
Multi-step, parallelizable workflows can use composio run. The official documentation gave an example of pulling emails and issues in parallel:
composio run '
const [emails, issues] = await Promise.all([
execute("GMAIL_FETCH_EMAILS", { max_results: 5 }),
execute("GITHUB_LIST_REPOSITORY_ISSUES", { owner: "composiohq", repo: "composio", state: "open" }),
]);
console.log({ emails: emails.data, issues: issues.data });
'
2. SDK: Create a session per user, pass tools to the Agent¶
The Skill’s Tool Router rules emphasize: create a separate session for each user, and explicitly limit the toolkit. The TypeScript example is as follows (from tr-session-basic.md):
import { Composio } from '@composio/core';
const composio = new Composio();
const session = await composio.create('user_123', {
toolkits: ['gmail', 'slack']
});
console.log('Session ID:', session.sessionId);
console.log('MCP URL:', session.mcp.url);
The Python equivalent:
from composio import Composio
composio = Composio()
session = composio.create(
user_id="user_123",
toolkits=["gmail", "slack"]
)
print(f"Session ID: {session.session_id}")
print(f"MCP URL: {session.mcp.url}")
Do not call create() every time in multi-turn conversations. The official Quickstart practice is to store session.session_id (TS: session.sessionId) in your own database, and use composio.use(session_id) to restore it next time. In production environments, replace user_id with a stable user ID from your application’s database; the example user_123 is only suitable for local testing.
When connecting to OpenAI Agents, use the dedicated provider package, do not mistakenly use @composio/openai / composio-openai which are designed for Chat Completions. The minimal example from the official README:
import { Composio } from "@composio/core";
import { OpenAIAgentsProvider } from "@composio/openai-agents";
import { Agent, run } from "@openai/agents";
const composio = new Composio({ provider: new OpenAIAgentsProvider() });
const session = await composio.create("user_123");
const tools = await session.tools();
const agent = new Agent({
name: "Personal Assistant",
instructions: "You are a helpful assistant. Use Composio tools to take action.",
tools,
});
const result = await run(agent, "Summarize my emails from today");
console.log(result.finalOutput);
If you need to use MCP without installing a framework provider, point your client to session.mcp.url (and the required headers as specified in the documentation).
3. Let coding Agents handle tasks directly in conversation¶
The prompt given in the official Agent plugin documentation does not rely on remembering slugs in advance, for example:
- List the open GitHub issues assigned to me.
- Summarize the unread Gmail messages I received today.
- Create a Linear issue from these release notes: ...
The Agent will first run composio search, run composio link and provide a Connect Link when authorization is needed, and then run composio execute after approval. When the composio Skill is installed locally, similar natural language tasks will also be processed according to the CLI / SDK rules in the Skill.
Applicable Scenarios and Notes¶
It is suitable for the following types of work:
- Individuals or coding Agents directly operating connected SaaS in the terminal, without wanting to write integration code for one-off tasks
- Building multi-user Agents: each end user connects their own Slack / Gmail / GitHub, instead of sharing a single bot account
- Writing Agents using frameworks such as OpenAI Agents, Claude Agent SDK, Vercel AI SDK, LangChain, CrewAI, and wanting session-hosted tool discovery and authentication
- Already have an MCP client and want to connect to Composio’s toolkits via the session’s MCP endpoint
- Need external triggers such as new Gmail emails or GitHub events to drive subsequent workflows
There are a few points to keep in mind when using it.
Do not make up tool / toolkit names. The Skill clearly states: only use the results returned by composio search; verify application names with composio manage toolkits info or `composio manage