agentskill-mcp

AgentSkill MCP

Bring Claude Agent Skills to ANY MCP-compatible Agent

A universal MCP server that enables any Agent application with MCP support to use Anthropic's official Claude Agent Skills with progressive disclosure - reducing context overhead while maximizing capability.

Package Name: agentskill-mcp | PyPI: agentskill-mcp

English | 简体中文

Why AgentSkill MCP?

Claude Agent Skills are brilliantly designed but locked to Claude's ecosystem. This project breaks that limitation by:

• ✅ Universal Compatibility: Works with ANY MCP-compatible agent (Kilo Code, Cursor, Roo Code, Codex, and more)
• ✅ 100% Claude Skill Compatible: Uses official Anthropic Skill format - no modifications needed
• ✅ Progressive Disclosure: Implements the same smart context loading as Claude Code
• ✅ Zero Lock-in: Standard MCP protocol means you're never tied to one platform

The Problem Skills Solve

Traditional MCP tools load ALL documentation upfront, consuming 20k+ tokens before you even start. With 15+ tools, your agent is context-starved before doing any real work.

Skills fix this through progressive disclosure: agents see a lightweight skill list initially, then load full details only when needed. This project brings that same efficiency to every MCP-compatible agent.

Features

• 🚀 One-Line Installation: pip install agentskill-mcp or uvx agentskill-mcp
• 🔌 Universal MCP Compatibility: Works with Kilo Code, Cursor, Roo Code, Codex, Cherry Studio, and any MCP-compatible agent
• 📦 Official Skill Format: Fully compatible with Anthropic's Claude Skills
• 🎯 Progressive Disclosure: Smart context loading - minimal overhead until skills are needed
• 🔄 Hot Reload: File changes detected and updated in real-time (where protocol supported)
• 🗂️ Smart Path Discovery: Auto-detects .claude/skills/, .skill/, or custom directories
• 🌍 Environment Aware: Project-level and global skill directories with automatic detection
• 🎨 ClaudeCode Compatible: Supports both .claude/skills/ (ClaudeCode format) and .skill/ (legacy)

Supported Platforms

Tested and verified on:

