Skills

A skill is a named Markdown fragment (an instruction or workflow) that an agent can load during a session. Use one of H’s built-in skills or create your own, then attach it to any agent by name. An agent loads a skill’s full body only when its description looks relevant to the task at hand; the description is the trigger it routes on.

What’s in a skill

Field	Required	Description
`name`	Yes	Identifies the skill in your catalog and is how agents reference it.
`description`	Yes	Tells the agent when to use the skill: the trigger it routes on to decide whether to load the `body`.
`body`	Yes	The Markdown instructions the agent loads when it uses the skill.
`source`	No	Records where the content came from.
`url_pattern`	No	Hints at URLs where the skill applies. Informational, not matched against the live page.

For exact field constraints, see Create a skill.

Create custom skills

Create a skill once, then reference it by name from any agent’s skills array.

Create a skill

curl -X POST https://agp.eu.hcompany.ai/api/v2/skills \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "extract-table-data",
    "description": "Extract structured data from HTML tables into JSON.",
    "body": "When you encounter an HTML table, extract all rows and columns into a JSON array of objects, using the headers as keys."
  }'

from hai_agents import Client

client = Client()

client.skills.create_skill(
    name="extract-table-data",
    description="Extract structured data from HTML tables into JSON.",
    body=(
        "When you encounter an HTML table, extract all rows and columns into a JSON "
        "array of objects, using the headers as keys."
    ),
)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

await client.skills.createSkill({
  name: "extract-table-data",
  description: "Extract structured data from HTML tables into JSON.",
  body:
    "When you encounter an HTML table, extract all rows and columns into a JSON " +
    "array of objects, using the headers as keys.",
});

Attach it to an agent

Reference it by name from the agent’s skills array when you create the agent:

curl -X POST https://agp.eu.hcompany.ai/api/v2/agents \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "table-scraper",
    "description": "Scrapes structured data from web tables.",
    "environments": ["h/browser"],
    "skills": ["extract-table-data"]
  }'

client.agents.create_agent(
    name="table-scraper",
    description="Scrapes structured data from web tables.",
    environments=["h/browser"],
    skills=["extract-table-data"],
)

await client.agents.createAgent({
  name: "table-scraper",
  description: "Scrapes structured data from web tables.",
  environments: ["h/browser"],
  skills: ["extract-table-data"],
});

How an agent uses a skill

An agent doesn’t read every attached skill up front. Each one is advertised to it by name and description in an <available_skills> section of the system prompt, with the body held back:

<available_skills>
<skill>
<name>
extract-table-data
</name>
<description>
Extract structured data from HTML tables into JSON.
</description>
</skill>
</available_skills>

When the agent judges a skill’s description relevant to the task, it calls a built-in load_skill tool with that name. The tool returns the full skill, and its body enters the conversation as instructions for the steps that follow. If the name doesn’t match, the tool replies with the closest available names so the agent can retry. A url_pattern, when set, is listed next to the description as an extra hint; it is not matched against the live page. Environments ship with their own skills too, bundled by default and always in context rather than loaded on demand. These are fixed per environment, not something you configure.

Write effective skills

Make the description a trigger, not a summary. It is the only thing the agent sees before loading a skill, so phrase it as “use this when…” and name the situation precisely. Vague descriptions get loaded at the wrong time or not at all.
Keep the body self-contained. The agent reads it cold, mid-task, so write a focused procedure (steps, formats, edge cases) rather than background prose.
Put always-on behavior in the agent’s instructions. Reserve skills for procedures that only apply some of the time, so they stay out of context until they are relevant.
Compose small skills. Several narrow skills route better than one broad skill, because each description can target a distinct situation.

Built-in skills

H maintains a catalog of computer-use skills under the h/ namespace. Attach them to any agent by name. List them by filtering on the h/ prefix, or fetch one by name:

# List H-maintained skills
curl "https://agp.eu.hcompany.ai/api/v2/skills?name=h/" -H "Authorization: Bearer $HAI_API_KEY"

# Fetch one by name
curl "https://agp.eu.hcompany.ai/api/v2/skills/h/{skill_name}" -H "Authorization: Bearer $HAI_API_KEY"

from hai_agents import Client

client = Client()

# List H-maintained skills
skills = client.skills.list_skills(name="h/")

# Fetch one by name
skill = client.skills.get_skill("h/{skill_name}")

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

// List H-maintained skills
const skills = await client.skills.listSkills({ name: "h/" });

// Fetch one by name
const skill = await client.skills.getSkill({ name: "h/{skill_name}" });

Endpoints

Method	Path	Description
`POST`	`/api/v2/skills`	Create a skill
`GET`	`/api/v2/skills`	List skills
`GET`	`/api/v2/skills/{name}`	Retrieve a skill
`PUT`	`/api/v2/skills/{name}`	Update a skill
`PATCH`	`/api/v2/skills/{name}`	Patch a skill
`DELETE`	`/api/v2/skills/{name}`	Delete a skill

The list is paginated (page, size) and returns an items / page / total envelope; sort it with sort=created_at or sort=name (prefix - for descending), and filter with name (substring match) or search (matches name or description).

Get started

Concepts

Browser

Desktop

Integrations

Guides

Platform

What’s in a skill

Create custom skills

Create a skill

Attach it to an agent

How an agent uses a skill

Write effective skills

Built-in skills

Endpoints

​What’s in a skill

​Create custom skills

Create a skill

Attach it to an agent

​How an agent uses a skill

​Write effective skills

​Built-in skills

​Endpoints

What’s in a skill

Create custom skills

How an agent uses a skill

Write effective skills

Built-in skills

Endpoints