@iflow-mcp/kdpa-llc-local-skills-mcp

v0.4.4

Published

3 months ago

Universal MCP server enabling any LLM or AI agent to utilize expert skills from your local filesystem. Reduces context consumption through lazy loading - only skill names visible initially, full content loads on-demand. Works with Claude, Cline, custom ag

Downloads

🎯 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?

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:

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

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

AI sees all available skill names/descriptions (auto-updated, ~50 tokens each)
When you request a skill, AI invokes the get_skill tool
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):

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

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: