Skills

A skill is a package of instructions an agent reads while it works: a SKILL.md file plus any files that go with it. Skills are versioned, and they are their own kind of marketplace item. A skill is no longer the same thing as an agent card. A card, or a stage card, refers to the skills it uses.

The marketplace tabsCopy Anchor Link

Open the Marketplace. At the organization level it has three sections: Agents, Skills and Models (see Model Access). Inside a project the Marketplace also lists Workflows.

AgentsCopy Anchor Link

The Agents section is where you find and install agent cards. It has a tab per catalogue: Built-in, Organization, LangChain Hub, MCP Catalogs, Vendor-hosted and Git-hosted. Inside a project there is also an Installed list for that project's own cards. Installing puts a card in your org or project. You then place it on a stage in Settings, under Stages. See Stage Cards.

The old agents list in project settings now redirects to Agents, then Installed.

SkillsCopy Anchor Link

The Skills section lists the skills your org can see: built-in skills the platform ships, and skills your org imported.

• Search by name or description, filter by source (Built-in or This organization) and by whether a skill is installed.
• Open a skill to see its source, its versions and its files, and its SKILL.md as plain text. Imported skills are external content and are shown with where they came from.
• Import pulls a skill from the Tessl registry into your org's catalogue. Only organization admins can import, and an API key cannot. In 1.0 imports are skills made of a SKILL.md and its files. Importing the same content twice creates one version.

Install versus attach to every runCopy Anchor Link

These are two separate steps, and installing alone does not put a skill in any run.

A skill that is installed but not attached is used when a card or stage card names it. A skill that is attached rides along with every run in the org or project, whichever card runs.

The Attach to every run switch is on the skill's row and in its preview. Each install pins a version, the current one by default, and the pin can be changed later.

Attach levels and merge orderCopy Anchor Link

Skills can be attached at four levels, and the run merges them in this order:

A later level replaces an earlier one that has the same skill name (the name in its SKILL.md), so the most specific copy wins. A stage card or a card can add skills and replace an attached one, but cannot remove an attached skill in 1.0.

Details of the merge:

• Versions. A reference uses its own version if it names one, else the project's pin, else the org's pin, else the skill's current version.
• Visibility. A level can only use skills it can see. A built-in skill is visible everywhere; an org's skill is visible only to that org.
• Disallowed tools. Each skill can disallow tools. For a run, the lists of every delivered skill are combined and applied on top of the run's existing limits. They only ever narrow what the agent may use.
• Limits. A run carries at most 32 skills, 256 KiB of files per skill and 1 MiB of files in total, and at most 32 KiB of SKILL.md text per skill and 64 KiB in total. Skills are admitted most specific first, so a skill that does not fit is dropped whole, starting from the least specific level. A skill is never cut short.
• Nothing drops silently. The dispatch receipt lists every skill that did not reach the run, with its level and a reason: not_visible, version_missing, descriptor_only, size_cap or content_integrity. If the skills could not be read at all, the run still goes ahead and the receipt says so.

Add skills to a stage cardCopy Anchor Link

In Settings, then Stages, open a stage and edit its cards. Each card has a Skills list. Pick from the skills your org can see (up to 32 per stage card). A list set at a higher scope is shown as inherited; changing it saves the full list at your scope.

The repo-skill policyCopy Anchor Link

Your repository may already contain skills, for example under .claude/skills, .agents/skills or .pi/skills. The repo-skill policy decides whether the harness may use them:

Set the project default in the project's Settings, under Stages, as Project repo-skill policy, and override it for a single card in a stage under Repo skills for that card. The card's setting wins, then the project's, then all. The policy travels with the run only when it is not all.

How skills reach the harnessCopy Anchor Link

At dispatch the platform resolves each skill to its content and sends it with the run: the skill's files, with a digest for each, and the SKILL.md text as a fallback. The runner on your host then places the skill where the harness can use it:

• Where the runner supports native delivery for a harness, the skill is materialized for that harness in its own skill format.
• Otherwise, and for older runners, the SKILL.md text is appended to the agent's system prompt.

Which harnesses get native delivery is a property of the runner, not of the platform, and it is documented with the runner. See the layered execution model on donmai.dev.

APICopy Anchor Link

Related pagesCopy Anchor Link

• Stage Cards
• Agent Cards
• Stages and Roles