moscaverd/local-skills-mcp

📑 Table of Contents

• What is Local Skills MCP?
• ✨ Features
• 🚀 Quick Start
• 📝 SKILL.md Format
• 🎯 Usage
• 🆚 Differences from Built-in Skills
• ❓ FAQ
• 🤝 Contributing

What is Local Skills MCP?

A universal Model Context Protocol (MCP) server that enables any LLM or AI agent to access expert skills from your local filesystem. Your skills become portable, reusable prompt libraries that work across Claude Code, Claude Desktop, Cline, Continue.dev, custom agents, or any MCP-compatible client.

Transform AI capabilities with structured, expert-level instructions for specialized tasks. Lazy loading preserves context—only skill names and descriptions load initially; full content loads on-demand.

✨ Features

• 🌐 Universal - Works with any MCP client (Claude Code, Desktop, Cline, Continue.dev, custom agents)
• 🔄 Portable - Write once, use across multiple AI systems and LLMs (Claude, GPT, Gemini, local models)
• ⚡ Context Efficient - Lazy loading: only skill names/descriptions load initially (~50 tokens/skill), full content on-demand
• 🔥 Hot Reload - All changes apply instantly (new skills, edits, deletions) without restart
• 🎯 Multi-Source - Auto-aggregates from package built-in skills, ~/.claude/skills, ./.claude/skills, ./skills, and custom paths
• 📦 Zero Config - Works out-of-the-box with standard skill locations
• ✨ Ultra Simple - Single tool (get_skill) with dynamic skill discovery

🚀 Quick Start

Install

From npm (recommended):

npm install -g local-skills-mcp

Alternative: From GitHub:

npm install -g github:kdpa-llc/local-skills-mcp

Or clone locally:

git clone https://github.com/kdpa-llc/local-skills-mcp.git
cd local-skills-mcp
npm install  # The prepare script auto-builds

Requirements: Node.js 18+, any MCP-compatible client

Configure MCP Client

Add to your MCP client configuration (e.g., ~/.config/claude-code/mcp.json):

If installed globally:

{
  "mcpServers": {
    "local-skills": {
      "command": "local-skills-mcp"
    }
  }
}

If cloned locally:

{
  "mcpServers": {
    "local-skills": {
      "command": "node",
      "args": ["/absolute/path/to/local-skills-mcp/dist/index.js"]
    }
  }
}

For Cline: Same config in VS Code Settings → "Cline: MCP Settings"

For other MCP clients: Use the same command/args structure according to their MCP server setup.

The server auto-aggregates skills from multiple directories in this priority order (lowest to highest):

1. Package built-in skills (includes self-documenting usage guides)
2. ~/.claude/skills/ - Your global skills
3. ./.claude/skills/ - Project-specific skills
4. ./skills - Default project skills
5. $SKILLS_DIR - Custom directory (if set)

Later directories override earlier ones, allowing you to customize built-in skills.

Create & Use Skills

Option 1: Ask Claude to Create Skills (Recommended)

After installing Local Skills MCP, you can ask Claude to create skills for you:

You: "Create a Python expert skill that helps me write clean, idiomatic Python code"
Claude: [Creates ~/.claude/skills/python-expert/SKILL.md with appropriate content]
        ✅ Created python-expert skill! It's immediately available thanks to hot reload.

You: "Make a skill for reviewing pull requests focusing on security and best practices"
Claude: [Creates the skill with detailed PR review instructions]
        ✅ The pr-reviewer skill is ready to use right away!

Claude will use the built-in skill-creator skill to generate well-structured skills with proper YAML frontmatter, trigger keywords, and best practices.

Option 2: Create Manually

Create ~/.claude/skills/my-skill/SKILL.md:

---
name: my-skill
description: What this skill does and when to use it
---

You are an expert at [domain]. Your task is to [specific task].

Guidelines:

1. Be specific
2. Provide examples
3. Be helpful

Using Skills:

Request any skill in your AI client: "Use the my-skill skill"

The AI auto-discovers available skills and loads them on-demand. All changes apply instantly thanks to hot reload—no restart needed!

📝 SKILL.md Format

Every skill is a SKILL.md file with YAML frontmatter:

---
name: skill-name
description: Brief description of what this skill does and when to use it
---

Your skill instructions in Markdown format...

Required Fields:

• name - Skill identifier (lowercase, hyphens, max 64 chars)
• description - Critical for skill selection (max 200 chars)

Writing Effective Descriptions:

Pattern: [What it does]. Use when [trigger conditions/keywords].

• ✅ Good: "Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes."
• ✅ Good: "Analyze Excel spreadsheets and create pivot tables. Use when working with .xlsx files or tabular data."
• ❌ Poor: "Helps with Excel files"

Claude uses language understanding to decide when to invoke skills—specific trigger keywords help Claude make better decisions.

🎯 Usage

Single Tool: get_skill - loads expert prompt instructions for specific tasks

How it works:

1. AI sees all available skills in the tool description (auto-updated)
2. When you request a skill, AI invokes get_skill
3. Full skill content loads with detailed instructions

Built-in Skills: The package includes three self-documenting skills that explain how to use Local Skills MCP and create new skills. These are available immediately after installation:

• local-skills-mcp-usage - Quick usage guide
• local-skills-mcp-guide - Comprehensive documentation
• skill-creator - Skill authoring best practices

Skill Aggregation: Auto-aggregates from package built-in skills, ~/.claude/skills/, ./.claude/skills/, ./skills, and $SKILLS_DIR (if set). Later directories override duplicates.

Custom Directory: Add via environment variable:

{
  "command": "local-skills-mcp",
  "env": {
    "SKILLS_DIR": "/custom/path/to/skills"
  }
}

Example Skill:

---
name: code-reviewer
description: Reviews code for best practices, bugs, and security. Use when reviewing PRs or analyzing code quality.
---

You are a code reviewer with expertise in software engineering best practices.

Analyze the code for:

1. Correctness and bugs
2. Best practices
3. Performance and security issues
4. Maintainability

Provide specific, actionable feedback.

🆚 Differences from Built-in Skills

❓ FAQ

More: See , ,

🤝 Contributing

Contributions welcome! See for guidelines.

Quick start:

1. Fork the repository
2. Create your feature branch
3. Make your changes and test
4. Commit and push
5. Open a Pull Request

Note: This project follows a .

🔗 Complementary Projects

Optimize your MCP setup with these complementary tools:

MCP Compression Proxy

Aggregate and compress tool descriptions from multiple MCP servers

While Local Skills MCP provides expert prompt instructions, MCP Compression Proxy optimizes your tool descriptions with intelligent LLM-based compression.

Perfect combination:

• Local Skills MCP - Expert skills with lazy loading (~50 tokens/skill)
• MCP Compression Proxy - Compressed tool descriptions (50-80% token reduction)

Together they enable:

• 🎯 Maximum context efficiency across skills AND tools
• 🔗 Access to multiple MCP servers through one connection
• ⚡ Minimal token consumption for large-scale workflows
• 🚀 Professional AI agent setups with hundreds of tools

Learn more about MCP Compression Proxy →

💖 Support This Project

If you find Local Skills MCP useful, please consider supporting its development!

Ways to support:

• ⭐ Star this repository
• 💰 Sponsor via the badges above
• 🐛 Report bugs and suggest features
• 📝

📄 License

MIT License - see file. Copyright © 2025 KDPA

🙏 Acknowledgments

Built with Model Context Protocol SDK • Inspired by Claude Skills