Skills

Skills are workflows and expertise your agents apply on their own — a code review checklist, a report format, the way your team qualifies deals. Instructions in a skill are injected into the agent’s context when the skill is active, so the know-how travels with the work.

Without skills, that expertise lives in fragile places: someone’s head, or the instructions of one particular assignment. Every new prompt restates the house rules, and every restatement drifts a little. A skill writes the know-how down once and applies it wherever the agent works — a chat session, a scheduled report, a webhook-triggered run. When the process changes, you edit the skill and every agent that carries it changes with it.

Skills are procedure; the knowledge base is reference. If it’s “how we do this,” write a skill. If it’s “what is true” — product specs, policies, past decisions — it belongs in knowledge, where agents consult it while working.

Creating a skill

From Skills & integrations → Skills, choose New skill and then Write skill instructions, Upload a skill (.tgz / .zip), or Import from URL (see Importing a skill). A skill has three parts:

A Name — what the skill is called wherever it appears.
A Description — “a short description that helps agents decide when to apply this skill.” This line does real work: the agent reads it when choosing whether the skill is relevant to the task at hand.
Instructions in markdown — the know-how itself. The AI assist button can generate or enhance the instructions from a description of what you want.

A concrete example — a skill a sales workspace might keep:

Name: Deal qualification

Description: Apply when researching, scoring, or writing up a sales prospect or opportunity.

Instructions: Qualify every prospect against four criteria, in order: budget signal, access to the decision maker, timeline, and fit with our ideal customer profile (see icp.md). Score each from 1 to 3 and total them. A total under 8 is a nurture, not a pursue — say which one explicitly. Write the summary using templates/qualification.md, and end with a single recommended next action.

Beyond the main instructions, a skill can carry supporting files and folders — templates, examples, reference data — all editable in place, all with revision history and restore. The example above leans on two of them: the icp.md the criteria refer to, and the template the write-up follows. Keeping those files inside the skill means the procedure and its materials version together; restoring an old revision restores both.

To update a skill from a new archive, open it and choose Replace from archive in its menu. Every file is replaced by the archive’s files, files the archive leaves out are deleted, and the agents and assignments that use the skill keep it. Uploading an archive whose SKILL.md names a skill you can already edit asks whether to replace that skill or create a new one.

When a skill applies

Each skill has an activation mode, set by the activation_mode line in its SKILL.md frontmatter:

Auto (the default) — the skill is listed in the agent’s catalog by its description, and the agent activates it when the task matches.
Always on — the full instructions are in every session that includes the skill.
Manual — hidden from the agent’s catalog; the skill runs only when someone picks it, for example by typing / in the chat box and choosing it.

Most skills should stay Auto. Reserve Always on for rules that hold on every task, since its instructions take up context whether or not the work needs them.

Importing a skill

Import from URL brings in a skill someone else published, from a public GitHub repository or skills.sh. Paste the skill’s URL, or pin an exact commit with owner/repository/path#<commit>. Point it at a repository root or a folder of several skills and you get a list to pick from, up to 25 at a time.

Every import is reviewed before anything is added. The review shows the skill’s files, the commit it is pinned to, and what the scan found:

Can’t import — commands with no legitimate place in a skill, such as a decoded payload that gets executed or a credential file sent to another host. These are never importable, wherever they appear in the skill’s files.
Needs acknowledgement — things that are often fine but worth a look, like sudo or an installer piped to a shell. You acknowledge each skill’s warnings before it imports. Executable scripts, package manifests, MCP configuration, and archives are flagged here too, because the agent can read them and may run them.
Audit results from skills.sh, when the skill is listed there.

Imported skills start inactive: add one to an agent to use it. Importing from an agent’s page turns the skill on for that agent in the same step. Every import also arrives as Manual, whatever its frontmatter asks for; the review shows the mode the source requested, and you change the activation_mode line once you have read the skill. Every file in the reviewed skill is imported with it. Importing gives the agent no new tools or permissions: it reads the skill’s files with the tools it already has.

