Skills

Load and use skills to give your agents the context they need to use MCP tools effectively

The Skills tab is always accessible. Cloud (hosted) skills — the project store, upload button, and skill tree — are available on accounts where the feature has been enabled. Skills over MCP (server-provided skills from connected servers) require no account feature and are always shown. Local skills, read from your filesystem, also need no account feature.

Skills are an open format that provide instructions on how to use MCP tools and complete workflows. MCPJam lets you discover skills from your filesystem (local) or your project (hosted), upload new ones, and use them in the Playground — either automatically based on the user’s prompt or deterministically with the / command.

Getting Started

1. Open the Connect view in MCPJam Inspector and select the Skills tab (Servers | Client | Computer | Skills)
2. Load skills — MCPJam automatically discovers skills from supported directories. You can also upload skills directly through the Skills tab, or run npx skills to install them
3. Use skills in the Playground — the LLM discovers them automatically, or you can inject them with the / command

Skill Directories

MCPJam scans the following directories for skills. Each subdirectory is expected to contain a SKILL.md file. When duplicate skill names are found, the first match in search order wins.

Global:

~/.claude/skills/
~/.mcpjam/skills/
~/.agents/skills/

Project-local:

./.claude/skills/
./.mcpjam/skills/
./.agents/skills/

If you have no skills installed, run npx skills to get started quickly.

Finding skill IDs

Several CLI flags take a skill ID: eval run --compose-skill, eval cases run --compose-skill, and environments ensure-adhoc --skill. Use mcpjam cloud skills list to discover the IDs of the project-shared skills in your project:

mcpjam cloud skills list --project my-project

Each row includes a pinnability field that says whether the skill can be pinned into an environment or eval run, and why not if it can’t. To see a skill’s full SKILL.md body:

mcpjam cloud skills get --skill <id> --project my-project

Only sharing: "project" skills can be pinned. Personal drafts (sharing: "user") are visible in the list but are not accepted by --compose-skill or skillSelection.

Uploading Skills

You can upload skill folders directly from the Skills tab in the Connect view. The upload dialog supports drag-and-drop or file browsing and validates the SKILL.md frontmatter in real time.

• Local: Uploaded skills are stored in ~/.mcpjam/skills/.
• Hosted (cloud): Cloud skills carry supporting files. A folder may contain SKILL.md plus scripts, references, and assets; the model reaches them with listSkillFiles and readSkillFile after loading the skill.

Hosted skill folders are bounded by three limits, enforced when the files are attached:

Limit	Value
Per file	2 MB
Files per skill	50
Total per skill	20 MB

Uploading a skill with a name that already exists will be rejected. Delete the existing skill first if you need to replace it.

Updating Skills

To pull the latest version of the mcp-inspector skill — which contains MCPJam’s guidance for interpreting probe, doctor, OAuth, and conformance output — run:

npx skills update mcp-inspector

To update every installed skill at once:

npx skills update

Where a turn’s skills come from

A chat turn builds one catalog from every origin available to it, rather than picking a single source:

Origin	Reference	Available on
Your project (Cloud Skills)	code-review	anywhere you’re signed in with a project
A local file	local/code-review	the desktop and npm app
A connected MCP server	<server>/code-review	anywhere that server is connected
A plugin	<plugin>/code-review	wherever the plugin is installed

This is why the Skills tab’s Local/Cloud switch only changes what you are browsing. It no longer decides what the model can use: a desktop turn signed into a project offers your local files and your project skills, so a skill you author in the tab is usable in the very next message.

Signed out, or with no project selected, a desktop turn simply has no project family — it offers local files, exactly as before.

Two skills with the same name

Local and project skills are namespaced apart on purpose, so nothing is hidden and nothing is silently preferred. If you have a local code-review and a project code-review, both appear and both load:

loadSkill("local/code-review")  → your file
loadSkill("code-review")        → the project's

An exact reference always wins. code-review is the project skill’s reference, so asking for it is not ambiguous — it is a direct hit, and the local skill stays reachable under its own name. That is what keeps a project skill addressable no matter what you happen to have on disk.

Ambiguity is the case where nothing is an exact hit: two namespaced skills share a name and no skill answers to the bare name itself — a plugin docs-tools/code-review alongside a local local/code-review, with no project code-review. There the tool refuses and names the alternatives rather than guessing:

"code-review" is ambiguous — it matches "docs-tools/code-review" and
"local/code-review". Use the full reference.

Skills an agent writes for itself

Harness runs (Claude Code, Codex) execute in a sandbox with a real filesystem, so the agent can write a skill mid-run the same way it would on your machine. After a clean turn, MCPJam adopts any skill it finds in the sandbox’s skills directory into your project — otherwise the work would vanish with the sandbox.

Adopted skills are personal: visible to you, not to the rest of the project, until you promote one. They are marked with a computer-adopted provenance, so you can tell them from skills you authored.

Adoption is deliberately narrow. It does not run when:

• the run used pinned skills — a pinned set is a frozen snapshot, and writing back into the pool would change what the next eval arm resolves against, silently altering the thing under comparison;
• the turn failed, was aborted, or is paused waiting for approval;
• the run carries an execution scope (guest and swarm runs never adopt);
• the live skills fetch failed, so MCPJam cannot tell an agent-authored skill from one it simply failed to see as already managed.

Set HARNESS_SKILL_ADOPTION_DISABLED=1 to turn adoption off entirely for a deployment.

Using Skills

Progressive Disclosure

When you have skills available, MCPJam inlines the skill catalog — each skill’s name and a one-line description — directly into the LLM’s system prompt. The LLM decides which skills are relevant to your prompt and calls loadSkill to load only the full instructions it needs. Once a skill is loaded, the LLM can also browse and read its supporting files using listSkillFiles and readSkillFile.

The catalog is not a tool call. There is no general listSkills tool — a turn with no skills gets no skill tools and no catalog section at all, so an empty project never spends a discovery turn on tools that would return nothing.

Catalog Size Limit

The catalog is capped at 2% of the model’s context window (MCPJam follows OpenAI’s plugin guidance here, measured in characters at roughly 4 characters per token). When a model definition carries no context length, the cap falls back to 8,000 characters.

If your skills do not fit, MCPJam shortens descriptions first, and only omits whole skills as a last resort. An omission is always reported in the catalog itself:

