Skip to main content
Glama

🎯 Local Skills MCP

Enable any LLM or AI agent to utilize expert skills from your local filesystem via MCP

npm version npm downloads npm types License: MIT Node MCP

CI codecov CodeQL

GitHub Stars GitHub Forks GitHub Issues GitHub Last Commit PRs Welcome

Quick Start β€’ Features β€’ Usage β€’ FAQ β€’ Contributing


πŸ“‘ Table of Contents


Related MCP server: superpowers-mcp

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?

Feature

Local Skills MCP

Built-in Claude Skills

Portability

Any MCP client

Claude Code only

Storage

Multiple directories aggregated

~/.claude/skills/ only

Invocation

Explicit via MCP tool

Auto-invoked by Claude

Context Usage

Lazy loading (names only)

All skills in context

✨ 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

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!

GitHub Sponsors Buy Me A Coffee PayPal

Ways to support:

πŸ“„ License

MIT License - see LICENSE file. Copyright Β© 2025 KDPA LLC

πŸ™ Acknowledgments

Built with Model Context Protocol SDK β€’ Inspired by Claude Skills


⬆ Back to Top

Made with ❀️ by KDPA

Available Tools

3 tools
evaluate_skillA

Runs Anthropic skill-creator eval loop for a skill (requires Python, Claude CLI auth, and an eval set JSON; legacy layouts may also require ANTHROPIC_API_KEY + anthropic package).

Inputs: skill_name (required), model, holdout, num_workers, +6 more.

get_skillA

Loads specialized expert prompt instructions that transform your capabilities for specific tasks. Each skill provides comprehensive guidance, proven methodologies, and domain-specific best practices. Use when you need focused expertise, systematic approaches, or professional standards for any task that would benefit from specialized knowledge. Invoke with the skill name to receive detailed instructions that enhance your problem-solving approach with structured, expert-level guidance.

Available skills:

  • local-skills-mcp-guide: Repository implementation guide for the local-skills-mcp codebase. Use when asked: how src/index.ts and src/skill-loader.ts work together; where MCP tool handlers are defined and registered; how getAllSkillsDirectories priority and override behavior works; how local-skills-mcp discovers skills and merges metadata across directories; where validate_skill and evaluate_skill are implemented in this repository; or how integration tests are structured in this local-skills-mcp project.

  • local-skills-mcp-usage: Operational guide for using Local Skills MCP in day-to-day projects. Use when asked: where skills should live (~/.claude/skills, ./.claude/skills, ./skills, SKILLS_DIR); directory precedence and override rules; how to configure local-skills-mcp in Claude Code mcp.json; fastest way to create a new skill folder and make it discoverable; how to add project skills to git so the team gets them; or how Local Skills MCP hot-reloads skill edits without restarting.

  • skill-creator: Use this skill when building, writing, reviewing, or fixing a SKILL.md file for a new or existing skill. Covers choosing skill names, writing and correcting YAML frontmatter (name and description fields), crafting effective 'Use when' trigger phrases, structuring skill body instructions, improving an existing skill's routing quality with better trigger keywords, and interpreting or evaluating a skill description against an eval set using validate_skill or evaluate_skill.

Inputs: skill_name (required).

validate_skillB

Validates a SKILL.md file against name/description/frontmatter rules and returns errors + warnings.

Inputs: skill_name (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct purpose: validate_skill validates SKILL.md files, get_skill loads skill instructions, evaluate_skill runs an evaluation loop. No overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (evaluate_skill, get_skill, validate_skill), making the API predictable.

    Tool Count4/5

    Three tools is slightly minimal for a skill management system, but covers core operations. A few more (e.g., create_skill, list_skills) could improve completeness without being excessive.

    Completeness2/5

    Missing basic lifecycle operations: no tool to create, update, or delete skills. The get_skill tool lists available skills but this is atypical. Validation and evaluation alone are insufficient for managing a skill inventory.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers