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

# Skills

> Define reusable capabilities your agent can invoke — code scripts plus reference and asset files.

<Info>
  **Field reference:** [`skills`](/reference/skills) — every field, type, default, and tier for this page.
</Info>

Skills are reusable capabilities that extend what your agent can do beyond conversation. A skill bundles a description, an action prompt, one or more Python/JavaScript scripts, and optional reference or asset files. The agent sees each script as a callable tool named `skill_{skill-name}_{script-name}`.

## What a skill contains

| Field           | Description                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Name**        | Lowercase letters, numbers, hyphens only. Used in the generated tool name.                   |
| **Description** | Tells the LLM when to use this skill (up to 200,000 chars — but keep it short and specific). |
| **Action**      | Step-by-step instructions, example inputs/outputs, common edge cases.                        |
| **Scripts**     | Python or JavaScript files. Language is auto-detected from the code.                         |
| **References**  | Text files the script can read at runtime.                                                   |
| **Assets**      | Binary files (images, etc.) the script can use.                                              |

## Adding a skill

1. Open your agent and go to **Skills** in the sidebar.
2. Click **Add Skill** and enter a name (lowercase, hyphenated).
3. Fill in **Description** and **Action**.
4. Expand **+ Scripts** and click **Add Script** to add code. Each script becomes a separate tool the agent can call.
5. Optionally expand **+ References** or **+ Assets** to attach files. Once the skill is saved, **+ Show All Files** lets you manage the full file tree.
6. Make sure the skill toggle is **ON** and click **Save Changes**.

The agent automatically decides when to call which script based on the skill's name, description, action, and the script filename.

## The `ctx` object

Scripts receive a `ctx` parameter giving them access to built-in operations and a bridge to call other tools:

```python theme={null}
async def handle(input, ctx):
    # Call another built-in tool
    result = await ctx.tools.search_data(query=input["query"])
    return {"answer": result}
```

See the [custom-tools-ctx reference](/custom-tools-ctx) for the full API.

## Examples

**Hello world — a formatter.** A skill named `text-tools` with one script that takes a string and returns it title-cased. Description: "Format text — title case, slugify, trim." The agent calls `skill_text-tools_format` whenever a user asks to clean up text. One script, no dependencies, instant.

**Simple — a calculator with a reference table.** A skill named `shipping` with a script that computes a shipping cost, plus a **reference** file `rates.csv` the script reads at runtime. When rates change you edit the CSV, not the code. The agent calls it for "how much to ship 2kg to France?".

**Medium — a multi-script toolkit.** A skill named `invoices` with three scripts: `generate` (build an invoice from line items), `summarise` (total a list of invoices), and `validate` (check a tax ID format). Each becomes its own tool (`skill_invoices_generate`, etc.), and the agent picks the right one per request. Bundling related scripts under one skill keeps them organised and shares the same reference files.

**Complex — a skill that composes built-in tools via `ctx`.** A skill named `research` whose script uses `ctx.tools.web_search(...)` to gather sources, `ctx.tools.web_fetch(...)` to read the top result, and returns a structured digest with a `_render` card so the user sees a formatted summary. The skill orchestrates several platform tools inside one sandboxed call — the agent invokes one tool and gets a multi-step research result back. See [custom-tools-ctx](/custom-tools-ctx) for the bridge API and [Tools → Tool results](/sidebar-menu/tools#tool-results-what-the-agent-sees-vs-what-the-user-sees) for the `_render` contract.

**System-pushing — a domain skill with assets and generated output.** A skill named `report-builder` that reads a **reference** template and a chart **asset**, pulls data via `ctx.tools`, renders a branded PDF/markdown report, and surfaces it to the user as a downloadable file (via the `surface_file` built-in through `ctx`). Bundle the template, logo, and styling as skill files so the whole report-generation capability travels as one importable skill — and use **Upload Skill Definition** to clone it across every agent that needs it.

## Importing a skill

Click **Upload Skill Definition** to import a pre-built skill bundle. This is useful for sharing skills between agents or restoring backups. You can drag in (or paste) a single **Markdown**, **JSON**, **YAML**, or **TOML** file, or upload a `.zip` / `.skill` directory-tree archive that carries the scripts, references, and assets alongside the definition.

### File format

Every format expresses the same four things: a **name**, a **description**, an **action**, and one or more **scripts**.

**Markdown** — the skill name is the top-level `#` heading, then `## Description` and `## Action` sections, then a `## Scripts` section with one `### <script-name>` sub-heading per script (each holding a fenced code block):

````markdown theme={null}
# lookup-order

## Description
Look up a customer's order status by order number.
Use this skill when the user asks about their order,
shipment tracking, or delivery status.

## Action
1. Ask the customer for their order number if not provided
2. Query the order database using the order ID
3. Return the current status, shipping carrier, and tracking link

## Scripts

### lookup
```python
import requests

def lookup_order(order_id: str) -> dict:
    resp = requests.get(f"https://api.example.com/orders/{order_id}")
    resp.raise_for_status()
    return resp.json()
```
````

**JSON** — `name`, `description`, `action`, and a `scripts` array of `{ name, code }` objects. Pass an array of these objects to define several skills at once:

```json theme={null}
{
  "name": "lookup-order",
  "description": "Look up a customer's order status by order number.",
  "action": "1. Ask for the order number\n2. Query the database\n3. Return the status",
  "scripts": [
    { "name": "lookup", "code": "import requests\n\ndef lookup_order(order_id):\n    ..." }
  ]
}
```

**YAML** — the same keys, with `scripts` as a list of `name` / `code` entries:

```yaml theme={null}
name: lookup-order
description: >-
  Look up a customer's order status by order number.
action: |
  1. Ask for the order number
  2. Query the database
  3. Return the status
scripts:
  - name: lookup
    code: |
      import requests

      def lookup_order(order_id):
          ...
```

**TOML** — top-level `name` / `description` / `action`, with each script as a `[[scripts]]` table:

```toml theme={null}
name = "lookup-order"
description = """Look up a customer's order status by order number."""
action = """
1. Ask for the order number
2. Query the database
3. Return the status
"""

[[scripts]]
name = "lookup"
code = """
import requests

def lookup_order(order_id):
    ...
"""
```

## Limits

* Skill names are limited to 64 characters.
* Skills are available on every plan — there is no per-agent skill-count cap.
* Script execution time, memory, and output size are bounded by the code sandbox. Those limits are shared with custom code tools — see [Custom tools](/sidebar-menu/tools).

## Manage via the Management MCP

This page can be configured programmatically through the [Management MCP](/manage-mcp) — useful for AI agents and CI pipelines.

|               |                                                                                           |
| ------------- | ----------------------------------------------------------------------------------------- |
| Endpoint      | `https://manage.agentheya.com/mcp`                                                        |
| Tool          | `config.set`                                                                              |
| Section       | `skills`                                                                                  |
| Schema (HTTP) | [`GET /api/manage-mcp/schema/skills`](https://agentheya.com/api/manage-mcp/schema/skills) |

Example:

```json theme={null}
{
  "tool": "config.set",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "section": "skills",
  "data": { /* see schema for accepted fields */ }
}
```

Partial updates are supported — only the fields you include are changed. Call `config.get` to read the current values and `schema.get` (or the HTTP schema URL above) to see the full field list.