(3 more skills could not be listed within this model's skill-metadata budget.)

An omitted skill is invisible to the model and cannot be loaded, so keep skill descriptions to a single line if you have many skills installed.

Catalog Fetch Failures (Hosted)

In the hosted app, the catalog is fetched from your project when the prompt is built, with a 3 second timeout. If that fetch fails or times out, the turn proceeds with no skills rather than failing — the LLM sees no catalog and no skill tools. MCPJam records the failure separately from a genuinely empty project, so a run that silently lost its skills is distinguishable after the fact.

Deterministic Injection

Type / in the input to open the skills popover. Select a skill to inject it directly into the conversation — this pre-loads the SKILL.md content before the LLM processes your message, so the skill is guaranteed to be used.

When you select a skill via /, it appears as a card above the input. You can expand the card to browse the skill’s file tree and optionally select additional files to include. Only files you explicitly select are pre-loaded — by default, only the SKILL.md is injected.

The / picker works in both local and hosted modes. In the hosted app, it lists your project’s cloud skills.

LLM Tool Integration

When at least one skill is available, the LLM is given loadSkill, and — on surfaces that can serve supporting files — the two file tools as well:

Tool	Description	When advertised
loadSkill(name)	Load the full skill instructions by name	Whenever the turn has at least one skill
listSkillFiles(name)	List all files in the skill directory	Only when the turn’s skills can carry supporting files
readSkillFile(name, path)	Read the content of a specific supporting file	Only when the turn’s skills can carry supporting files

The file tools are not advertised everywhere, because promising them for skills that have no files invites the model to go looking:

• Local and hosted Playground chat — all three tools.
• Eval runs with pinned skills — loadSkill only. Pinned eval skills are SKILL.md-only, so there are no files to browse.
• Environment-resolved turns — all three, but only when the resolved set actually contains a file-bearing skill.

Together with the inlined catalog, these tools let the LLM progressively load skill content as needed during a conversation, rather than injecting every skill’s content upfront.

listSkills is not a general discovery tool. It appears only when a connected MCP server provides skills through the Skills over MCP extension (SEP-2640), and it lists those server-provided skills only. Use it to re-read the catalog mid-conversation; the catalog is already inlined in the system prompt at the start of each turn.

Skills over MCP (Server-Provided Skills)

When a connected MCP server advertises the SEP-2640 skills extension, MCPJam discovers its skills automatically and inlines them in the system prompt catalog alongside local and hosted skills — each entry attributed to its originating server (MCP server "…"). The model can choose a relevant skill from the catalog and load it with loadSkill, exactly as it would for any other skill origin.

Every server skill is verified before it is loaded: MCPJam fetches each file listed in the skill’s manifest and checks its digest (and byte length, when the server provides one) before any content reaches the model.

Each server skill row shows the origin server’s label as a badge directly on the row, so provenance is visible wherever the skill appears in the list. A server that has not mutually declared the extension contributes no rows — “this host and server never had a skills conversation” is a different fact from “this server has no skills”.

The tab’s single refresh button reloads both the project skill store and all server skill catalogs at once. It remains visible even when the project store is hidden, since server skills are the only list in that case.

Inspecting a server’s skills from the CLI

mcpjam skills asks a server what it serves and verifies the answer. It connects directly, so it needs no MCPJam project and no API key:

mcpjam skills list --url https://example.com/mcp
mcpjam skills get --url https://example.com/mcp --uri "skill://acme/refunds/SKILL.md"
mcpjam skills read --url https://example.com/mcp \
  --skill-uri "skill://acme/refunds/SKILL.md" \
  --resource-uri "skill://acme/refunds/scripts/run.py"

mcpjam resources list will also show skill:// URIs, because they are resources — but it shows them as bytes with no manifest, no digest check, and no reason when something is wrong. These commands run the same verified read path the Playground uses, so what you get back is either verified content or a refusal naming the check that failed (see the table below). A refusal is a result, not an error: it prints to stdout and exits 0, because “this skill cannot be verified, and here is why” is the answer you asked for.

mcpjam skills reads a connected server’s skills. mcpjam cloud skills lists the Cloud Skills in your own MCPJam project. Same word, opposite direction.

The skills extension is mutually declared, so these commands advertise it on connect. If you pin a host persona that does not — --host cursor, say — the command refuses rather than quietly advertising anyway, since the answer to “what would Cursor see here?” is nothing:

$ mcpjam skills list --url https://example.com/mcp --host cursor
`skills` requires the advertised client capabilities to include the
`io.modelcontextprotocol/skills` extension ... That host would not see this
server's skills at all.

Agents driving MCPJam reach the same three operations as list_server_skills, get_server_skill and read_server_skill_file — over /api/v1, the hosted MCP server, and the in-app assistant.

Checking that your own server serves skills correctly

mcpjam server doctor includes a skills check. Unlike the tool, resource and prompt checks it verifies rather than counts, fetching a sample of skills and checking each against its manifest:

- skills: ok (4 skills discovered. 4 verified against their manifests.)
- skills: error (1 of 2 sampled skills failed verification:
  skill://demo/tampered/SKILL.md (digest_mismatch).)

It reports skipped when the extension is not active on the connection, which is the normal state for a server that serves no skills.

Unloadable skills

A server skill can appear in the catalog but be refused for loading. MCPJam keeps the skill visible in the catalog — marked unverifiable — so the model stops retrying it and you can see what the server advertised. MCPJam declines to inject unverifiable content into a model turn. The reason is always shown:

Reason	What it means
no_resources	The server omitted the resources manifest the spec requires. MCPJam cannot verify the skill’s contents without one.
dynamic_resources	The server declared "resources": "dynamic" — a form the spec defines for skills generated per request. There is no manifest to verify against, so MCPJam declines to load it.
too_many_resources	The skill’s manifest lists more than 512 files, which is the per-skill limit the spec requires hosts to support.
too_large	The skill’s manifest declares a total size over 16 MiB, which is the per-skill byte budget the spec requires hosts to support.

A skill that is unloadable for a limit reason (too_many_resources or too_large) is a real skill whose manifest exceeds what any conforming host is required to handle — it is not a server bug. The skill remains visible in the catalog with its advertised manifest so you can inspect what was declared.

Prompt injection cap

Verification uses the spec’s per-skill budget (16 MiB). A separate, lower cap of 128 KiB applies to how much skill content MCPJam will place in a single model turn. A skill that verifies correctly but exceeds this cap is refused rather than truncated — a clipped skill ends mid-sentence, and the model cannot distinguish that from a skill that simply said less.