# 🎯 Local Skills MCP **Enable any LLM or AI agent to utilize expert skills from your local filesystem via MCP** [![npm version][npm-version-badge]][npm-package] [![npm downloads][npm-downloads-badge]][npm-package] [![npm types][npm-types-badge]][npm-package] [![License: MIT][license-badge]][license] [![Node][node-badge]][nodejs] [![MCP][mcp-badge]][mcp-protocol] [![CI][ci-badge]][ci-workflow] [![codecov][codecov-badge]][codecov] [![CodeQL][codeql-badge]][codeql-workflow] [![GitHub Stars][stars-badge]][stargazers] [![GitHub Forks][forks-badge]][network] [![GitHub Issues][issues-badge]][repo-issues] [![GitHub Last Commit][commit-badge]][commits] [![PRs Welcome][prs-badge]][contributing] [Quick Start](#-quick-start) β€’ [Features](#-features) β€’ [Usage](#-usage) β€’ [FAQ](#-faq) β€’ [Contributing](#-contributing)
--- ## πŸ“‘ Table of Contents - [What is Local Skills MCP?](#what-is-local-skills-mcp) - [✨ Features](#-features) - [πŸš€ Quick Start](#-quick-start) - [πŸ“ SKILL.md Format](#-skillmd-format) - [🎯 Usage](#-usage) - [πŸ†š Differences from Built-in Skills](#-differences-from-built-in-skills) - [❓ FAQ](#-faq) - [🀝 Contributing](#-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. Your skills become portable, reusable prompt libraries that work 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. Lazy loading preserves contextβ€”only skill names and descriptions load initially; full content loads on-demand. ## ✨ 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, local models) - **⚑ Context Efficient** - Lazy loading: only skill names/descriptions load initially (~50 tokens/skill), full content on-demand - **πŸ”₯ Hot Reload** - All changes apply instantly (new skills, edits, deletions) without restart - **🎯 Multi-Source** - Auto-aggregates from package built-in skills, `~/.claude/skills`, `./.claude/skills`, `./skills`, and custom paths - **πŸ“¦ Zero Config** - Works out-of-the-box with standard skill locations - **✨ Ultra Simple** - Single tool (`get_skill`) with dynamic skill discovery ## πŸš€ Quick Start ### Install **From npm (recommended):** ```bash npm install -g local-skills-mcp ``` **Alternative: From GitHub:** ```bash npm install -g github:kdpa-llc/local-skills-mcp ``` **Or clone locally:** ```bash git clone https://github.com/kdpa-llc/local-skills-mcp.git cd local-skills-mcp npm install # The prepare script auto-builds ``` **Requirements:** Node.js 20+, any MCP-compatible client ### Configure MCP Client Add to your MCP client configuration (e.g., `~/.config/claude-code/mcp.json`): **If installed globally:** ```json { "mcpServers": { "local-skills": { "command": "local-skills-mcp" } } } ``` **If cloned locally:** ```json { "mcpServers": { "local-skills": { "command": "node", "args": ["/absolute/path/to/local-skills-mcp/dist/index.js"] } } } ``` **For Cline:** Same config in VS Code Settings β†’ "Cline: MCP Settings" **For other MCP clients:** Use the same command/args structure according to their MCP server setup. The server auto-aggregates skills from multiple directories in this priority order (lowest to highest): 1. Package built-in skills (includes self-documenting usage guides) 2. `~/.claude/skills/` - Your global skills 3. `./.claude/skills/` - Project-specific skills 4. `./skills` - Default project skills 5. `$SKILLS_DIR` - Custom directory (if set) Later directories override earlier ones, allowing you to customize built-in skills. ### Create & Use Skills **Option 1: Ask Claude to Create Skills (Recommended)** After installing Local Skills MCP, you can ask Claude to create skills for you: ``` You: "Create a Python expert skill that helps me write clean, idiomatic Python code" Claude: [Creates ~/.claude/skills/python-expert/SKILL.md with appropriate content] βœ… Created python-expert skill! It's immediately available thanks to hot reload. ``` ``` You: "Make a skill for reviewing pull requests focusing on security and best practices" Claude: [Creates the skill with detailed PR review instructions] βœ… The pr-reviewer skill is ready to use right away! ``` Claude will use the built-in `skill-creator` skill to generate well-structured skills with proper YAML frontmatter, trigger keywords, and best practices. **Option 2: Create Manually** Create `~/.claude/skills/my-skill/SKILL.md`: ```markdown --- 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 2. Provide examples 3. Be helpful ``` **Using Skills:** Request any skill in your AI client: `"Use the my-skill skill"` The AI auto-discovers available skills and loads them on-demand. **All changes apply instantly** thanks to hot reloadβ€”no restart needed! ## πŸ“ SKILL.md Format Every skill is a `SKILL.md` file with YAML frontmatter: ```markdown --- 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:** Pattern: `[What it does]. Use when [trigger conditions/keywords].` - βœ… **Good**: "Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes." - βœ… **Good**: "Analyze Excel spreadsheets and create pivot tables. Use when working with .xlsx files or tabular data." - ❌ **Poor**: "Helps with Excel files" Claude uses language understanding to decide when to invoke skillsβ€”specific trigger keywords help Claude make better decisions. ## 🎯 Usage **Single Tool:** `get_skill` - loads expert prompt instructions for specific tasks **How it works:** 1. AI sees all available skills in the tool description (auto-updated) 2. When you request a skill, AI invokes `get_skill` 3. Full skill content loads with detailed instructions **Built-in Skills:** The package includes three self-documenting skills that explain how to use Local Skills MCP and create new skills. These are available immediately after installation: - `local-skills-mcp-usage` - Quick usage guide - `local-skills-mcp-guide` - Comprehensive documentation - `skill-creator` - Skill authoring best practices **Skill Aggregation:** Auto-aggregates from package built-in skills, `~/.claude/skills/`, `./.claude/skills/`, `./skills`, and `$SKILLS_DIR` (if set). Later directories override duplicates. **Custom Directory:** Add via environment variable: ```json { "command": "local-skills-mcp", "env": { "SKILLS_DIR": "/custom/path/to/skills" } } ``` **Example Skill:** ```markdown --- 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 3. Performance and security issues 4. Maintainability Provide specific, actionable feedback. ``` ## πŸ†š Differences from Built-in Skills | 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 | ## ❓ FAQ
Q: What MCP clients are supported?

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

