4
keywords: [skills, playbooks, use cases, execution plan, pitfalls, tool sequence, search, sessions, efficiency, tokens]
5
---
6
7
-A **skill** is an execution playbook for one concrete task — "send an email to someone", "post a message to a Slack channel", "query a Notion database". Each skill records the tools the task needs, the order to call them in, and the mistakes that make it fail.
7
+A **skill** is an execution playbook for one concrete task: "send an email to someone", "post a message to a Slack channel", "query a Notion database". It records the tools the task needs, the order to call them in, and the mistakes that make it fail.
8
9
-Composio derives skills from real usage across the platform rather than hand-writing them, so they reflect how these tasks are actually completed in practice.
9
+You don't install skills or reference them by ID. When your agent calls [`COMPOSIO_SEARCH_TOOLS`](/toolkits/meta-tools/search_tools) to find the tools for a task, a skill covering that task comes back in the same response:
10
11
-Your agent does not fetch skills itself. They come back in the search results it already asks for: when the agent searches for the tools to do something, a skill for that use case is returned alongside them.
11
+```json
12
+{
13
+ "primary_tool_slugs": ["SLACK_FIND_CHANNELS", "SLACK_SEND_MESSAGE"],
14
+ "related_tool_slugs": ["SLACK_FIND_USERS"],
15
+ "difficulty": "easy - Simple single-tool operation with known parameters",
16
+ "recommended_plan_steps": [
17
+ "Resolve the channel ID with SLACK_FIND_CHANNELS before posting.",
18
+ "Send the message with SLACK_SEND_MESSAGE using the resolved ID."
19
+ ],
20
+ "known_pitfalls": [
21
+ "Passing a channel name where the API expects an ID returns channel_not_found."
22
+ ]
23
+}
24
+```
25
+
26
+What just happened: your agent asked for tools and got a sequence. `primary_tool_slugs` and `related_tool_slugs` come back on every search. `recommended_plan_steps`, `known_pitfalls`, and `difficulty` appear only when a skill covers the use case, so treat them as optional in your handling.
27
+
28
+Composio derives skills from real usage across the platform rather than writing them by hand, so they reflect how these tasks get completed, not how they ought to work.
29
30
## Why skills matter
31
15
-Handing an agent a toolkit tells it *what* it can call. It does not tell it *how* the call usually goes wrong. An agent discovering that on its own pays for it in tokens and retries:
32
+Handing an agent a toolkit tells it *what* it can call. It doesn't tell it *how* the call usually goes wrong, and an agent that works this out on its own pays for it in tokens and retries:
33
34
- It calls a tool with the wrong identifier, reads the error, and tries again.
35
- It fetches a whole inbox when it needed one search.
36
- It skips a lookup step and posts to a channel that never resolves.
37
21
-A skill front-loads that knowledge. The sequence is already known, and so are the pitfalls, so the work that would have gone into rediscovering them is not spent at all.
38
+A skill front-loads that knowledge. The sequence is already known and so are the pitfalls, so the work of rediscovering them is never spent. Because the skill arrives inside the search response, it lands in your agent's context before the first execution: the sequence is right the first time, and the known failure modes are avoided rather than discovered from an error.
39
40
<Callout type="info">
24
-Skills are read-only. You never attach one to a session or reference it by ID — search matches them to the use case your agent describes, so there is nothing to install, enable, or configure. They are part of search results by default, and there is no opt-out today.
41
+Skills are read-only. Search matches them to the use case your agent describes, so there is nothing to install, enable, or configure. They are part of search results by default, and there is no opt-out today.
42
</Callout>
43
44
## What a skill contains
45
29
-**Use case** — the task in plain language, e.g. *Start a direct message with someone in Slack and send a message*. This is what search matches against.
46
+**Use case.** The task in plain language, for example *Start a direct message with someone in Slack and send a message*. This is what search matches against.
47
31
-**Tools** — the tool slugs the task uses, such as `SLACK_FIND_USERS`, `SLACK_OPEN_DM`, `SLACK_SEND_MESSAGE`. A skill distinguishes the main tools from supporting ones.
48
+**Tools.** The tool slugs the task uses, such as `SLACK_FIND_USERS`, `SLACK_OPEN_DM`, and `SLACK_SEND_MESSAGE`. A skill distinguishes the main tools from the supporting ones.
49
33
-**Execution plan** — the ordered steps for completing the task, including optional steps and fallback paths for when the primary route is unavailable.
50
+**Execution plan.** The ordered steps for completing the task, including optional steps and fallback paths for when the primary route is unavailable.
51
35
-**Pitfalls** — the known failure modes for this task: the wrong-identifier mistakes, the missing lookups, the assumptions that do not hold.
52
+**Pitfalls.** The known failure modes for this task: the wrong-identifier mistakes, the missing lookups, and the assumptions that don't hold.
53
37
-A skill is not limited to one app. A task may span Slack and Gmail, and a skill that spans several toolkits appears under each of them.
54
+A skill isn't limited to one app. A task may span Slack and Gmail, and a skill covering several toolkits appears under each of them.
55
56
## How a skill reaches your agent
57
41
-Skills arrive through the search step a [session](/docs/how-composio-works) already does:
58
+Skills arrive through the search step a [session](/docs/how-composio-works) already performs:
59
60
1. You create a session and give your agent its meta tools.
44
-2. The agent has something to do, so it calls [`COMPOSIO_SEARCH_TOOLS`](/toolkits/meta-tools/search_tools) with the task described in plain language, one `use_case` per query.
61
+2. Your agent has something to do, so it calls `COMPOSIO_SEARCH_TOOLS` with the task in plain language, one `use_case` per query.
62
3. Composio searches for tools and for a skill covering that use case at the same time.
46
-4. The response carries the tools to call, in `primary_tool_slugs` and `related_tool_slugs`, along with their schemas. When a skill covers the use case, the same response also carries the skill: `recommended_plan_steps`, `known_pitfalls`, and `difficulty`.
47
-5. The agent works through the returned steps in order and checks the pitfalls as it goes, instead of inferring a sequence from the tool schemas.
48
-
49
-The agent gets tools either way. What the skill adds is the part the tools cannot tell it: the order to call them in and the mistakes that break the task. Because it arrives inside the search response, it lands in the agent's context before the first execution, so the sequence is right the first time and the known failure modes are avoided rather than discovered from an error.
63
+4. The response carries the tool slugs and their schemas. When a skill covers the use case, that same response carries the plan and pitfalls.
64
+5. Your agent works through the returned steps in order and checks the pitfalls as it goes, instead of inferring a sequence from the tool schemas.
65
51
-Search matches on the use case, not on a tool name, so the phrasing the agent uses matters. "Start a DM with someone in Slack and send them a message" matches a skill; "slack tools" does not.
66
+Search matches on the use case, not on a tool name, so the phrasing your agent uses matters. "Start a DM with someone in Slack and send them a message" matches a skill. "slack tools" does not.
67
53
-Skills ride inside the search response. There is no separate contract for them, so nothing in your code has to ask for them.
68
+Note that skills ride inside the search response, so there is no separate contract to code against and nothing in your application has to ask for them.
69
70
<Callout type="info">
56
-There is no API for listing or reading skills, so unlike most of Composio there is no cURL equivalent on this page. Your agent still receives them at runtime through search — the limit is on browsing the catalog yourself. This page will be updated when that changes.
71
+There is no API for listing or reading skills, so unlike most of Composio there is no cURL equivalent on this page. Your agent still receives them at runtime through search. This page will be updated when that changes.
72
</Callout>
73
74
## Related
75
61
-- [How Composio works](/docs/how-composio-works) — sessions, meta tools, and where search fits
62
-- [`COMPOSIO_SEARCH_TOOLS`](/toolkits/meta-tools/search_tools) — the search meta tool and its response fields
63
-- [Configuring sessions](/docs/configuring-sessions) — how you give an agent access to tools
76
+- [How Composio works](/docs/how-composio-works): sessions, meta tools, and where search fits.
77
+- [`COMPOSIO_SEARCH_TOOLS`](/toolkits/meta-tools/search_tools): the search meta tool and its response fields.
78
+- [Configuring sessions](/docs/configuring-sessions): how you give an agent access to tools.