How agents load skills

Agents reach skills through the same MCP endpoint they already use for tools. Agent Handler serves two built-in tools for it, list_skills and retrieve_skill, alongside search_tools and request_tool_access on https://ah-api.merge.dev/mcp.

That is the endpoint your employees connect their own AI clients to, so skills reach agents set up through Agent Handler for Employees. The embedded endpoint an agent in your product calls, covered by Building an agent, does not serve these two tools.

There is nothing to install and nothing to sync. A skill published a moment ago is retrievable on the next call, and an agent already connected to the endpoint has both tools without reconnecting.

The retrieval pattern

Skills load in two or three steps, so an agent spends context only on what it needs.

1. list_skills returns the skills available to the caller, as slug, name, description, and referenced connectors. No instruction bodies.
2. retrieve_skill with a slug returns that skill’s full SKILL.md plus the list of files bundled with it.
3. retrieve_skill with a slug and a path returns one bundled file, if the instructions call for it.

Most work stops at step two. Step three is what keeps a long reference document out of every retrieval that does not need it.

list_skills

Lists the skills this caller can use. The set is resolved per user, not per org:

• Skills published to the whole organization
• Skills published to a group the user belongs to
• The user’s own personal skills
• Merge-provided skills your admins have enabled

Two people in the same org can therefore get different results from the same call, which is the point of group and personal reach. See Who a skill reaches.

The keyword filter matches name and description only. Skill bodies are not searched, which is why a skill’s description has to carry the words people use for the task. See Writing a skill.

1
{
2
  "skills": [
3
    {
4
      "slug": "expense-report-review",
5
      "name": "Expense report review",
6
      "description": "Review a submitted expense report against the T&E policy and either approve it or send it back with the line items that need receipts.",
7
      "referenced_connectors": ["expensify", "slack"]
8
    }
9
  ]
10
}

Unpublished skills, drafts, submissions awaiting review, catalog skills your org has not enabled, and skills scoped to a group or a person the caller is not do not appear.

retrieve_skill resolves against the same set, so a slug the caller cannot reach returns not found rather than a permission error. A guessed slug tells an agent nothing about what exists.

retrieve_skill

Returns a skill’s instructions, or one of its bundled files.

Called with a slug alone, you get the instructions and the manifest:

1
{
2
  "skill": {
3
    "slug": "expense-report-review",
4
    "name": "Expense report review",
5
    "version": 3,
6
    "skill_md": "# Expense report review\n\n## Steps\n\n1. Pull the report with `expensify__get_report`...",
7
    "manifest": ["SKILL.md", "references/te-policy.md", "examples/rejection-message.md"],
8
    "referenced_connectors": ["expensify", "slack"]
9
  }
10
}

version is the published version number the agent read, which is worth logging on your side: it makes “which instructions produced this run” answerable later.

Called with a path from that manifest, you get the one file:

1
{
2
  "skill": {
3
    "slug": "expense-report-review",
4
    "version": 3,
5
    "path": "references/te-policy.md",
6
    "encoding": "utf-8",
7
    "content": "# Travel and expense policy\n\nMeals are reimbursable up to $75 per day..."
8
  }
9
}

Text files come back as UTF-8 in content. Binary files come back base64-encoded, with encoding saying which, so the caller knows how to decode.

A path that is not in the skill’s manifest returns not found. Agents cannot read outside a skill’s bundle, and cannot reach another skill’s files through a path.

What agents get, and what they do not

retrieve_skill always serves the currently published version. Drafts and in-review revisions are invisible to agents, so an author working on a revision never affects a running agent. If a skill is unpublished mid-flight, the next retrieval returns not found rather than stale content.

A skill grants nothing. Instructions that name a tool the caller cannot use still fail at the tool layer, with the same error a direct request would produce. If a skill consistently fails for a group of users, the fix is in their Tool Pack or connector access, not in the skill. Managing tool access covers that side.

Retrieval is audited

Every retrieve_skill call writes a SKILL_RETRIEVED event to the Audit Trail, attributed to the user whose agent made the call. Read next to Tool Call Logs, that gives you the sequence: which skill an agent loaded, and which calls it made afterward.

Each skill also carries a retrieval count in the dashboard, which is the fastest way to see which skills your org actually uses and which ones nobody has ever loaded. It counts skill loads, not bundled-file fetches, so an agent reading three reference files is one retrieval.

Next: Skills