Agent Skills MCP Server

This project implements a Model Context Protocol (MCP) server that exposes "Skills" to AI agents. Skills are specialized instruction sets and resources that help agents perform specific tasks with domain expertise. You can find detailed skills specification here: Agent Skills Spec

Overview

The Agent Skills MCP Server allows you to define skills using a simple file-based structure (directories or ZIP files) containing a SKILL.md file. This server then exposes these skills as MCP tools that agents can invoke.

When an agent invokes a skill tool, it receives:

Instructions: Specialized guidance for completing the task.
Resources: Access to files and data associated with the skill.
Metadata: Information about the skill, such as allowed tools and licensing.

Features

File-based Skill Registry: Skills are loaded from a local directory.
Support for Directory and ZIP Skills: Skills can be defined as a directory or packaged as a .zip or .skill file.
Dynamic Tool Registration: Each skill is automatically registered as an MCP tool.
Resource Access: Skill resources are exposed via MCP resource URIs.
Spring Boot Integration: Built using Spring Boot and Spring AI.

Getting Started

Prerequisites

Java 24
Maven

Configuration

The server looks for skills in a directory specified by the skills.root property. By default, it looks for a skills directory in the current working directory.

You can configure this in application.properties or via command-line arguments:

skills.root=/path/to/your/skills

Building the Project

mvn clean package

Running the Server

java -jar target/agent-skills-mcp.jar

Or with a custom skills directory:

java -jar target/agent-skills-mcp.jar --skills.root=/path/to/my/skills

Creating a Skill

A skill is defined by a SKILL.md file. This file contains YAML front matter for metadata and Markdown content for instructions.

Structure

A skill can be a directory or a ZIP file.

Directory Structure:

my-skill/
├── SKILL.md
├── data.csv
└── script.py

SKILL.md Format:

---
name: My Skill Name
description: A short description of what this skill does.
license: MIT
allowed_tools:
  - tool_name_1
  - tool_name_2
extra:
  key: value
---

# Instructions

Here are the detailed instructions for the agent...

Metadata Fields

name: (Required) The display name of the skill.
description: (Required) A brief description used for the tool definition.
license: (Optional) License information for the skill.
allowed_tools: (Optional) A list of tool names that the agent is allowed/encouraged to use when executing this skill.
extra: (Optional) Any additional metadata.

Usage with MCP Clients

Once the server is running, connect your MCP client (e.g., an AI assistant or IDE plugin) to it. The client will discover the available skills as tools.

When an agent uses a skill tool:

It provides a task description.
The server returns the skill's instructions and references to any included resources.
The agent follows the instructions to complete the task, potentially fetching resources via the MCP protocol.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

MCP Servers