Agent Skills

Overview

MCP servers give agents tools (the actions). Skills give agents knowledge (how to use those tools effectively).

MCP servers expose tools with basic descriptions, but agents often lack the context to use them well. They don't know when to use each tool, how tools should be combined into multi-step workflows, or what best practices and edge cases to watch for. Skills fill this gap — they are the second pillar of MCP Gateway.

Agent Skills are portable instruction packages following the agentskills.io open specification. Think of them as "recipes" that turn a generic tool catalog into guided, reliable automation. A PR review skill knows to fetch the diff, analyze changes for security vulnerabilities, and post structured comments in the right order. A data analysis skill knows to load the CSV, clean nulls, run aggregations, and generate charts — without the agent figuring it out from scratch each time.

This is the same concept behind Anthropic's Agent Skills architecture: skills live in the agent's filesystem, load progressively to save tokens, and bridge the gap between raw tool access and expert-level automation.

Like all three pillars, skills follow the Manage → Monitor → Generate pattern.

How Skills Work

Progressive Disclosure

Skills are designed for efficient token usage — the same progressive loading model used by Anthropic's Claude:

This ensures agents get relevant context without overwhelming their context window. An agent can have dozens of skills installed with near-zero token cost — only the triggered skill's instructions enter the context.

Skill Structure

A skill package is a ZIP file with a SKILL.md at its root:

my-skill.skill/
  SKILL.md           # Required — YAML frontmatter + markdown instructions
  scripts/           # Optional — executable helper scripts
  references/        # Optional — external documentation, API specs
  assets/            # Optional — templates, example data

The SKILL.md uses YAML frontmatter for metadata (name, description, author, version, tags, allowed tools) followed by markdown content with step-by-step instructions. This format ensures skills are portable across any system that supports the agentskills.io spec.

Where Skills Run

Skill instructions guide the agent's reasoning. But when a skill includes bundled scripts (a validate.py, a fill_form.py), those scripts execute inside a sandbox — the third pillar. The skill's directory and files live in the sandbox's persistent filesystem. This is how the three pillars connect:

• MCP servers provide the tools (API connections)
• Skills provide the knowledge (how to orchestrate those tools)
• Sandboxes provide the computer (where skill scripts execute)

SDK Access — Calling Tools Programmatically

Skills can include Python scripts that call MCP tools programmatically using mcpgateway-sdk. This is what transforms skills from passive guidance into active tool orchestration — a script can search tools, execute them, cache intermediate results, and return a compact summary instead of raw API payloads.

How the gateway enables this: When a script runs in a sandbox, the gateway automatically injects a scoped API token as the MCPGATEWAY_TOKEN environment variable. The SDK reads this token transparently — script authors write zero authentication code. The gateway injects the token when:

• A script tool is dispatched (via tools/ + workflow.json) — the token is scoped to only the allowed_tools declared in the manifest
• A script is executed in a network-enabled sandbox (via scripts/ folder) — the token has wildcard scope for the user's accessible tools

The token is temporary (expires after execution + buffer), bound to the invoking user, and revoked in a finally block. The script never sees raw credentials for the underlying MCP servers — the gateway resolves OAuth tokens, API keys, and other credentials on each SDK call.

from mcpgateway_sdk import MCPGateway
gw = MCPGateway()  # auto-reads MCPGATEWAY_TOKEN — zero config

# Call any MCP tool through the gateway
opps = await gw.tools.execute(
    "salesforce_opportunities_list",
    {"quarter": "Q1-2026"}
)

# Search tools semantically
tools = await gw.tools.search("pipeline deals", limit=5)

# Cache data for follow-up questions
await gw.cache.set("accounts", data, ttl=600)

