Publishing skills
Publishing puts a procedure in front of your employees’ 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
Click Add skill and work through three steps.
- Skill details. Drop in a
SKILL.md, or a zip bundle withSKILL.mdat its root. Workforce validates it and shows you what it parsed: the name, the slug it derived, and the description, next to the file you uploaded and its size. Nothing is saved yet, so a validation error here costs you nothing. Edit the display name and description if you want them to differ from the file, keeping the description inside 120 characters. The full file list appears on the skill’s detail drawer once it is saved. - Referenced connectors. The Connectors the frontmatter declared are pre-selected. Add or remove them here without touching the bundle.
- Provisioning. Choose who can retrieve the skill. See Who a skill reaches.
Finish with Publish. The skill goes live at version 1 and your employees’ 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 final 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 theirs.
Saving a draft instead
Choose Save as draft to keep an unpublished skill in the library. A draft is visible to you under the Draft tab 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 only for users who can publish. An author without publishing rights submits for review instead, which parks the skill 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.
The default is Only me whenever your dashboard user is linked to an employee identity, and Entire organization when it is not. That holds for admins too, so nothing goes org-wide by accident: widening the reach is a deliberate click.
An author without publishing rights sees the same three choices worded for their own reach: Only me, Everyone, and Specific groups I’m in.
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 identity provider Groups that back tool access, so a skill lands with the people already grouped for the work. See Groups and access.
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 the author’s alone. It never appears in another employee’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.
Changing reach after publishing
Reach only ever changes through one deliberate action. Uploading a new version never changes it: 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.
To move a published skill between org-wide and specific Groups, re-scope it directly. The access grants are reconciled in one transaction, so the skill stays retrievable throughout and there is no window where agents lose it. Widening a Group-scoped skill to the whole org, and narrowing an org-wide one to two Groups, are both this same change.
Re-scoping requires manage_skills, so an author with manage_own_skills cannot widen the audience of their own skill. Only me is not a re-scope target: personal reach is the author’s choice at creation, not something an admin assigns.
The change lands on the Audit trail as SKILL_EDITED, attributed to whoever made it.
The skill’s detail drawer has no reach control today. Its actions are unpublish, upload a new version, republish, publish a draft, and enable or disable a Merge-provided skill. Unpublishing and republishing preserves reach, and a slug cannot be reused by a second skill, so until a control ships, ask your Merge contact to re-scope a live skill.
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, and the drawer’s Version history badges the one currently live.
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, and the skill moves to the Draft tab where you can bring it back.
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
Two tabs carry skills Merge maintains rather than skills you wrote. Discover holds the examples Merge writes by hand; Auto-generated holds the ones Merge generates. Read both before writing a skill yourself, since the work may already be done.
They are opt-in. Open a skill to see its full SKILL.md and file list, then Enable for organization to make it retrievable by your employees. Nothing in either tab reaches your agents until an admin enables it, so the catalog growing never changes what your agents see.
Disabling one removes it from your employees immediately. Merge maintains the content, so an enabled skill can be updated on Merge’s side; the enablement decision stays yours.
If you want one of these skills with different instructions, publish your own version rather than asking for the Merge 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. An employee 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
Let your employees write skills and keep the publishing decision with an admin in Reviewing submissions.