• ✅ Kilo Code (VSCode extension)
• ✅ QwenCode (Alibaba's AI coding assistant)
• ✅ Cursor (AI code editor)
• ✅ Roo Code (AI coding assistant)
• ✅ Codex (AI development platform)
• ⚠️ Cherry Studio (limited - conversation-only agents have reduced functionality)

In theory: Any agent implementing the Model Context Protocol should work.

Quick Start

Installation

Method 1: Using pip (Recommended)

pip install agentskill-mcp

Method 2: Using uvx (Recommended for trying without installation)

# Run directly without installing
uvx agentskill-mcp --help

Method 3: Using uv

uv pip install agentskill-mcp

Verify Installation:

agentskill-mcp --help

# Expected output:
# usage: agentskill-mcp [-h] [--skills-dir SKILLS_DIR]
#                       [--log-level {DEBUG,INFO,WARNING,ERROR}]
#
# AgentSkill MCP - MCP Server for Claude Skills with progressive disclosure

For Development (if you want to modify the code):

git clone https://github.com/QianjieTech/Open-ClaudeSkill.git
cd Open-ClaudeSkill
pip install -e .

Configuration

Add to your MCP client configuration file:

Kilo Code / Cursor / Roo Code / Codex

Edit your MCP configuration file (.kilocode/mcp.json, .cursor/mcp.json, or similar):

{
  "mcpServers": {
    "skills": {
      "command": "agentskill-mcp",
      "args": []
    }
  }
}

For uvx users (no installation needed):

{
  "mcpServers": {
    "skills": {
      "command": "uvx",
      "args": ["agentskill-mcp"]
    }
  }
}

When to specify --skills-dir:

• MCP server starts in a directory other than the project directory

If your agent supports project-level MCP configuration, configuring this MCP tool at the project level will automatically load skills from .claude/skills/ or .skill/ in the current directory. Otherwise, you need to specify the skill directory via the --skills-dir parameter.

💡 Tip: If Kilo Code doesn't load skills after configuring project-level MCP, manually click the "Refresh MCP Server" button or restart VSCode.

QwenCode

Edit C:\Users\YourUserName\.qwen\settings.json (Windows) or ~/.qwen/settings.json (Mac/Linux):

{
  "mcpServers": {
    "skills": {
      "command": "agentskill-mcp",
      "args": ["--skills-dir", "C:\\Users\\YourName\\.skill"]
    }
  }
}

Other MCP-Compatible Agents

AgentSkill MCP works with ANY agent that supports the Model Context Protocol. Check your agent's documentation for MCP configuration location, then use the same JSON format as above.

Loading Skills

Create a skills directory and add skill packages:

Format 1: ClaudeCode Format (Recommended for ClaudeCode users)

# Create in current project (recommended)
Create .claude/skills/ in project root directory

# Or create globally
mkdir -p ~/.claude/skills    # Linux/Mac
mkdir C:\Users\YourName\.claude\skills  # Windows

Format 2: Legacy Format (Compatible with other agents)

# Create in current project
Create .skill/ in project root directory

# Or create globally
mkdir ~/.skill         # Linux/Mac
mkdir C:\Users\YourName\.skill  # Windows

Then place your Skill packages in the skills directory. The ./examples directory contains several official Anthropic Skill packages, which are sufficient for Step 5 testing.

# Example of migrating skills (ClaudeCode format)
Copy examples/canvas-design -> .claude/skills/
Copy examples/brand-guidelines -> .claude/skills/

# Or (Legacy format)
Copy examples/canvas-design -> .skill/
Copy examples/brand-guidelines -> .skill/

The final structure should look like:

• ClaudeCode format: .claude/skills/canvas-design/
• Legacy format: .skill/canvas-design/

Try It Out

Restart your Agent application and test with:

Create a 1920x1080 promotional poster using Anthropic brand style.
Theme: "AI belongs to the future? AI is just a means, not an end"

What happens:

1. Agent sees available skills in the load_skill tool description
2. Agent identifies relevant skills (canvas-design, brand-guidelines)
3. Agent calls load_skill to get full skill details
4. Agent follows skill instructions to create the poster

Note: The agent may call only one skill depending on how it interprets the task. This is normal - AI agents have some inherent randomness in tool selection.

Skill Format

Skills follow the official Claude Skill format:

Frontmatter (YAML)

---
name: skill-name          # Required: matches folder name
description: |            # Required: detailed description for agent matching
  What this skill does and when to use it.
  Include keywords that agents should match on.
license: MIT              # Optional: license information
---

Skill Content

After the frontmatter, provide detailed Markdown instructions:

• Clear, actionable guidance
• Examples and best practices
• References to auxiliary resources

Auxiliary Resources

Skills can include resources like templates, fonts, scripts:

# ClaudeCode format
.claude/skills/
├── algorithmic-art/
│   ├── SKILL.md
│   └── templates/
│       ├── viewer.html
│       └── generator.js

# Or legacy format
.skill/
├── algorithmic-art/
│   ├── SKILL.md
│   └── templates/
│       ├── viewer.html
│       └── generator.js

Reference resources in your skill:

Read `templates/viewer.html` using the Read tool

How It Works

Progressive Disclosure Implementation

The Challenge: How to implement progressive disclosure within the MCP framework?

Official Claude Implementation (inferred from behavior):

• Built-in Skill system integrated in agent's system prompt
• Initial display shows only <available_skills> list
• Special load_skill command triggers full content loading

Our MCP Implementation:

1. Single MCP Tool: load_skill

   • Embeds all available skill metadata in the tool's description
   • Agents see the skill list without loading full content

2. Tool Description Structure:

Tool(
    name="load_skill",
    description="""Execute a skill within the main conversation

<skills_instructions>
When users ask you to perform tasks, check if any of the
available skills below can help...
</skills_instructions>

<available_skills>
<skill>
  <name>code-reviewer</name>
  <description>Comprehensive code review framework...</description>
</skill>
<skill>
  <name>calculator</name>
  <description>Mathematical calculations...</description>
</skill>
</available_skills>
""",
    inputSchema={
        "type": "object",
        "properties": {
            "skill": {"type": "string"}
        }
    }
)

3. On-Demand Loading:
   • Agent matches task with skills from <available_skills>
   • Calls load_skill(skill="code-reviewer")
   • Server reads .skill/code-reviewer/SKILL.md
   • Returns full skill content

Why Some Agents Have Limited Support?

Cherry Studio and conversation-only agents face limitations:

1. No Environment Awareness: Cannot detect current directory or auto-load project skills
2. Global Configuration Only: Must hardcode skill directories - all projects share same skills
3. Tool Availability: Skills may reference tools (e.g., Read, Write) that conversation agents lack

Path Discovery

The server automatically finds skills using this priority:

1. Command-line argument: --skills-dir /path/to/skills
2. Environment variable: MCP_SKILLS_DIR=/path/to/skills
3. Dynamic setting: Via set_skills_directory tool
4. Project-level: .claude/skills/ or .skill/ in project root (detects .git, .claude/, package.json, etc.)
5. Global fallback: ~/.skill

Note: The project-level discovery prioritizes .claude/skills/ (ClaudeCode format) over .skill/ (legacy format) when both exist.

Usage

For Type B Clients (with local agent capability)

Agents can set the skills directory dynamically:

Agent detects: User is in /path/to/project
Agent calls: set_skills_directory(path="/path/to/project")
Server responds: Discovered 5 skills: code-reviewer, calculator, ...

For Type A Clients (without local agent capability)

Use global configuration:

mkdir ~/.skill
cp -r examples/code-reviewer ~/.skill/

Tools Provided

set_skills_directory

Set the skills directory for the current session.

Parameters:

• path (string): Absolute or relative path to project, .claude/skills/, or .skill directory

Example:

set_skills_directory(path="/path/to/project")

Note: The tool will automatically detect and use .claude/skills/ if it exists, otherwise fall back to .skill/.

load_skill

Load and activate a skill by name.

Parameters:

• skill (string): Name of the skill to load

Example:

load_skill(skill="code-reviewer")

Advanced Configuration

Environment Variables

• MCP_SKILLS_DIR: Override default skills directory

Command-Line Arguments

agentskill-mcp --skills-dir /custom/path --log-level DEBUG

Logging

Set log level for debugging:

agentskill-mcp --log-level DEBUG

Levels: DEBUG, INFO, WARNING, ERROR

Examples

See the examples/ directory for sample skills:

• algorithmic-art: Create generative art using p5.js
• canvas-design: Design visual art and posters
• brand-guidelines: Apply Anthropic brand styling
• code-reviewer: Comprehensive code review framework
• calculator: Mathematical calculations

Development

Running from Source

# Install development dependencies
uv pip install -e .

# Run the server
uv run agentskill-mcp

# Run with debug logging
uv run agentskill-mcp --log-level DEBUG

Creating Custom Skills

1. Copy an example skill as a template
2. Modify the frontmatter (name, description)
3. Update the instructions
4. Add any auxiliary resources
5. Test with your agent

Architecture

Core Components

• ServerState: Manages runtime state and path discovery
• SkillLoader: Discovers and parses skill files
• SkillFileHandler: Monitors file changes with debouncing
• SkillMCPServer: Main MCP server implementation

Progressive Disclosure

Skills are exposed via a single load_skill tool that lists all available skills in its description. This minimizes initial token usage while providing full discovery.

Hot Reload

File changes are detected via watchdog and trigger skill reloading. Changes take effect immediately for the next agent request.

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - See LICENSE for details.

Resources

• Documentation: Official Docs
• Agent Skills Spec: Anthropic Spec
• MCP Protocol: Model Context Protocol

---

Made with ❤️ by the Open-ClaudeSkill community