> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/agent-builder/build/adding-a-skill-to-the-agent.md).
# Adding a Skill to the Agent
Skills define what an agent can *do* at runtime. While knowledge gives the agent information to reference, skills allow it to take actions — such as calling APIs, executing code, querying databases, interacting with external systems, or invoking other agents.
This flow allows you to attach new capabilities to an agent directly from the Builder Canvas through the **Add Skill to Agent** workflow.
***
### Understanding Skills
Different skill types are designed for different runtime actions. Before adding a skill, identify the type of capability your agent needs.
| Use Case | Recommended Skill Type |
| ------------------------------------------------- | -------------------------------------- |
| Call external APIs or services | **API Call** |
| Execute backend business logic | **Python Code** or **JavaScript Code** |
| Query structured databases using natural language | **Structured Data Query** |
| Connect to external MCP tools or systems | **MCP Server** |
| Reuse another agent as part of a workflow | **Agents** |
| Use internally created reusable capabilities | **Custom Skills** |
If you are unsure where to begin, start with the **Skill Library** tab.
***
## Add a Skill to the Agent
### Step 1 — Open the Add Skill Flow
From the Builder Canvas, click **+ Add Skill** in the Skills section below the agent node.
Opening the Add Skill flow from the canvas.
This opens the **Add Skill to Agent** dialog.
***
### Step 2 — Choose a Skill Source
The dialog is organized into multiple tabs to help you discover skills from different sources.
| Tab | Description |
| ------------------------- | ------------------------------------------------ |
| **All** | Displays all available skills across sources |
| **Skill Library** | Platform-provided skills maintained by Uptiq |
| **Custom Skills** | Skills created within your workspace |
| **Uptiq MCP Marketplace** | Curated MCP-based integrations and tools |
| **Agents** | Existing agents that can be reused as sub-agents |
| **MCP Marketplace** | External third-party MCP integrations |
Switching tabs automatically filters the available skill list.
***
### Step 3 — Search for a Skill
Use the **Search Skills** field to quickly filter skills by name or capability.
Search results are scoped to the currently selected tab.
***
### Step 4 — Select the Skill
Click a skill to open its configuration form.
Each skill card includes:
* Skill name
* Capability summary
* Skill type
* Author or provider attribution
The configuration experience varies depending on the selected skill type.
***
### Step 5 — Configure and Save
Configure the selected skill based on its runtime requirements.
Examples:
| Skill Type | Typical Configuration |
| --------------------- | ----------------------------------------------- |
| API Call | Endpoint, headers, authentication, request body |
| Python / JavaScript | Runtime logic and execution code |
| Structured Data Query | Database connection and schema mapping |
| MCP Server | Server URL, credentials, tool access |
| Agent | Agent selection and invocation configuration |
Secrets and variables can be referenced dynamically using:
* `$secret.{name}`
* `$agent.{name}`
This enables reusable and secure runtime configuration.
***
## What Happens After Adding a Skill
Once saved, the skill becomes available to the agent during runtime execution.
The agent planner can now decide when to invoke the skill based on the incoming user request and the agent instructions.
The Builder Canvas and Manage Agent views are also updated to reflect the newly attached capability.
***
## Common Issues and Troubleshooting
### The Agent Does Not Use the Skill
Possible causes:
* The agent instructions do not describe when the skill should be used
* The skill description is too generic or unclear
* Another skill is being prioritized by the planner
Improving the skill description and refining agent instructions usually resolves this.
***
### The Skill Fails During Runtime
Check:
* Authentication and credentials
* Endpoint configuration
* MCP server availability
* Runtime syntax or dependency errors
Use Monitoring and execution traces to inspect failures in detail.
***
### The Required Skill Cannot Be Found
Try switching to the **All** tab to search across every source.
If the capability does not exist yet, create it through **Custom Skills** or connect it via MCP integrations.
***
## Why Skills Matter
Skills are the operational layer of the agent runtime.
Without skills, agents can only generate responses. With skills, agents can execute workflows, retrieve live data, interact with systems, automate tasks, and orchestrate multi-step business actions.
The most effective agents combine:
* Strong knowledge sources
* Well-defined instructions
* Carefully selected runtime skills
This combination enables agents to move beyond conversational responses into real operational execution.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.uptiq.ai/agent-builder/build/adding-a-skill-to-the-agent.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.