Skip to main content
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.

​
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:
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: 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.
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.
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

Skills

See the built-in Skills and how agents use them.

Build a team with team.md

Read the plan that the collaborate Skill teaches agents to write.

teamhub CLI

See the commands that Skills tell agents to run.

Contribute

Run the checks before you open a pull request.