;
};
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](#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](#how-an-agent-uses-a-skill).
## 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](/computer-use-agents/skills/create).
## Create custom skills
Create a skill once, then reference it by `name` from any agent's `skills` array.
```bash cURL theme={null}
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."
}'
```
```python Python theme={null}
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."
),
)
```
```typescript TypeScript theme={null}
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.",
});
```
Reference it by `name` from the agent's `skills` array when you create the agent:
```bash cURL theme={null}
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"]
}'
```
```python Python theme={null}
client.agents.create_agent(
name="table-scraper",
description="Scrapes structured data from web tables.",
environments=["h/browser"],
skills=["extract-table-data"],
)
```
```typescript TypeScript theme={null}
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 `` section of the system prompt, with the `body` held back:
```xml theme={null}
extract-table-data
Extract structured data from HTML tables into JSON.
```
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](/computer-use-agents/environments/overview) 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`](/computer-use-agents/agents/overview). 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:
```bash cURL theme={null}
# 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"
```
```python Python theme={null}
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}")
```
```typescript TypeScript theme={null}
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](/computer-use-agents/skills/create) |
| `GET` | `/api/v2/skills` | [List skills](/computer-use-agents/skills/list) |
| `GET` | `/api/v2/skills/{name}` | [Retrieve a skill](/computer-use-agents/skills/retrieve) |
| `PUT` | `/api/v2/skills/{name}` | [Update a skill](/computer-use-agents/skills/update) |
| `PATCH` | `/api/v2/skills/{name}` | [Patch a skill](/computer-use-agents/skills/patch) |
| `DELETE` | `/api/v2/skills/{name}` | [Delete a skill](/computer-use-agents/skills/delete) |
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).