Skills over MCP
Serve Agent Skills from a GitHub repository or a remote skills server, merged into one governed catalog for every connected MCP client.
Skills over MCP lets your organization centrally manage Agent Skills through the MCP Gateway instead of copying skill folders onto individual machines. Connect a GitHub repository or a 3rd party MCP server that serves skills, and treat the functionality exactly like you do tools in Airia’s MCP Gateway. Just like with tools, Airia scans skills for prompt injection and version controls everything so that nothing can enter an LLM that hasn’t already been approved by an admin.
What a skill is
A skill is a folder. Inside it is a file called SKILL.md holding a name, a one-line description of when to use it, and then the instructions themselves. The folder can also hold reference documents, scripts, and assets.
csv-insights/
SKILL.md
scripts/summarize.py
references/output-format.md---
name: csv-insights
description: Summarize a CSV file. Use when the user has a .csv file and wants a quick overview.
---
Read the file with pandas, then report row and column counts, column types,
and basic stats. Format the result using references/output-format.md.The block between the --- lines is the frontmatter: the metadata an agent reads to decide whether a skill is relevant, before it reads any of the instructions underneath.
An agent does not load all of this at once. It sees only names and descriptions until one matches what the user is doing, then reads that skill's instructions, then fetches reference files or scripts only if those instructions call for them. This is progressive disclosure, and it is why you can keep a large library available without filling the model's context.
A skill is instructions, not code Airia runs. The model reads the instructions and follows them. If a skill includes a script, that script runs on the user's own machine inside their client. The Gateway delivers files. It never executes them.
Skills compared with tools
Tools are capabilities you give your agent. Skills are instruction manuals. The two are complementary rather than competing. A skill often tells the model which tools to call and in what order. Skills need no new transport: they ride the same MCP resources machinery the Gateway already uses.
Why serve skills through the Gateway
A skill normally lives in a folder on one person's machine. That works for an individual but breaks down for an organization.
| Skills on a laptop | Skills through the Gateway | |
|---|---|---|
| Where the files live | On each machine, copied by hand | One repository or skills server, fetched on demand |
| Updating them | Everyone re-copies, or drifts | Change the source once |
| Who manages them | The individual | A team or organization admin |
| Admin visibility | None | By design |
There is a governance gap. A SKILL.md is text injected straight into the model's context, which puts it in the same threat class as a malicious tool description. Airia already scans tool definitions for prompt injection; Tool Scanning now covers skills the same way.
How the Gateway handles skills
The Gateway is an aggregator. It allows you to create Skill MCPs connected to GitHub repos and combine them along with other MCPs (that might themselves contain Skills) to create powerful gateways available to everyone an admin grants access to.
Each skill carries the name of the server it came from, the same attribution the Gateway already stamps on tools.
Remote skills MCP servers
If you know of an MCP server that serves skills that doesn't yet exist in our catalogue. Add it as an ordinary remote custom server with Transport Type set to HTTP (MCP Protocol). There are no skills-specific fields. The Gateway asks the server what it supports when it connects, and if skills are among them, it starts aggregating.
GitHub repositories
GitHub repos are a natural place to store and version control Skills. A GitHub repository is not itself an MCP server, so one extra piece sits in front of it: SpecLink, the same Airia service that converts an OpenAPI spec into MCP tools. It reads a skills repo and publishes it as a server.
Set up a Skills MCP Server from a GitHub Repository
Start the custom MCP server creation flow and fill in the Basic Information step as usual.
On the Remote Configuration step, set Transport Type to Skills Repository.
| Field | Description |
|---|---|
| Repository URL | Required. An HTTPS github.com repository URL, for example https://github.com/acme/agent-skills. |
| Branch, tag, or commit | Optional. For example main or release/v2. Leave empty to use the repository's default branch and latest commit at fetch time. |
| Skills path | Optional. The repository-relative folder holding the skills, for example skills or packs/finance. Leave empty to search the whole repository. |
Click Test repository, then Run test. The test must pass for the exact repository, branch, and path you entered before Next unlocks. See The test step.
If the Skills Repository is private, you will need indicate it needs a GitHub Personal Access Token (PAT). If the Skills Repository is public, you do not need to provide authentication.
Confirm the details and create the server. Approve it in Server Management for all the users and groups you want to give access.
The test step
The test reads the repository there and then, without saving anything. If the repository is private, paste a GitHub personal access token into the dialog. That token is used for the test only and is not stored.
| Result | What it means |
|---|---|
| Skills found | Reports how many skills were found and previews up to ten of them by name and skill:// URL. |
| No skills found | The repository was readable but held no valid skills. Check the branch, the skills path, and the two repository rules below. |
| Test failed | Reports which stage failed, either connecting to the repository or reading the skills index. A bad URL, a missing token, or a private repository without one fails at the first stage. |
Repository requirements
Layout does not matter. Skills can sit at the repository root, under a skills/ folder, or nested in category folders. Every folder containing a SKILL.md is picked up.
Two rules do matter, and both are common causes of a half-empty result:
- A skill's
namemust match its folder name. A skill incsv-insights/must declarename: csv-insights. - The frontmatter may contain only recognized fields:
name,description,license,compatibility,metadata, andallowed-tools. Anything else, such asowner: finance-team, invalidates the skill.
A skill that breaks either rule is skipped silently, which is why a repository can report fewer skills than it appears to hold. A repository where every skill breaks them reports that it contains no valid skills.
Add the MCP server to a Gateway
Open the Gateway and add the server as an app, the same as any other. For a private repository, the GitHub token is entered here in the Gateway's credential step, as a GitHub Access Token. It is deliberately not collected in the creation wizard: a Skills Repository follows the same pattern as every other custom server, where the credential type is declared at creation and its value supplied when the server is configured on a Gateway.
Once it is configured, a Select Skills tab appears next to Select Tools, listing each skill with its description, its skill:// URL, and a security-scan badge. The application's row in the Gateway's left-hand navigation shows both counts, for example 0 tools selected · 6 skills selected, so a skills-only source does not look like an empty application. Toggle off any skills you do not wished to be served with the MCP server.
Security scanning
Each skill's SKILL.md is fetched when the source is discovered and run through the same Policy Engine scanner Airia uses for tool definitions. The verdict appears as a badge next to each skill on the Skills tab.
| Badge | Meaning |
|---|---|
| Verified | Nothing found. |
| Risk detected | Prompt-injection risk found in the skill. Review it before enabling the server. |
| Scan error | The scan could not complete. |
| Not scanned | The file could not be read, was over the size limit, or was beyond the per-server scan limit. |
Scanning limits
- 20 skills per server are scanned, in catalog order. The rest are listed as Not scanned rather than hidden, so nothing disappears from the inventory.
- 256 KB per file. A larger file is skipped entirely rather than partly scanned, because a verdict on half a file would be a false pass.
- Only
SKILL.mdis scanned. Reference files and scripts inside a skill are not.
What is reported and what is enforced
Scanning reports. It does not block. A skill marked Risk detected is still served to clients, and the verdict is visible to an admin in Airia but is not attached to the catalog clients read.
Two things the Gateway does enforce:
- Provenance. Every skill carries the source it came from, and an upstream cannot overwrite that label.
- Integrity. The checksum a source publishes with a skill is passed through exactly as published. The Gateway does not compute or repair a missing one, because that obligation sits with the publisher.
Scanning needs Tool Scanning switched on as well as Skills over MCP. With skills on and scanning off, the catalog works normally and no verdicts appear.
What end users see
When a client connects, the Gateway tells it that skills are available and where the catalog is. Everything after that is driven by the client. While Airia's MCP Gateway fully supports extention SEP-2640 (Skills over MCP), not all clients do. Airia's Skills over MCP functionality will not function properly if the client an end user is using does not support Skills over MCP itself.
| Client | Behavior |
|---|---|
| goose | Reads the skill catalog on its own and matches skills to a request automatically. |
| Claude Code | Reads and uses skills correctly once pointed at them, but does not load the catalog by itself. |
| Clients without the extension | See the same files as ordinary MCP resources. |