Q: How is this different from Claude's built-in skills?

Works with any MCP client (not just Claude), aggregates from multiple directories, explicit invocation control, and better context efficiency via lazy loading.

Q: Can I use existing Claude skills?

Yes! Auto-aggregates from ~/.claude/skills/ along with other directories.

Q: Do I need to restart after adding skills?

No! Full hot reload is supported. All changes (new skills, content edits, deletions) apply immediately without restart. Skills are discovered dynamically on every tool list request.

Q: How much context does this consume?

Minimal! Only names/descriptions initially (~50 tokens/skill). Full content loads on-demand, preserving 95%+ of context.

Q: Can I use multiple skill directories?

Yes! Auto-aggregates from package built-in skills, ~/.claude/skills/, ./.claude/skills/, ./skills, and $SKILLS_DIR.

Q: What if I have duplicate skill names?

Later directories override earlier ones: package built-in β†’ ~/.claude/skills β†’ ./.claude/skills β†’ ./skills β†’ $SKILLS_DIR. This lets you customize built-in skills.

Q: What built-in skills are included?

The package includes three self-documenting skills: local-skills-mcp-usage (quick usage guide), local-skills-mcp-guide (comprehensive documentation), and skill-creator (skill authoring guide). These are available immediately after installation.

Q: Works with local LLMs (Ollama, LM Studio)?

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

Q: Works offline?

Yes! Runs entirely on local filesystem (though your LLM may need internet depending on the model).

Q: How to create a good skill?

Follow SKILL.md format. Use clear descriptions with trigger keywords, specific instructions, and examples.

Q: Where can I get help?

Open an issue on GitHub.

