local-skills-mcp

🎯 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

• What is Local Skills MCP?
• ✨ Features
• 🚀 Quick Start
• 📝 SKILL.md Format
• 🎯 Usage
• 🆚 Differences from Built-in Skills
• ❓ FAQ
• 🤝 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):

npm install -g local-skills-mcp

Alternative: From GitHub:

npm install -g github:kdpa-llc/local-skills-mcp

Or clone locally:

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 18+, any MCP-compatible client

Configure MCP Client

Add to your MCP client configuration (e.g., ~/.config/claude-code/mcp.json):

If installed globally:

{
  "mcpServers": {
    "local-skills": {
      "command": "local-skills-mcp"
    }
  }
}

If cloned locally:

{
  "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):

• Package built-in skills (includes self-documenting usage guides)
• ~/.claude/skills/ - Your global skills
• ./.claude/skills/ - Project-specific skills
• ./skills - Default project skills
• $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:

---
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:

---
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:

• AI sees all available skills in the tool description (auto-updated)
• When you request a skill, AI invokes get_skill
• 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:

{
  "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
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, SECURITY.md, CHANGELOG.md

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Quick start:

• Fork the repository
• Create your feature branch
• Make your changes and test
• Commit and push
• Open a Pull Request

Note: This project follows a Code of Conduct.

💖 Support This Project

If you find Local Skills MCP useful, please consider supporting its development!

Ways to support:

• ⭐ Star this repository
• 💰 Sponsor via the badges above
• 🐛 Report bugs and suggest features
• 📝 Contribute code or documentation

📄 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