> ## Documentation Index
> Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-4053-1786992934526.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
Cloud (hosted) skills are available on accounts where the feature has been enabled — they are part of a project's environments, alongside MCP servers and Computers. Local skills, read from your filesystem, need no account feature and always work.
[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.
## 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 are **SKILL.md-only**. Folders that contain files other than `SKILL.md` are rejected — inline any content that `SKILL.md` references directly into the file before uploading.
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
```
## 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 — their catalog is fetched from the server on demand rather than inlined in the prompt.