skill-mcp-server 0.1.0
Turn any AI agent into a specialist - A Model Context Protocol server for modular skills
Requires Python: >=3.10
Keywords: agent, ai, automation, claude, llm, mcp, model-context-protocol, skills

# Skill MCP Server

<p align="center">
  <strong>Turn any AI agent into a specialist — just drop in a skill folder.</strong>
</p>

<p align="center">
  <a href="#features">Features</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#how-it-works">How It Works</a> •
  <a href="#creating-skills">Creating Skills</a> •
  <a href="#documentation">Documentation</a>
</p>

---

**Skill MCP Server** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI agents like Claude to dynamically load and use modular "skills".

Think of it as a **plugin system for AI agents** — drop a skill folder into the directory, and your agent instantly gains new capabilities. No coding required, no server restarts needed.

## Why Skill MCP Server?

| Traditional Approach | With Skill MCP Server |
|---------------------|----------------------|
| Write code to extend agent capabilities | Just copy a folder |
| Restart services to apply changes | Hot reload, instant availability |
| Each capability developed separately | Community-shared, plug-and-play |
| Complex integration work | Zero configuration |

## Features

- **Instant Capability Extension** — Drop skill folders, gain superpowers
- **Zero Configuration** — Skills are auto-discovered and loaded
- **Hot Reload** — Add new skills without restarting the server
- **Multi-Language Scripts** — Execute Python, Shell, JavaScript, TypeScript
- **Secure by Design** — Path validation, sandboxed file operations
- **Resource Bundling** — Include templates, references, and assets with skills

## Quick Start

### Installation

```bash
# Using pip
pip install skill-mcp-server

# Using uv (recommended)
uv pip install skill-mcp-server
```

### 30-Second Setup

```bash
# 1. Create a skills directory
mkdir skills

# 2. Download or create a skill (example: copy the skill-creator)
cp -r examples/skill-creator skills/

# 3. Start the server
skill-mcp-server --skills-dir ./skills
```

That's it! Your AI agent can now use the skill.

### Configure with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "skill-server": {
      "command": "skill-mcp-server",
      "args": ["--skills-dir", "/path/to/your/skills"]
    }
  }
}
```

### Configure with Claude Code

Add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "skill-server": {
      "command": "skill-mcp-server",
      "args": [
        "--skills-dir", "/path/to/your/skills",
        "--workspace", "/path/to/workspace"
      ]
    }
  }
}
```

## How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                        AI Agent (Claude)                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ MCP Protocol
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Skill MCP Server                            │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐    │
│  │   skill   │  │  skill_   │  │  skill_   │  │   file_   │    │
│  │  loader   │  │ resource  │  │  script   │  │   ops     │    │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Skills Directory                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │ data-analyst│  │ doc-writer  │  │ api-helper  │  ...        │
│  │  SKILL.md   │  │  SKILL.md   │  │  SKILL.md   │             │
│  │  scripts/   │  │  templates/ │  │  references/│             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `skill` | Load a skill to get detailed instructions |
| `list_skills` | List all available skills |
| `skill_resource` | Read resource files from a skill |
| `skill_script` | Execute scripts bundled with a skill |
| `file_read` | Read files from workspace |
| `file_write` | Write files to workspace |
| `file_edit` | Edit existing files in workspace |

## Creating Skills

A skill is simply a folder containing a `SKILL.md` file:

```
my-skill/
├── SKILL.md              # Required: Instructions for the AI
├── scripts/              # Optional: Executable scripts
│   └── process_data.py
├── references/           # Optional: Reference documentation
│   └── api_docs.md
└── assets/               # Optional: Templates, images, etc.
    └── report_template.md
```

### SKILL.md Format

```markdown
---
name: my-skill
description: Brief description of what this skill does and when to use it
---

# My Skill

## Overview

Explain what this skill enables the AI to do.

## Usage

Step-by-step instructions for the AI agent...

## Available Resources

- `scripts/process_data.py` - Process input data
- `assets/report_template.md` - Output template
```

### Example: Data Analyst Skill

```markdown
---
name: data-analyst
description: Analyze CSV data and generate insights reports
---

# Data Analyst

## When to Use

Use this skill when the user wants to:
- Analyze CSV or tabular data
- Generate statistical summaries
- Create data visualizations

## Workflow

1. Read the data file using `file_read`
2. Execute `scripts/analyze.py` for statistical analysis
3. Use `assets/report_template.md` to format the output
4. Write the report using `file_write`
```

## Use Cases

- **Data Analysis** — Agent becomes a data scientist
- **Document Generation** — Agent creates professional documents
- **API Integration** — Agent works with specific APIs
- **Code Review** — Agent follows your team's standards
- **DevOps Tasks** — Agent automates deployment workflows

## Documentation

- [Getting Started Guide](docs/getting-started.md)
- [Creating Skills](docs/creating-skills.md)
- [Skill Format Reference](docs/skill-format.md)
- [API Reference](docs/api/)

## Development

```bash
# Clone the repository
git clone https://github.com/your-org/skill-mcp-server.git
cd skill-mcp-server

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

---

<p align="center">
  <sub>Built with the <a href="https://modelcontextprotocol.io/">Model Context Protocol</a></sub>
</p>