Skills

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

Field reference: skills — every field, type, default, and tier for this page.

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:

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 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 for the bridge API and Tools → Tool results 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):

# 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:

{
  "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:

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:

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.

Manage via the Management MCP

This page can be configured programmatically through the Management 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

Example:

{
  "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.