local-skills-mcp
This server is a universal MCP server that lets any LLM/AI agent discover and load expert skills from local SKILL.md files.
Auto-aggregates skills from built-in skills,
~/.claude/skills,./.claude/skills,./skills, and optional$SKILLS_DIR, with override priority and hot reload.Provides
get_skillto lazily load full expert instructions by skill name.Provides
validate_skillto check aSKILL.mdagainst name/description/frontmatter rules and return errors/warnings.Provides
evaluate_skillto run an Anthropic skill-creator eval loop measuring trigger reliability, with options for eval set path, model, thresholds, runs, timeout, holdout, workers, and description override.Works with any MCP-compatible client/LLM and runs entirely from the local filesystem.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@local-skills-mcp list my available skills"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π― Local Skills MCP
Enable any LLM or AI agent to utilize expert skills from your local filesystem via MCP
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 |
|
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_skillto load one,validate_skillto check a SKILL.md,evaluate_skillto 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 belowFor 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):
Package built-in skills (self-documenting guides)
~/.claude/skills/- Global skills./.claude/skills/- Project-specific (hidden)./skills- Project-specific (visible)$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 practicesUse 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:
AI sees all available skill names/descriptions (auto-updated, ~50 tokens each)
When you request a skill, AI invokes the
get_skilltoolFull skill content loads on-demand with detailed instructions
Built-in Skills:
Three self-documenting skills are included:
local-skills-mcp-usage- Quick usage guidelocal-skills-mcp-guide- Comprehensive documentationskill-creator- Skill authoring best practices
Skill Directories:
Auto-aggregates from multiple locations (later ones override earlier):
Package built-in skills
~/.claude/skills/- Global skills./.claude/skills/- Project-specific (hidden)./skills- Project-specific (visible)$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:
Fork and clone the repository
Create your feature branch (
git checkout -b feature/amazing-feature)Make changes and add tests
Commit (
git commit -m 'Add amazing feature')Push (
git push origin feature/amazing-feature)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:
π° Sponsor via the badges above
π License
MIT License - see LICENSE file. Copyright Β© 2025 KDPA LLC
π Acknowledgments
Built with Model Context Protocol SDK β’ Inspired by Claude Skills
Made with β€οΈ by KDPA
Available Tools
3 toolsevaluate_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
Scored across 3 tools
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.
All tool names follow a consistent verb_noun pattern (evaluate_skill, get_skill, validate_skill), making the API predictable.
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.
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
Related MCP Connectors
Hosted MCP server for live public-data APIs and Skills for AI agents.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Nifty's MCP server β exposes tasks, projects, messages, and files as tools for AI agents.
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Related MCP Servers
- AlicenseBqualityDmaintenanceProduction-grade MCP server that gives AI agents safe access to your local dev environment: filesystem, databases, processes, and OpenAPI specs.1540 npm4MIT
- AlicenseAqualityDmaintenanceAn MCP server that makes superpowers skills available to any LLM that supports the Model Context Protocol.720MIT
- AlicenseNot gradedqualityCmaintenanceA self-hostable MCP server that turns a folder of skills into callable tools via MCP and REST APIs.3MIT
- AlicenseNot gradedqualityDmaintenanceA complete MCP server that gives LM Studio's Qwen3 (or any local LLM) full coding agent capabilities including 80+ tools for file operations, command execution, git, web search, memory, planning, and a full skills system.14MIT