How the sandbox reaches the gateway without internet access: Sandboxes used for script execution run with network_enabled=True, but this does not mean open internet. In Docker (dev), the sandbox connects to the gateway over the internal Docker bridge network. In Kubernetes (prod), the sandbox pod communicates via the internal K8s service DNS. External egress is blocked by NetworkPolicy — the sandbox can only reach the gateway backend port, DNS, and HTTPS. The gateway injects MCPGATEWAY_URL pointing to its internal address (e.g., http://backend:8000), so the SDK knows where to connect. The script never makes outbound internet calls — all tool execution routes through the gateway, which applies credential resolution, audit logging, and plugin pipelines on every call.

Script Tools — Gateway-Enforced Tool Replacement

Skills can also declare script tools — Python scripts in a tools/ directory with a workflow.json manifest. This is MCP Gateway's proposal to solve the MCP token bloat problem: instead of the agent calling raw tools and receiving 200KB responses, a script tool calls the same tools internally via the SDK, filters and joins the data, and returns a compact result.

When a skill with tools/ + workflow.json is attached to a server, the gateway:

1. Reads the manifest and registers each script as a first-class MCP tool in the database
2. The agent sees these tools in tools/list and SEARCH_TOOLS — identical to any REST tool
3. When called, the gateway dispatches to a sandbox, injects a scoped token, and enforces response budgets and schema validation

The agent has zero awareness that a script is involved. It makes one tool call and gets a compact result.

my-skill/
├── SKILL.md           # Agent guidance
├── workflow.json      # Tool schemas, allowed_tools, response budgets
└── tools/
    └── summarize_pipeline.py   # Runs in sandbox, calls tools via SDK

Key enforcement features:

See Script Tools for the full architecture, including the two execution paths (agent-mediated vs gateway-enforced) and the gateway SDK reference.

Three Entry Paths

Import from Catalog

Browse and import skills from external catalogs like GitHub repositories or the skills.sh marketplace. The gateway fetches the skill package, validates it against the agentskills.io specification, and stores it locally.

curl -X POST /api/v1/skills/import \
  -d '{"source": "anthropics", "skill_name": "pr-reviewer"}'

AI Generation

The most powerful entry path. Describe what you want in plain text and a deep agent creates a complete skill package. The agent operates in a sandboxed workspace with path-validated file operations and streams real-time progress events via SSE.

curl -X POST /api/v1/skills/generate \
  -d '{"intent": "Review PRs for security vulnerabilities"}'
  # → SSE stream: planning → thinking → file_created → complete

The generation agent is guided by a comprehensive system prompt and uses workspace tools (init_skill, write_file, read_file, package_skill) to build the skill iteratively. The system prompt can be customized per deployment via the prompt override system.

Manual Upload

Upload .zip, .skill, or .md files directly. The gateway validates the package structure, checks that frontmatter follows the specification, and stores the skill.

Server Linking

Skills can be linked to specific MCP servers they are designed for. When linked, the skill's tool references can be validated against the server's actual tool catalog, and the web UI shows the association for easier discovery. This bridges the first pillar (tools) with the second (knowledge).

Portal Publishing

Skills can be published to the customer portal with categories, tags, and download tracking for team discovery. Admins curate which skills team members see, making it easy to share best practices and expert workflows across the organization.

Validation and Security

Every skill is validated against the agentskills.io specification before storage:

• Name must be lowercase-hyphenated (max 64 characters)
• Description must not exceed 1024 characters
• YAML frontmatter must include required fields
• ZIP packages must contain SKILL.md at the root or in a single subdirectory
• Package size limit: 10MB maximum with a 100-file cap
• AI generation workspace uses path traversal prevention, YAML safe loading, and filename sanitization

Key Features

• Open standard — follows agentskills.io for cross-platform portability
• Three entry paths — import from catalogs, generate with AI, or upload manually
• AI-powered generation — deep agent pattern with SSE streaming, sandboxed workspace, and customizable system prompts
• Progressive disclosure — metadata loads at startup (~100 tokens), full instructions only when triggered
• Catalog integration — GitHub repositories and skills.sh marketplace
• Starter templates — pre-built templates for API integration, data analysis, workflow automation, and code generation
• Portal publishing — categories, tags, and download tracking for team discovery
• Server linking — associate skills with specific MCP servers for tool validation

API Reference

• List skills — retrieve all skills with pagination and filtering
• Create a skill — create a skill from generated content
• Upload a skill — upload a .zip, .skill, or .md file
• Generate a skill — AI-generate a skill from a plain-text intent (SSE streaming)
• Browse catalogs — list available skills from external catalogs
• Import from catalog — import a skill from GitHub or skills.sh