Local Skills MCP

---

📑 Table of Contents

• What is Local Skills MCP?
• ✨ Features
• 🚀 Quick Start
• 📝 SKILL.md Format
• 🎯 Usage
• ❓ 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. Write skills once, use them 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. Context-efficient lazy loading—only skill names/descriptions load initially (~50 tokens/skill), full content on-demand.

🆚 Why Use Local Skills MCP?

✨ 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, Ollama, etc.)
• ⚡ Context Efficient - Lazy loading (~50 tokens/skill for names/descriptions, full content loads on-demand)
• 🔥 Hot Reload - Changes apply instantly without restart (new skills, edits, deletions)
• 🎯 Multi-Source - Auto-aggregates from built-in skills, ~/.claude/skills, ./.claude/skills, ./skills, custom paths
• 📦 Zero Config - Works out-of-the-box with standard locations
• ✨ Focused API - Three tools: get_skill to load one, validate_skill to check a SKILL.md, evaluate_skill to measure how reliably it triggers

🚀 Quick Start

1. Install

Requirements: Node.js 22+

Choose one installation method:

# From npm (recommended)
npm install -g local-skills-mcp

# Or clone and build locally
git clone https://github.com/kdpa-llc/local-skills-mcp.git
cd local-skills-mcp
npx --yes npm@11 ci  # Use the same npm major as CI
npm run build  # Creates dist/index.js for the local MCP client configuration below

For source builds, use a current Node.js 22 or 24 release. The build step is required: the prepare script only installs Git hooks.

2. Configure MCP Client

Add to your MCP client configuration:

For Claude Code/Desktop (~/.config/claude-code/mcp.json or ~/Library/Application Support/Claude/claude_desktop_config.json):

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

For Cline: VS Code Settings → "Cline: MCP Settings" (same JSON structure)

For other MCP clients: Use the same command/args structure

If cloned locally (not installed globally), use:

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

Skill Discovery:

The server auto-aggregates skills from multiple directories (priority: low to high):

1. Package built-in skills (self-documenting guides)
2. ~/.claude/skills/ - Global skills
3. ./.claude/skills/ - Project-specific (hidden)
4. ./skills - Project-specific (visible)
5. $SKILLS_DIR - Custom path (if env var set)

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

3. Create & Use Skills

Create Skills (Option 1: Ask AI - Recommended)

Simply ask your AI to create skills:

"Create a Python expert skill for clean, idiomatic code"
"Make a PR review skill focusing on security and best practices"

The AI uses the built-in skill-creator skill to generate well-structured skills with proper YAML frontmatter and trigger keywords.

Create Skills (Option 2: Manual)

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 and actionable
2. Provide examples
3. Include best practices

Use Skills

Request any skill: "Use the my-skill skill"

Skills are auto-discovered and load on-demand. All changes apply instantly with 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:

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

✅ Good Examples:

• "Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes."
• "Analyzes Excel spreadsheets and creates pivot tables. Use when working with .xlsx files or tabular data."

❌ Poor Example:

• "Helps with Excel files"

Specific trigger keywords help the AI make better decisions when selecting skills.

🎯 Usage

How It Works:

1. AI sees all available skill names/descriptions (auto-updated, ~50 tokens each)
2. When you request a skill, AI invokes the get_skill tool
3. Full skill content loads on-demand with detailed instructions

Built-in Skills:

Three self-documenting skills are included:

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

Skill Directories:

Auto-aggregates from multiple locations (later ones override earlier):

1. Package built-in skills
2. ~/.claude/skills/ - Global skills
3. ./.claude/skills/ - Project-specific (hidden)
4. ./skills - Project-specific (visible)
5. $SKILLS_DIR - Custom path (optional)

Custom Directory:

Configure via environment variable in your MCP client config:

{
  "mcpServers": {
    "local-skills": {
      "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 and maintainability
3. Performance and security issues

Provide specific, actionable feedback with examples.

❓ FAQ

Q: What MCP clients are supported?

Any MCP-compatible client: Claude Code, Claude Desktop, Cline, Continue.dev, or custom agents.

Q: Can I use existing Claude skills from ~/.claude/skills/?

Yes! The server automatically aggregates skills from ~/.claude/skills/ along with other directories.

Q: Do I need to restart after adding or editing skills?

No! Hot reload is fully supported. All changes (new skills, edits, deletions) apply instantly without restarting the MCP server.

Q: How do I override a built-in skill?

Create a skill with the same name in a higher-priority directory. Priority order: package built-in → ~/.claude/skills → ./.claude/skills → ./skills → $SKILLS_DIR.

Q: Does this work with local LLMs (Ollama, LM Studio)?

Yes! Works with any MCP-compatible client and LLM. Skills are structured prompts that work with any model.

Q: Does this work offline?

Yes! The MCP server runs entirely on your local filesystem (though your LLM may require internet depending on the provider).

Q: How do I create effective skills?

See the SKILL.md format section. Use clear descriptions with trigger keywords, specific instructions, and examples. Or ask your AI to create skills using the built-in skill-creator skill.

Q: Where can I get help?

Open an issue on GitHub or check the built-in local-skills-mcp-guide skill.

More: See CONTRIBUTING.md, SECURITY.md, CHANGELOG.md

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for detailed guidelines.

Quick start:

1. Fork and clone the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make changes and add tests
4. Commit (git commit -m 'Add amazing feature')
5. Push (git push origin feature/amazing-feature)
6. Open a Pull Request

This project follows a Code of Conduct.

🔗 Complementary Projects

Optimize your MCP setup with these complementary tools:

MCP Compression Proxy

Discover and access tools from multiple MCP servers

While Local Skills MCP provides reusable prompt instructions, MCP Compression Proxy connects multiple MCP servers through one gateway. Its CLI loads selected tool schemas on demand; its native MCP mode shortens descriptions while keeping input schemas visible.

Use them together:

• Local Skills MCP - Expert skills with lazy loading (~50 tokens/skill)
• MCP Compression Proxy - Progressive tool discovery and description compression

Context savings depend on your tool schemas, client mode, and task. Measure the complete tool definitions used by your own setup.

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
• 📝 Contribute code or documentation

📄 License

MIT License - see LICENSE file. Copyright © 2025 KDPA

🙏 Acknowledgments

Built with Model Context Protocol SDK • Inspired by Claude Skills

---