Skills MCP

Create .mcp.json in your project or ~/.claude.json globally:

{
  "mcpServers": {
    "skills-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "skills-mcp", "-s", "/absolute/path/to/skills"]
    }
  }
}

Create ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "skills-mcp": {
      "command": "npx",
      "args": ["-y", "skills-mcp", "-s", "/absolute/path/to/skills"]
    }
  }
}

Create .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "skills-mcp": {
      "command": "npx",
      "args": ["-y", "skills-mcp", "-s", "/absolute/path/to/skills"]
    }
  }
}

Create .vscode/mcp.json in your project:

{
  "servers": {
    "skills-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "skills-mcp", "-s", "/absolute/path/to/skills"]
    }
  }
}

Skills are modular, self-contained packages that transform general-purpose AI agents into specialized experts. Think of them as "onboarding guides" for specific domains or tasks—they provide procedural knowledge that no model can fully possess.

Example: A PDF Processing Skill might include:

• Instructions for extracting text and filling forms
• Python scripts for reliable PDF operations
• Reference documentation for advanced use cases
• Template files for generating documents

Instead of explaining PDF processing in every conversation, you install the skill once and the agent knows when and how to use it.

While Claude has native Skills support built-in, this MCP server brings that same capability to other agents:

• Universal compatibility: Any MCP-compatible agent can now use Claude Skills
• Unified management: Single skills directory works across all agents and platforms
• Optional for Claude: When using Claude Desktop or Claude Code, you can disable this server and use native Skills instead
• Progressive disclosure: Skills load information in stages, minimizing context usage

Key benefit: Create skills once in Claude's format, use them everywhere—whether with Claude's native support or via MCP in VS Code, Cursor, and other tools.

Skills use a three-level progressive disclosure system to manage context efficiently:

1. Metadata (~100 tokens): Name and description loaded at startup
2. Instructions (~5k tokens): Main SKILL.md content loaded when skill is triggered
3. Resources (loaded as needed): References, scripts, and assets accessed on-demand

This means you can install dozens of skills without context penalty—agents only load what they need, when they need it.

Skills follow Anthropic's convention-based format from Claude Skills:

skill-name/
├── SKILL.md              # Required: Skill metadata and instructions
├── references/           # Optional: Documentation loaded as needed
├── scripts/              # Optional: Executable code
└── assets/               # Optional: Templates and files for output

SKILL.md Format

---
name: Skill Name
description: What this skill does and when to use it (be specific!)
---

# Skill Name

## Instructions

[Step-by-step guidance for the agent]

## Examples

[Concrete usage examples]

Tips for writing good skills:

• Make descriptions specific about WHEN to use the skill
• Use imperative/infinitive form in instructions ("To do X, use Y")
• Keep SKILL.md under 5k words; move detailed docs to references/
• Bundle scripts for deterministic operations
• Include templates in assets/ for files used in output

For more details, see the Skills specification.

Arguments

• -s, --skills-dir: Path to skills directory (required, can be specified multiple times, must be absolute paths)

Multiple Skills Directories

When specifying multiple skills directories, all directories are scanned for skills. If multiple skills with the same ID are found across different directories, a warning will be logged and the last loaded skill will be used.

Example configuration with multiple directories:

{
  "servers": {
    "skills-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "skills-mcp",
        "-s",
        "/path/to/skills1",
        "-s",
        "/path/to/skills2"
      ]
    }
  }
}

Testing the Server

You can test the server manually using stdio:

npx skills-mcp --skills-dir /absolute/path/to/skills

The server will start and wait for JSON-RPC messages on stdin. Press Ctrl+C to stop the server.

⚠️ Important Note

Skills provide agents with instructions and executable code. Only use skills from trusted sources—those you created yourself or obtained from Anthropic.

A malicious skill can:

• Direct agents to invoke tools in harmful ways
• Execute code with the agent's privileges
• Access or expose sensitive data

💡 Usage Tip

Treat skills like software installation: Only install from trusted sources, especially in production systems with access to sensitive data or critical operations.

For more details, see the Security Considerations section in the spec.

list_skills

Lists all available skills with their metadata.

Output:

{
  "skills": [
    {
      "id": "pdf-processing",
      "name": "PDF Processing",
      "description": "Extract text and tables from PDF files..."
    }
  ]
}

get_skill

Retrieves the full skill content and absolute path.

Input:

{
  "id": "pdf-processing"
}

Output:

{
  "path": "/Users/username/.claude/skills/pdf-processing/SKILL.md",
  "name": "PDF Processing",
  "description": "Extract text and tables...",
  "content": "# PDF Processing\n\n## Quick start\n..."
}

init-skills

Provides informational guidance about the Skills MCP workflow. This prompt:

• Explains what skills are and how they're structured
• Outlines the progressive disclosure model (load only what you need, when you need it)
• Describes the step-by-step workflow for discovering, loading, and using skills
• Clarifies that the MCP is a minimal wrapper—agents handle all file operations

When to use: Run at the start of a conversation to provide background context. The prompt is informational only—it doesn't trigger any immediate actions. Agents will use skills when they encounter tasks that match available skill descriptions.

The Skills MCP follows a minimal wrapper design that leverages the full capabilities of modern AI agents:

What the server provides:

• Skill discovery and metadata
• Skill content with absolute file paths
• Skills-specific context formatting

What agents handle (using their existing tools):

• Reading referenced files (references/, scripts/, assets/)
• Executing scripts
• Searching and navigating directories

Example workflow:

1. Agent calls list_skills and finds "PDF Processing"
2. Agent calls get_skill and receives /path/to/pdf-processing/SKILL.md
3. Skill mentions references/FORMS.md for advanced features
4. Agent constructs full path and reads it: /path/to/pdf-processing/references/FORMS.md
5. Agent executes scripts: cd /path/to/pdf-processing && python scripts/fill_form.py

This design keeps the MCP server simple while giving agents maximum flexibility.