**More:** See [CONTRIBUTING.md][contributing], [SECURITY.md][security], [CHANGELOG.md][changelog] ## 🀝 Contributing Contributions welcome! See [CONTRIBUTING.md][contributing] for guidelines. Quick start: 1. Fork the repository 2. Create your feature branch 3. Make your changes and test 4. Commit and push 5. Open a Pull Request Note: This project follows a [Code of Conduct][code-of-conduct]. ## πŸ”— Complementary Projects **Optimize your MCP setup with these complementary tools:** ### [MCP Compression Proxy][mcp-tool-aggregator] **Aggregate and compress tool descriptions from multiple MCP servers** While Local Skills MCP provides expert prompt instructions, [MCP Compression Proxy][mcp-tool-aggregator] 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 β†’][mcp-tool-aggregator] ## πŸ’– Support This Project If you find Local Skills MCP useful, please consider supporting its development!
[![GitHub Sponsors][sponsor-github-badge]][sponsor-github] [![Buy Me A Coffee][sponsor-coffee-badge]][sponsor-coffee] [![PayPal][sponsor-paypal-badge]][sponsor-paypal]
**Ways to support:** - ⭐ [Star this repository][stargazers] - πŸ’° Sponsor via the badges above - πŸ› [Report bugs and suggest features][repo-issues] - πŸ“ [Contribute code or documentation][contributing] ## πŸ“„ License MIT License - see [LICENSE][license-file] file. **Copyright Β© 2025 KDPA** ## πŸ™ Acknowledgments Built with [Model Context Protocol SDK][mcp-sdk] β€’ Inspired by [Claude Skills][claude-skills] ---
**[⬆ Back to Top](#-local-skills-mcp)** Made with ❀️ by KDPA
[npm-version-badge]: https://img.shields.io/npm/v/local-skills-mcp.svg [npm-package]: https://www.npmjs.com/package/local-skills-mcp [npm-downloads-badge]: https://img.shields.io/npm/dm/local-skills-mcp [npm-types-badge]: https://img.shields.io/npm/types/local-skills-mcp [license-badge]: https://img.shields.io/badge/License-MIT-yellow.svg [license]: https://opensource.org/licenses/MIT [node-badge]: https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg [nodejs]: https://nodejs.org/ [mcp-badge]: https://img.shields.io/badge/MCP-Compatible-purple.svg [mcp-protocol]: https://modelcontextprotocol.io/ [ci-badge]: https://github.com/kdpa-llc/local-skills-mcp/actions/workflows/ci.yml/badge.svg [ci-workflow]: https://github.com/kdpa-llc/local-skills-mcp/actions/workflows/ci.yml [codecov-badge]: https://codecov.io/gh/kdpa-llc/local-skills-mcp/branch/main/graph/badge.svg [codecov]: https://codecov.io/gh/kdpa-llc/local-skills-mcp [codeql-badge]: https://github.com/kdpa-llc/local-skills-mcp/actions/workflows/codeql.yml/badge.svg [codeql-workflow]: https://github.com/kdpa-llc/local-skills-mcp/actions/workflows/codeql.yml [stars-badge]: https://img.shields.io/github/stars/kdpa-llc/local-skills-mcp?style=social [stargazers]: https://github.com/kdpa-llc/local-skills-mcp/stargazers [forks-badge]: https://img.shields.io/github/forks/kdpa-llc/local-skills-mcp?style=social [network]: https://github.com/kdpa-llc/local-skills-mcp/network/members [issues-badge]: https://img.shields.io/github/issues/kdpa-llc/local-skills-mcp [repo-issues]: https://github.com/kdpa-llc/local-skills-mcp/issues [commit-badge]: https://img.shields.io/github/last-commit/kdpa-llc/local-skills-mcp [commits]: https://github.com/kdpa-llc/local-skills-mcp/commits/main [prs-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg [repo]: https://github.com/kdpa-llc/local-skills-mcp [pulls]: https://github.com/kdpa-llc/local-skills-mcp/pulls [contributing]: CONTRIBUTING.md [security]: SECURITY.md [changelog]: CHANGELOG.md [code-of-conduct]: CODE_OF_CONDUCT.md [license-file]: LICENSE [sponsor-github-badge]: https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?logo=github [sponsor-github]: https://github.com/sponsors/moscaverd [sponsor-coffee-badge]: https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?logo=buy-me-a-coffee [sponsor-coffee]: https://buymeacoffee.com/moscaverd [sponsor-paypal-badge]: https://img.shields.io/badge/PayPal-donate-blue?logo=paypal [sponsor-paypal]: https://paypal.me/moscaverd [mcp-sdk]: https://github.com/modelcontextprotocol/sdk [claude-skills]: https://docs.claude.com/en/docs/claude-code/skills [mcp-tool-aggregator]: https://github.com/kdpa-llc/mcp-compression-proxy