Publishing skills

Publishing puts a skill in front of your organization’s agents. It takes one upload, and it is reversible: a published skill can be unpublished without losing its history, and a new version can be published without disturbing the old one until it is ready.

Publishing happens on the Skills page in the dashboard. Skills are not part of the public API surface.

Publishing a skill

1. Go to Skills and click Add skill.
2. Upload a SKILL.md, or a zip bundle with SKILL.md at its root.
3. Agent Handler validates the bundle and shows you what it parsed: the name, the slug it derived, the description, the file list with sizes, and the connectors the frontmatter declared. Nothing is saved yet, so a validation error here costs you nothing.
4. Adjust what you want to differ from the file. You can edit the display name, the description, and the connector list without touching the bundle.
5. Choose who can retrieve the skill. See Who a skill reaches.
6. Publish.

The skill goes live at version 1 and your agents can retrieve it on their next call. No token rotation, no re-authentication.

If validation fails, the error names the specific problem. Writing a skill lists each error and its fix.

If you do not have publishing rights, the primary button reads Submit for review instead, and the skill goes to an admin. That flow is Reviewing submissions. The one exception is a skill scoped to yourself, which you publish directly.

Slugs

The slug is the skill’s stable identifier, and it is what agents pass to retrieve_skill.

It is derived from the skill’s name and follows it: edit the name in the upload dialog and the slug updates with it. The slug field itself is read-only, so the way to get the slug you want is to name the skill accordingly.

Name the skill deliberately for that reason, because the slug it produces is what your agents and your own documentation will use. The merge- prefix is reserved for skills Merge manages, so your slugs can never collide with the catalog.

Saving a draft instead

Choose Save as draft to keep an unpublished skill in the library. A draft is visible to you in the dashboard and invisible to agents. Publish it later from the skill’s detail drawer, with no re-upload.

Drafts are useful when a skill needs a connector you have not finished setting up, or when you want a reviewer to read it before agents can.

Save as draft appears for users who can publish. An author without publishing rights submits for review instead, which parks the skill just as safely and puts it in front of an admin.

Who a skill reaches

The upload asks who can retrieve the skill. It is the same decision whether you publish directly or submit for review, and it is what filters an agent’s list_skills results.

An author without publishing rights sees the same three choices worded for their own reach: Only me, Everyone, and Specific groups I’m in. They land on Only me by default, so a personal skill is the path of least resistance and nothing goes org-wide by accident.

Each skill’s detail drawer shows the result on a Visibility row: the owner’s name for a personal skill, the group names for a group-scoped one, and “Organization” for an org-wide one.

Group reach

Group reach uses the same IdP groups that back tool access, so a skill lands with the people already grouped for the work. See Companies and Groups.

An admin with manage_skills can target any group in the org. An author with manage_own_skills can target only groups they belong to, and picking one they are not in is rejected rather than silently published wider. At least one group is required.

The group option appears only once your org has groups to pick from. Without SCIM there are none, so the choice is org-wide or personal.

Personal skills

A personal skill is yours alone. It never appears in another member’s list_skills, and nobody else can open it in the dashboard, including admins. That last part is deliberate: the Visibility row names the owner, and slugs are guessable.

Personal skills also skip review. Publishing one is not an org-wide decision, so an author with manage_own_skills publishes it directly and publishes later versions directly too. A personal skill cannot be submitted for review at all, which is what stops one being promoted org-wide by an approval.

Reach is set when the skill is created

Uploading a new version never changes who a skill reaches. Sending a different reach along with a version is rejected rather than quietly ignored, so a resubmission cannot silently re-scope a live skill.

Unpublishing and republishing preserves reach for the same reason. A personal or group-scoped skill never comes back org-wide.

Versions

Every upload creates an immutable version. Publishing a new one repoints the skill at it; the previous version stays in the history with its number, its uploader, and its timestamp.

Open a skill and use Upload new version to publish a revision. Version numbers are assigned on publish and stay contiguous, so v3 is always the third published version, and drafts and rejected submissions never consume a number.

The version an agent receives is always the currently published one. That has a useful consequence: a revision filed for review over a live skill does not take the live skill down. Agents keep reading the published version until the revision is approved. See Reviewing submissions.

Unpublishing and republishing

Unpublishing hides a skill from agents. It does not delete it: versions, files, and history all stay.

Reach for unpublish when a skill is wrong and you need it gone now. Fixing it and publishing a new version is the better move when the skill is merely out of date, because agents keep working from the old version in the meantime.

Skills Merge provides

Alongside the skills you author, Browse carries a catalog of skills Merge maintains: ones written by hand, and ones Merge generates. Reach for it before writing a skill yourself, since the work may already be done.

Catalog skills are opt-in. Read through Browse, open a skill to see its full SKILL.md and file list, and enable it to make it available to your members. Nothing in the catalog reaches your agents until an admin enables it, so the catalog growing never changes what your agents see.

Disabling a catalog skill removes it from your members immediately. Merge maintains the content of these skills, so an enabled catalog skill can be updated on Merge’s side; the enablement decision stays yours.

If you want a catalog skill with different instructions, publish your own version rather than asking for the catalog one to change. Your org’s skill is fully yours to version.

Who can publish what

Skills use four role permissions. Assign them on Team and roles.

Publishing to the whole org or to a group requires manage_skills. A user with manage_own_skills publishes personal skills directly to themselves, and submits anything wider for approval, which is the flow described in Reviewing submissions.

What gets audited

Each of these lands on the Audit Trail, attributed to the user who did it.

Submission and review events are listed in Reviewing submissions. Agent retrievals are covered in How agents load skills.

Next: Reviewing submissions