# 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](https://agentskills.io/specification)

## 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:
1.  **Instructions**: Specialized guidance for completing the task.
2.  **Resources**: Access to files and data associated with the skill.
3.  **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:

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

### Building the Project

```bash
mvn clean package
```

### Running the Server

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

Or with a custom skills directory:

```bash
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:**

```markdown
---
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:
1.  It provides a `task` description.
2.  The server returns the skill's instructions and references to any included resources.
3.  The agent follows the instructions to complete the task, potentially fetching resources via the MCP protocol.

## License

   Copyright 2025 Sohu.com Inc.

   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.