MCP Agent Skills Server

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, 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:

npm install -g mcp-agent-skills

Option B: Run via NPX (Zero-Installation)

Execute the server on-demand without local installation:

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

{
  "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:

{
  "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

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.

---
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.