Skip to content

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

docs(skills): clarify surface discovery

Kshitij Jhunjhunwalaecd9b5ada801
diff --git a/skills/composio/references/for-you.md b/skills/composio/references/for-you.md
index feca5af8e..edd9fedf6 100644
--- a/skills/composio/references/for-you.md
+++ b/skills/composio/references/for-you.md
@@ -15,6 +15,20 @@ The removed `mcp.composio.dev` endpoint and Platform MCP URLs are not substitute
Default to MCP for desktop and hosted AI clients. Use the CLI for terminal agents that can execute commands and operate tools directly.
+### Know what each surface installs
+
+These surfaces are complementary. Installing one does not automatically install the others.
+
+| Surface | What the agent discovers |
+|---|---|
+| Raw Composio MCP connection | Callable tools and their schemas. MCP does not install an agent skill. |
+| Public `composio` skill | This product-and-job router. Install it explicitly from `ComposioHQ/composio`. |
+| Composio CLI | The `composio` command plus the separately maintained `composio-cli` skill when the CLI's agent setup flow installs it. That skill owns current command usage. |
+| OpenAI/Codex plugin | The hosted Composio app plus its bundled `composio-runtime` skill, which selects between hosted tools and the local CLI. |
+| Claude Code plugin | Commands and hooks. It does not bundle a skill; CLI login/setup installs `composio-cli` separately. |
+
+An agent can therefore see Composio tools without seeing either Composio skill, and it can have more than one skill when their roles differ. Use `composio` for product selection and integration guidance, `composio-runtime` for OpenAI plugin routing, and `composio-cli` for CLI operation.
+
### MCP clients
Claude Desktop and ChatGPT use browser OAuth and do not need a consumer key. Header-based clients use the endpoint and header above.