📑 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
• ✨ Simple API - Single tool (get_skill) with dynamic discovery

🚀 Quick Start

1. Install

Requirements: Node.js 18+

Choose one installation method:

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

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

# Or clone and build locally
git clone https://github.com/kdpa-llc/local-skills-mcp.git
cd local-skills-mcp
npm install  # Automatically builds via prepare script

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

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

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

📄 License

MIT License - see LICENSE file. Copyright © 2025 KDPA

🙏 Acknowledgments

Built with Model Context Protocol SDK • Inspired by Claude Skills