> This page is for Workforce.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Skills

> What a skill is in Workforce, what the Skills section holds, how a published skill reaches the AI clients your employees use, and how skills relate to tools and Connectors.

A skill is one of your company's procedures, written down once and published so employee agents follow it: how you close the books, how you triage a security review, how you write up a customer call. It is a plain `SKILL.md` file, plus any reference files it needs, in the open SKILL.md format.

Publish a skill once and every AI client your employees already use reads it from the same place: Claude, ChatGPT, Cursor, Claude Code, and anything else pointed at your MCP endpoint. Use it when the same task run by ten people through AI produces ten different results and you want one approved way to do the work.

If Tool Packs answer "what can this agent call," skills answer "how should it do the work."

Skills live at [wf-develop.merge.dev/skills-library](https://wf-develop.merge.dev/skills-library). Your employees can write them too, and an admin decides whether a submission reaches the library.

> **Availability**
>
> Skill retrieval over MCP is enabled per organization and is off until Merge turns it on. Until then `list_skills` and `retrieve_skill` are not served on your MCP endpoint, so a skill you publish in the dashboard does not reach your employees' AI clients. Ask your Merge contact to switch it on for your org.

## What a skill is made of

Every skill is a bundle with a `SKILL.md` at its root. That file carries YAML frontmatter (a `name` and a `description`) and a Markdown body holding the actual instructions.

A skill can also bundle supporting files: longer reference material, example payloads, a checklist an agent only needs for one branch of the work. Agents load `SKILL.md` first and pull a bundled file only when the instructions send them to it, so the entry point stays small and the detail stays available. See [Writing a skill](/merge-workforce/skills/writing-a-skill) for the format and limits.

## What the Skills section holds

Five tabs, all reading the same library from a different angle.

| Tab                | What it holds                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| **Published**      | What your organization can use right now: the skills you published, plus the Merge-provided ones an admin enabled            |
| **Draft**          | Unpublished skills, including ones you took down. Admins only, since employees submit for review rather than staging drafts. |
| **Review**         | Submissions waiting on an admin decision, and rejected ones                                                                  |
| **Auto-generated** | Skills Merge generates, each on or off for your org                                                                          |
| **Discover**       | Example skills Merge writes and maintains, each on or off for your org                                                       |

**Published** is where you land. Every card carries the skill's name, its description, who it came from (an author's name, **Example**, or **Auto-generated**), who it reaches, and the Connectors its frontmatter declared. The toggle on a card publishes or unpublishes one of your own skills, and enables or disables a Merge-provided one.

## How skills relate to tools and Connectors

A skill is advisory. It tells an agent what to do and in what order; it grants nothing.

Workforce executes the tool calls, and every call is still checked against the employee's own permissions and the Tool Pack in play. A skill that says "update the closed-won opportunity in Salesforce" fails for an employee with read-only Salesforce access, exactly as a direct request would. Skills cannot widen access, so publishing one is not a permission decision.

| Layer                     | Question it answers         | Enforcement                |
| ------------------------- | --------------------------- | -------------------------- |
| Employees and Groups      | Who is acting               | Identity                   |
| Connectors and Tool Packs | What they can call          | Enforced at the tool layer |
| Skills                    | How the work should be done | Advisory                   |

Reach is the one thing a skill does control: who can read it. A skill is published to the whole organization, to specific Groups from your identity provider, or to its author alone, and `list_skills` is filtered per employee accordingly. That decides who sees the instructions, never what they are allowed to call. See [Who a skill reaches](/merge-workforce/skills/publishing-skills#who-a-skill-reaches).

A skill's frontmatter can name the Connectors it expects (`referenced_connectors`), which is how the dashboard shows the Connectors a skill leans on. That list is a declaration for humans reading the card, not a grant and not a precondition.

## Where your library comes from

Nobody maintains one list. An employee's library is the set of skills that reach them, assembled from three places, and the dashboard labels each skill with its origin.

* **Skills they authored**, whether published to themselves or written for the org
* **Skills you published**, organization-wide or to a Group they belong to
* **Skills you enabled from Discover or Auto-generated**, written or generated by Merge

Nothing Merge maintains reaches your employees until an admin enables it, so a growing catalog never quietly expands what your agents read.

Two employees in the same org can therefore have different libraries, because Group-scoped and personal skills reach different people.

## How a published skill reaches an employee

Over MCP. The employee's AI client calls `list_skills` and `retrieve_skill` on the endpoint it already uses for tools. There is nothing to install and nothing to sync: a skill published a moment ago is retrievable on the next call, and the client's results are filtered to that employee's Group access. See [How agents load skills](/merge-workforce/skills/how-agents-load-skills).

That is the one path. The [Workforce desktop client](/merge-workforce/devices/overview) does not copy skills onto the machine; what it writes is the MCP configuration that points a client at the endpoint, so retrieval works without the employee setting anything up.

## What gets recorded

Publishing, drafting, submitting, approving, rejecting, unpublishing, republishing, re-scoping, enabling a Merge-provided skill, disabling one, and every agent retrieval each land as an event attributed to the employee who caused it. So "which skill did this agent read before it made that call" is answerable after the fact, on the [Audit trail](/merge-workforce/logs/audit-trail).

## Next steps

#### [Writing a skill](/merge-workforce/skills/writing-a-skill)

The SKILL.md format, the limits, and how to write a description agents match

#### [Publishing skills](/merge-workforce/skills/publishing-skills)

Upload a skill, choose who it reaches, version it, and turn on the ones Merge provides

#### [Reviewing submissions](/merge-workforce/skills/reviewing-submissions)

Let employees write skills and keep publishing an admin decision

#### [How agents load skills](/merge-workforce/skills/how-agents-load-skills)

The two MCP tools an employee's AI client uses to find a skill and read it