An imported skill’s page shows its source, pinned commit, and content hash under Reviewed import. Check for update compares it against the latest commit on the branch it tracks, or a ref you type, and opens the same review with a per-file diff. Approving it adds a new revision of the same skill and keeps its activation mode; nothing updates without that review.

Admins decide who may accept warnings, under Guardrails → Skill import in workspace or organization settings: Anyone who can import (the default), Admins only, or No one — warnings block import. A workspace can tighten the organization’s choice but not loosen it.

The same section holds Skill changes made with an API key need approval in the app, off by default. Turned on, requests made with an API key or over MCP can still preview and read skills, but every change is refused: importing or approving an update, one at a time or in bulk; creating, editing, moving, archiving, or deleting a skill or its files and folders; restoring an earlier revision; turning a skill on or off; and saving an agent, assignment, or session with a different skill list. Nothing is queued. The refusal carries a link to the Skills tab of Skills & integrations, opened on the skill when there is one, where someone signed in to the app makes the change themselves. Like the warnings setting, once the organization turns it on, a workspace can’t turn it off.

Scopes

Skills live at three scopes, shown as a chip on every row wherever skills appear. The Skills tab of Skills & integrations lists all three together, and its Scope filter narrows to one:

Agent — owned by one agent, managed on that agent’s Abilities card; the library lists it as Agent: name and links there.
Workspace — shared with everyone in the workspace, managed in Skills & integrations.
Organization — inherited by every workspace in the organization; everyone in the organization sees it in Skills & integrations, and org admins manage it there.

Scope tracks how widely the know-how is true. A procedure only one agent needs — the exact format of this agent’s Monday report — is an agent skill. Team conventions — how the support team triages, how the sales team qualifies — are workspace skills. Company-wide standards — the house writing style, the brand voice — are org skills, so every workspace inherits them without anyone re-creating them.

To move a skill, open its menu and choose Change scope…. An agent’s own skill can move to the workspace, by someone who can edit the agent. A workspace skill can move to the organization, by an org admin; an agent skill gets there by way of the workspace. A move keeps the skill’s id, so agents already using it keep it, and there is no moving it back. A skill can also start at the organization: pick Organization under Scope when creating it. Moving later is the natural path for a skill that proves out as one team’s convention before the whole organization gets it.

Skills on an agent

The agent’s Abilities card lists the skills it uses, from any scope, plus its own skills whether it uses them or not, each with its scope chip. Add holds everything you can give it: the shared skills it does not use yet come first, then Import a skill… and Create a skill…, which make an agent-private skill and turn it on in the same step. A row’s menu offers Use on an own skill marked Not in use; Change scope…, Archive skill and Delete permanently on an own skill, as the library does; and Remove from agent on any skill it uses. Archived own skills are behind the Archived filter, each restored or deleted from its row. Skills the agent inherits are marked Always on. Unless a shared skill is manual, the agent may also pick it up on demand mid-task without it being added here.

Two related controls live elsewhere. An assignment’s Options can pin skills the agent should always use for that job — by default the agent decides — see Assignments. And whether an agent may write skills of its own is part of the self-improvement guardrail: an agent allowed to do so can capture what it learns as a skill, which you can then review like any other.

Editing a shared skill updates every agent that uses it, starting on their next run — a run already in progress keeps the instructions it started with. Version history lets you restore an earlier revision, which applies the same way, on the next run. An agent only picks up a change mid-run if it activates that skill itself during the run.

Patterns that work

Format skill — the shape of a deliverable: what sections a weekly report has, how a customer brief is structured, what a good release note looks like. Carry the template as a supporting file.
Process skill — steps in a fixed order: deal qualification, incident triage, candidate screening. The instructions say what to check, in what order, and what the decision rule is.
Checklist skill — a rubric applied to work before it ships: a code review checklist, a QA pass, a pre-publish review. Useful as an org skill when the bar should be the same everywhere.
Voice skill — how the company writes: tone, terminology, things never to say. One org-wide skill beats a style note pasted into every prompt.