Skip to main content
Glama
kdpa-llc

local-skills-mcp

by kdpa-llc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🎯 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

# 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!

GitHub Sponsors Buy Me A Coffee PayPal

Ways to support:

📄 License

MIT License - see LICENSE file. Copyright © 2025 KDPA

🙏 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).

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNoOptional model passed to Claude CLI (defaults to "sonnet")
holdoutNoOptional holdout fraction for run_loop test split (defaults to 0.4, use 0 to disable holdout)
skill_nameYesThe skill directory name to evaluate
num_workersNoOptional evaluator parallel workers (defaults to 1 for stable trigger measurements)
eval_set_pathNoOptional path to eval set JSON. If omitted, common default locations are checked.
max_iterationsNoOptional max optimization iterations
runs_per_queryNoOptional repeats per query (defaults to 1; increase for variance analysis)
timeout_secondsNoOptional timeout per query in seconds (defaults to 120)
trigger_thresholdNoOptional trigger-rate threshold for pass/fail decisions (defaults to 0.5)
description_overrideNoOptional starting description override for what-if optimization without editing SKILL.md first

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must cover behavioral traits. It mentions prerequisites and legacy requirements, but does not disclose side effects, performance impact, or whether the tool modifies any files. This is a moderate disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is a single sentence with a parenthetical, efficiently conveying the primary action and key requirements. Slightly dense, but no superfluous content; could be restructured for better readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 10 parameters (all optional except one), no output schema, and no annotations, the description provides essential prerequisites but lacks details on output behavior and eval loop outcomes. Adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter already has a description. The tool description adds prerequisite context but does not enhance understanding of individual parameters beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Runs Anthropic skill-creator eval loop for a skill', specifying the exact action and target resource. This distinguishes it from sibling tools get_skill and validate_skill, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description lists prerequisites (Python, Claude CLI auth, eval set JSON) which guide usage. It implies usage for evaluation, though lacks explicit when-to-use vs siblings or when-not-to-use scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
skill_nameYesThe name of the skill to retrieve (e.g., "code-reviewer", "test-generator")

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It implies a read operation loading instructions but does not disclose behavioral traits such as idempotency, permission requirements, or potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a general purpose paragraph followed by a list of specific skills. It is front-loaded with the main action but slightly longer than necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and one parameter, the description adequately covers what the tool returns (detailed instructions) and how to call it, including examples. Lacks info on error cases but sufficient for a simple retrieval.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with a single string parameter described. The description adds value by listing available skill names, going beyond the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it loads specialized expert prompt instructions and transforms capabilities for specific tasks, distinguishing it from siblings evaluate_skill and validate_skill which assess skills.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use guidance ('when you need focused expertise') and lists specific skill examples, but does not explicitly state when not to use or contrast with alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validate_skillB

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

ParametersJSON Schema
NameRequiredDescriptionDefault
skill_nameYesThe skill directory name to validate

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must carry the full burden. It does not disclose whether the tool is read-only or has side effects, what happens if the file is missing, or any required permissions. The description only states it validates and returns errors/warnings, lacking critical behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded and to the point. It contains no unnecessary words or filler, and every part of the sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is fairly complete. It explains the function and the type of output (errors/warnings). However, it could mention whether the file must exist or what rules are checked, but these are minor omissions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'skill_name' has 100% schema coverage, and its description in the schema matches the tool description. The tool description adds no additional meaning beyond what the schema already provides. Baseline 3 applies since schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool validates a SKILL.md file against specific rules and returns errors/warnings. The verb 'validates' and resource 'SKILL.md' are precise, and the output ('errors + warnings') is specified. It distinguishes from siblings like 'evaluate_skill' and 'get_skill' by focusing on validation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like evaluate_skill or get_skill. There is no mention of prerequisites, context, or when not to use it. The description only states what it does, leaving the agent to infer usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.4.4
    • First observedevaluate_skill
    • First observedget_skill
    • First observedvalidate_skill
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers