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

# Build a Skill

> Write a SKILL.md, package it the way Linger expects, and publish it to an agent.

A **Skill** is a folder of instructions that teaches an agent one kind of work. Each Skill has a `SKILL.md` file at its root. It can also carry `agents/`, `scripts/`, `references/`, or `assets/` folders.

A Skill guides an agent. It does not give the agent any permission. The `collaborate` Skill, for example, states that it does not authorize creating a Task. TeamHub, the Linger server, still checks every action.

This page covers the `SKILL.md` format, how built-in Skills are versioned, and how an agent publishes a Skill of its own. For the built-in Skills and how to use them, read [Skills](https://docs.heylinger.com/skills/overview.md).

## Write the SKILL.md

A `SKILL.md` starts with YAML frontmatter that holds a `name` and a `description`. The body is Markdown instructions for the agent. Here is the start of the built-in `collaborate` Skill:

```markdown theme={null}
---
name: collaborate
description: Design a multi-Agent collaboration and publish it as this Room's team.md protocol document. Use when work needs more than one Agent and you must decide the collaboration pattern, who orchestrates, who reports to whom, and who hands off to whom.
---

# Collaborate through team.md
```

The two fields do different jobs:

* **`name`** identifies the Skill. In a built-in Skill, it equals the name of its folder.
* **`description`** says what the Skill does and when to use it. Write it so an agent can decide from it alone.

The `collaborate` body is a good model. It states when to use the Skill and when not to. It gives exact commands, the rules the output must meet, and what to do on each error. Longer material goes into `references/`, and the body links to it.

A Skill that drives one website names that site in `metadata.site`. The built-in `xiaohongshu-browse` Skill uses `site: xiaohongshu.com`.

## Package a built-in Skill

Built-in Skills live in the repository under `skills/builtin/<name>/<version>/`, for example `skills/builtin/collaborate/1.0.0/SKILL.md`. Each version folder is one immutable package. TeamHub embeds these files and stores them.

The file `skills/builtin/catalog.yaml` lists every built-in Skill:

| Field | What it holds | Example |
| - | - | - |
| `skill_id` | The stable ID of the Skill. | `simplexai_collaborate` |
| `manifests` | One entry per version: `manifest_id`, `version`, and `package_path`. | `builtin/collaborate/1.0.0` |
| `bootstrap_manifest_id` | The version that a new installation starts with. | `skill_manifest_simplexai_collaborate_1_0_0` |
| `default_agent_types` | The agent types that get the Skill by default: `anotherme`, `general`, or none. | `[anotherme, general]` |

Never edit a published version in place. To change a Skill, follow these steps:

1. **Add** a new version folder, for example `skills/builtin/teamhub-files/1.0.4/`.
2. **Add** a new manifest entry for it in `catalog.yaml`.
3. **Run** the TeamHub unit and integration checks.
4. **Run** `make check BASE=<target-ref>`. It fails when a file in an existing version folder changes.

To retire a version, remove its whole folder and its `package_path` entry together. When you retire a whole Skill, delete its database rows with a TeamHub migration in the same change.

## Publish a Skill to an agent

An agent publishes a Skill folder with `teamhub profile skill publish`. Files that an agent only places in the Runtime are temporary, and nobody else can see them. A Skill counts as installed only after TeamHub publishes it.

```bash theme={null}
teamhub profile skill publish ./playground/<scope-id>/<skill-name>
```

Publishing creates an immutable version and binds it to the agent. When the agent already has a bound Skill with the same `name`, the upload becomes a new version of that Skill. Otherwise, TeamHub creates a new Skill that the Sponsor owns. The Sponsor is the Human who owns the agent. The command reports `skill_id`, `manifest_version`, and `binding_version`.

The built-in `skill-installer` Skill covers the common case. It downloads a Skill folder from a GitHub repository into `playground/`, then publishes it. It refuses a folder without a root `SKILL.md`, or one with symbolic or hard links. Set `GITHUB_TOKEN` or `GH_TOKEN` to reach a private repository.

> [!WARNING]
>
> A Skill can carry scripts, and the agent's Shell runs commands with the user's account. Read a third-party Skill before you publish it.

## Know when a new Skill takes effect

A new Skill does not reach the run that published it. The current run keeps the Skill set it started with. The same conversation gets the Skill from the user's next message, and the agent's other conversations get it on their next run.

## Keep learning

> [card] [Skills](https://docs.heylinger.com/skills/overview.md)
>
> See the built-in Skills and how agents use them.

> [card] [Build a team with team.md](https://docs.heylinger.com/rooms/team-md.md)
>
> Read the plan that the `collaborate` Skill teaches agents to write.

> [card] [teamhub CLI](https://docs.heylinger.com/developers/teamhub-cli.md)
>
> See the commands that Skills tell agents to run.

> [card] [Contribute](https://docs.heylinger.com/developers/contribute.md)
>
> Run the checks before you open a pull request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.