# 🎯 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) - [❓ 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. 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 - **✨ Simple API** - Single tool (`get_skill`) with dynamic discovery ## πŸš€ Quick Start ### 1. Install **Requirements:** Node.js 18+ Choose one installation method: ```bash # 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`): ```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: ```json { "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`: ```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 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: ```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:** 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: ```json { "mcpServers": { "local-skills": { "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 and maintainability 3. Performance and security issues Provide specific, actionable feedback with examples. ``` ## ❓ FAQ
Q: What MCP clients are supported?

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

Q: Can I use existing Claude skills from ~/.claude/skills/?

Yes! The server automatically aggregates skills from ~/.claude/skills/ along with other directories.

Q: Do I need to restart after adding or editing skills?

No! Hot reload is fully supported. All changes (new skills, edits, deletions) apply instantly without restarting the MCP server.

Q: How do I override a built-in skill?

Create a skill with the same name in a higher-priority directory. Priority order: package built-in β†’ ~/.claude/skills β†’ ./.claude/skills β†’ ./skills β†’ $SKILLS_DIR.

Q: Does this work with local LLMs (Ollama, LM Studio)?

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

Q: Does this work offline?

Yes! The MCP server runs entirely on your local filesystem (though your LLM may require internet depending on the provider).

Q: How do I create effective skills?

See the SKILL.md format section. Use clear descriptions with trigger keywords, specific instructions, and examples. Or ask your AI to create skills using the built-in skill-creator skill.

Q: Where can I get help?

Open an issue on GitHub or check the built-in local-skills-mcp-guide skill.

**More:** See [CONTRIBUTING.md][contributing], [SECURITY.md][security], [CHANGELOG.md][changelog] ## 🀝 Contributing Contributions welcome! See [CONTRIBUTING.md][contributing] 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][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%3D18.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