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

# Agent Skills Tools

> Detailed documentation for the tools used by agents to interact with Skills.

The Agent Skills system provides several built-in tools that allow your AI agents to dynamically interact with, load, and execute the content of Skills during a session.

These tools empower agents to read the instructions defined in a skill, or even execute scripts that are bundled alongside a skill's `SKILL.md` file.

## Available Skill Tools

There are two primary tools that handle skill operations:

### 1. `activate_skill`

Loads the full instructions and content of a specialized skill. An agent will use this when it determines that the user's request matches a skill's description, allowing it to "page in" the necessary context.

**Input Parameters:**

* `skill_id` (string, required): The UUID of the skill to activate.

**Output:**

* Returns the full content (`SKILL.md`) of the skill wrapped in XML-like tags, informing the agent of the virtual directory where the skill's files reside.

### 2. `read_execute_skill_file`

Allows the agent to read an attached file OR execute a script from a skill's bundle.

If the agent asks to read a text file or markdown file from the skill's virtual directory, this tool reads and returns the text. If the agent asks to execute a Python script (`.py`), this tool safely executes the script within the UBIK logic node environment and returns the output.

**Input Parameters:**

* `skill_id` (string, required): The UUID of the skill.
* `file_path` (string, required): The relative path of the file (e.g., `scripts/run.py` or `docs/info.md`).
* `args` (array of strings, optional): Command-line arguments to pass if executing a python script.

**Output:**

* `status`: Success or error.
* `action`: Either `'read'` or `'executed'`.
* `content`: The text content (if read).
* `stdout` / `stderr`: The standard output and error streams (if executed).
* `artifacts` / `generated_files`: Arrays containing any files, images, or data generated by the script during execution. These files can be retrieved using the `GET /assets/tools/{tool_id}/{execution_id}/{filename}` endpoint.

## How Agents Use Skill Tools

When you attach a Skill to an Agent, the agent is automatically made aware of the skill's name and description.

1. **Trigger:** The user asks a question (e.g., "Analyze this dataset using our standard methodology").
2. **Activation:** The agent realizes it has a "Data Analysis Methodology" skill. It calls `activate_skill` with that skill's ID to retrieve the detailed steps.
3. **Execution:** The skill's instructions might tell the agent to run a specific script. The agent then calls `read_execute_skill_file` with the path `scripts/analyze.py` to perform the work.
4. **Completion:** The agent reads the `stdout` of the script and formulates a final response for the user.