> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Skills

> Create and manage modular, reusable Skills that agents discover and execute at runtime

## What Are Skills?

Skills are reusable capability modules that agents can discover and run at runtime. Each Skill has a name, description, prompt instructions, and one or more configured tools. Instead of wiring every tool into each agent manually, you build Skills once in the Skills Directory; agents then find and use them dynamically based on context.

***

## When to Use Skills vs Tools

Agents can take action through both [tools](./agents-tools-and-deployment#configure-agent-tools) and Skills. The right choice depends on how tightly coupled the capability is to a single agent versus how broadly it needs to be shared.

| Consideration   | Tools                                             | Skills                                                         |
| --------------- | ------------------------------------------------- | -------------------------------------------------------------- |
| **Scope**       | Configured directly on one agent                  | Created once in the Skills Directory, available to many agents |
| **Setup**       | Admin adds and configures each tool on the agent  | Admin builds the Skill once; agents discover it at runtime     |
| **Reusability** | Must be recreated on every agent that needs it    | Shared across any agent with Skills enabled                    |
| **Maintenance** | Update each agent individually when logic changes | Update the Skill once and all agents pick up the change        |
| **Best for**    | Capabilities specific to a single agent's purpose | Common capabilities used across multiple agents or apps        |

<Tip>Start with tools when an agent needs a one-off capability. Promote a tool to a Skill when you find yourself configuring the same automation on multiple agents.</Tip>

***

## Create a Skill

App admins create and manage Skills under **Intelligence → Skills**.

1. Open **Intelligence** in your app.
2. Click the **Skills** tab at the top of the page.
3. Enter a name, description, prompt instructions, and one or more tools.
4. Click **Create Skill**.

**Skill fields:**

* **Name** and **Description** — How the Skill is identified and when it should be used
* **Prompt instructions** — Instructions the agent follows when executing the Skill
* **Tools** — One or more tools that implement the Skill's behavior. Skills support the same tool types as agents: Run Automation, Create Record, Update Record, Search Records, AI Search, and Run Agent. Configuring tools on a Skill follows the same workflow as configuring tools on an agent — for field-by-field setup steps for each tool type, see [Configure Agent Tools](./agents-tools-and-deployment#configure-agent-tools).

<Tip>Skills that use Create Record, Update Record, Search Records, AI Search, or Run Agent run natively in Elementum — you don't need to build a separate automation to wrap them. Use **Run Automation** when you want the Skill to trigger an existing On-Demand automation.</Tip>

**Lifecycle status:**

| Status       | Behavior                                          |
| ------------ | ------------------------------------------------- |
| **Draft**    | Not available to agents; use for work-in-progress |
| **Active**   | Available to agents when Skills are enabled       |
| **Disabled** | Temporarily hidden from agents; can be re-enabled |

Only **Active** Skills appear when agents search or use Skills at runtime. **Draft** Skills never appear in search.

***

## Configure Access Policies

Access policies control which users can have a Skill discovered for them at runtime. When a user interacts with an agent, the agent only sees Skills the user is authorized to use.

1. Open **Intelligence → Skills** and select the Skill.
2. Open the **Access Policy** section.
3. Add the users or groups that should be able to access the Skill.
4. Save your changes.

**Behavior notes:**

* If no access policies are configured, the Skill is available to every user in your organization.
* Access policies are evaluated per user at runtime, so the same agent may discover different Skills for different users.

***

## Tune Skill Discovery

Discovery properties tell an agent when a Skill is the right fit for a request. The agent combines all configured properties into a weighted score and ranks candidate Skills, so well-tuned Skills surface ahead of weaker matches as your catalog grows.

1. Open **Intelligence → Skills** and select the Skill. Use the status filter at the top of the page to narrow the list to **Draft**, **Active**, or **Disabled** Skills.
2. Open the **Discovery** section.
3. Configure any of the following properties:
   * **Routing Priority** — Increase the weight of this Skill when multiple Skills could apply to the same request.
   * **Aliases** — Add alternate names the agent should recognize for this Skill.
   * **Example Utterances** — Add sample phrases a user might say when this Skill should be selected.
   * **Positive Keywords** — Add words and phrases that should make the Skill more likely to be discovered.
   * **Negative Keywords** — Add words and phrases that should make the Skill less likely to be discovered.
4. Save your changes.

<Tip>
  Small tuning changes can shift which Skill wins for a given request. Adjust one property at a time and re-test so you can see the impact.
</Tip>

### Test a Skill

Test how an agent ranks Skills against a sample request before exposing the Skill to users.

1. On the Skill page, click **Test Skills** in the top-right corner.
2. Enter a **Query** that represents what a user might ask.
3. Select the **Agent** to test against.
4. Optionally select one or more **Users** so the test honors the Skill's access policy for those users.
5. Click **Run Query** to see which Skills are returned and how they are ranked.

Use the test results to refine the discovery properties or access policy until the right Skill consistently surfaces for the right users.

***

## Add Skills to an Agent

1. In **Intelligence**, select an agent.
2. Click **Configure**.
3. Choose the Skills you'd like the agent to have access to (including **All App Skills**).
4. Click **Save**.

<Note>If you know an agent will always need a specific Skill, add up to 3 preloaded Skills the agent can access immediately — skipping the runtime search step.</Note>

The **Skill Access** setting controls the agent's access level:

| Mode         | Behavior                                                                                |
| ------------ | --------------------------------------------------------------------------------------- |
| **None**     | Agent has no Skills (default for new agents)                                            |
| **All**      | Agent can discover and use all active Skills in the agent's own app                     |
| **Selected** | Admin picks specific Skills from a checkbox table within the agent's own app            |
| **Custom**   | Admin picks specific Skills from any app in the organization, including the agent's own |

In **Selected** mode, use the checkbox table to choose exactly which Skills the agent can use. This gives fine-grained control when you have many Skills but want each agent to use only a subset.

### Share Skills Across Apps

Use **Custom** access when you want an agent to use Skills that live in other apps. Build a Skill once in the app that owns the data or process, then make it available to agents elsewhere in your organization without duplicating configuration.

To configure cross-app Skills:

1. Open the agent and click **Configure**.
2. Expand the **Skill Access** section.
3. Under **Access Mode**, select **Custom** and click the settings icon to edit the **Custom skills available** list.
4. Search for and select active Skills from any app in your organization.
5. Click **Done**, then click **Save**.

**Behavior notes:**

* Agents discover and execute cross-app Skills the same way they use local Skills — no additional setup is required at runtime.
* Only **Active** Skills surface in the Custom picker; **Draft** and **Disabled** Skills are excluded.
* When an agent is deployed, the apps that provide its configured Skills are automatically included in the deployment so the Skills remain accessible.

***

## Runtime Behavior

When Skills are enabled (any mode other than **None**), the agent automatically receives discovery tools — no manual tool setup is required. At runtime, the agent uses Skills in three steps:

1. **Search** — The agent calls the Skill search tool to find Skills relevant to the user's request.
2. **Details** — For a chosen Skill, the agent retrieves the name, description, instructions, and configured tools.
3. **Execute** — The agent runs the Skill's behavior by invoking its configured tools. Create Record, Update Record, Search Records, AI Search, and Run Agent tools execute natively in Elementum; Run Automation tools trigger the linked On-Demand automation.

***

## Operational Notes

* Only **Active** Skills surface at runtime; **Disabled** Skills do not.
* New agents default to **None**; enable Skills explicitly if you want the agent to use them.
* After changing a Skill's status or an agent's **Enabled Skills** mode, allow a moment for the agent to see the updated set.

***

## Troubleshooting

If an agent isn't using the Skill you expect, work through the checks below.

### Confirm the Skill is Active

Skills must be **Active** to surface at runtime. Open **Intelligence → Skills** and confirm the Skill's status reads **Active**. If it doesn't, select the Skill and click **Activate** in the top right corner.

### Make the Name and Description Discoverable

Agents discover Skills by searching the name and description. If either is too generic, the agent may not find the Skill — or it may pick up the wrong one. Use specific, task-oriented wording that reflects when the Skill should be used.

### Review the Conversation History

Open the agent's conversation history and check what happened during the request:

* **Is the agent trying to discover Skills at all?** If the agent answers without searching, it may not realize a Skill is relevant. Adjust the agent's prompt to point it toward the Skills Directory for the kind of request you're testing.
* **Is the agent running the Discover Skills tool?** If the tool isn't being called, prompt the agent differently so it knows to search for an existing Skill before attempting to act on its own.
* **Are the wrong Skills coming back?** Look at the query the agent used to search. Either refine the Skill's name and description to better match how the agent phrases the request, or update the agent's instructions to guide it toward better search queries.

***

## Related Documentation

* [Agent tools, deployment, and integrations](./agents-tools-and-deployment) — Tools reference, deployment, and external agents; includes how Skills fit into agent tools
* [Building Agents](./agents-experience) — Create and configure agents, including tools and channels