# MCP Agent Skills Server

![Version](https://img.shields.io/npm/v/mcp-agent-skills?style=flat-square)
![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)
![Platform](https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux-lightgrey?style=flat-square)
![Standard](https://img.shields.io/badge/standard-Agent%20Skills-purple?style=flat-square)

A production-ready implementation of the **Model Context Protocol (MCP)** server designed to equip AI agents with dynamic, persistent, and executable skills.

This server adheres to the [Anthropic Agent Skills Standard](https://github.com/anthropics/skills), enabling seamless interoperability between LLMs (Claude, GPT-4o) and local system capabilities via a standardized `SKILL.md` structure.

## 📋 Capabilities

*   **Progressive Disclosure:** Reduces context window usage by exposing only skill metadata (`explore_skills`) until full instruction sets are requested (`acquire_skill`).
*   **Secure Script Execution:** Safely executes local scripts (Python, Node.js/Bun, Bash/PowerShell) encapsulated within skill directories.
*   **Cross-Platform Runtime:** Built on the Bun runtime for native performance on Windows, macOS, and Linux without complex environment handling.
*   **Zero-Config Discovery:** Automatically scans and registers valid skills from the `./skills` directory.

## 🚀 Installation

### Option A: Global Installation (Recommended for Persistence)
Install the package globally to ensure the server is always available:

```bash
npm install -g mcp-agent-skills
```

### Option B: Run via NPX (Zero-Installation)
Execute the server on-demand without local installation:

```bash
npx mcp-agent-skills
```

### Option C: Local Deployment (For Contributors)
Clone the repository to develop custom skills or modify core logic.


---

## ⚙️ Configuration

To use this server with your AI client, add the following configuration.

### Claude Desktop
Located at:
*   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
*   **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "agent-skills": {
      "command": "npx",
      "args": ["-y", "mcp-agent-skills"]
    }
  }
}
```

*> **Dev Note:** If running from source, replace `command` with `bun` and `args` with `["run", "/absolute/path/to/index.ts"]`.*

### Cursor IDE
1. Navigate to **Settings** > **General** > **MCP Servers**.
2. Click **Add new MCP server**.
3. Enter the configuration:
    *   **Name:** `agent-skills`
    *   **Type:** `command`
    *   **Command:** `npx -y mcp-agent-skills`

### Zed Editor
Edit `.config/zed/settings.json`:

```json
{
  "context_servers": {
    "agent-skills": {
      "command": "npx",
      "args": ["-y", "mcp-agent-skills"]
    }
  }
}
```

---

## 🛠️ Creating Custom Skills

A **Skill** is a self-contained directory that teaches an agent how to perform a specific task.

### Directory Structure
```text
skills/
└── my-custom-skill/
    ├── SKILL.md          # Definition & Instructions (Required)
    ├── README.md         # Human-readable documentation
    └── scripts/          # Executable logic
        └── analyze.py
```

### The `SKILL.md` Standard
The entry point must contain YAML frontmatter followed by Markdown instructions.

```markdown
---
name: Data Processor
description: Clean and normalize CSV datasets using Python.
version: 1.0.0
---

# Instructions
1. When the user provides a CSV file path, execute the cleaning script.
2. Report the number of rows processed.

## Tools
Use `run_skill_script` to execute `scripts/clean.py`.
```

---

## 🔒 Security Implications

This MCP server grants the connected AI agent the ability to:
1.  **Read Files:** Access `SKILL.md` and associated resources within the package directory.
2.  **Execute Code:** Run scripts defined in the `skills` folder using local runtimes (Python, Node, Shell).

**Recommendation:** Only install skills from trusted sources. Review `scripts/` content before loading a new skill if you are running a custom fork.

## 🤝 Contributing

Contributions are welcome. Please ensure your skills follow the directory structure and include a `README.md`.

1.  Fork the repository.
2.  Create a feature branch (`git checkout -b feature/new-skill`).
3.  Commit your changes.
4.  Open a Pull Request.

## 📄 License

This project is licensed under the **MIT License**.