> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-4414-1787809205277.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://agentskills.io/what-are-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](#skill-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:
```bash theme={"theme":"css-variables"}
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:
```bash theme={"theme":"css-variables"}
mcpjam cloud skills get --skill --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:
```bash theme={"theme":"css-variables"}
npx skills update mcp-inspector
```
To update every installed skill at once:
```bash theme={"theme":"css-variables"}
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 | `/code-review` | anywhere that server is connected |
| A 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](https://aaif.io/blog/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:
```bash theme={"theme":"css-variables"}
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.