local-skills-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Package built-in skills directory as base default for all MCP instances
+- Self-documenting capabilities: `local-skills-mcp-usage`, `local-skills-mcp-guide`, and `skill-creator` skills
+- Skills are now available immediately after installation with zero configuration
+
+### Changed
+- Directory aggregation priority updated to include package built-in skills as lowest priority (first in list)
+- Updated documentation to reflect new built-in skills feature
+
+## [0.1.0] - 2025-11-01
+
+### 🎉 First Public Release
+
+This is the initial public release of Local Skills MCP - a proof of concept for enabling any LLM or AI agent to utilize expert skills via the Model Context Protocol.
+
+### Features
+
+#### Universal LLM/Agent Support
+- Works with any MCP-compatible client (Claude Code, Claude Desktop, Cline, Continue.dev, custom agents)
+- Portable skills that work across multiple AI systems
+- LLM-agnostic design (Claude, GPT, Gemini, local models, etc.)
+
+#### Efficient Context Management
+- Lazy loading: only skill names and descriptions initially visible (~50 tokens per skill)
+- Full content loads on-demand, preserving 95%+ of context window
+- Progressive disclosure pattern optimized for context efficiency
+
+#### Powerful Skill Management
+- Standard SKILL.md format with YAML frontmatter
+- Automatic aggregation from multiple directories (~/.claude/skills, ./.claude/skills, ./skills, custom)
+- Dynamic discovery: tool description updates in real-time with available skills
+- Zero configuration: works out-of-the-box with standard locations
+- Ultra-simple API: single `get_skill` tool with built-in discovery
+
+#### Open Source Best Practices
+- Comprehensive contribution guidelines (CONTRIBUTING.md)
+- Code of Conduct (Contributor Covenant v2.0)
+- Security policy and vulnerability reporting (SECURITY.md)
+- Complete documentation and examples
+- GitHub issue and PR templates
+- MIT License
+
+### Technical Implementation
+- TypeScript with Node.js 18+
+- Model Context Protocol SDK integration
+- Version centralized in package.json (single source of truth)
+- Intelligent caching and lazy loading
+- Multi-directory skill aggregation with override support
+
+---
+
+## Pre-Release Development History
+
+The following versions were internal development iterations before the public release:
+
+### [Internal 2.2.0] - 2025-11-01
+- Simplified to single tool (removed list_skills)
+- Generic, utilization-focused tool descriptions
+- Dynamic skill list in get_skill description
+
+### [Internal 2.1.0] - 2025-11-01
+- Enhanced tool descriptions following Claude Skills best practices
+- Added comprehensive documentation on skill description patterns
+- Improved trigger keyword matching
+
+### [Internal 2.0.0] - 2025-10-30
+- Changed to official Claude Skills format (SKILL.md)
+- Added multi-directory skill aggregation
+- Removed custom skill.json format
+
+### [Internal 1.0.0] - 2025-10-29
+- Initial prototype with custom format
+- Four MCP tools with parameter interpolation
+
+---
+
+<!-- Version Links -->
+[0.1.0]: https://github.com/kdpa-llc/local-skills-mcp/releases/tag/v0.1.0
+[unreleased]: https://github.com/kdpa-llc/local-skills-mcp/compare/v0.1.0...HEAD
+
+<!-- Reference Links -->
+[repo]: https://github.com/kdpa-llc/local-skills-mcp
+[issues]: https://github.com/kdpa-llc/local-skills-mcp/issues
+[pulls]: https://github.com/kdpa-llc/local-skills-mcp/pulls
+[releases]: https://github.com/kdpa-llc/local-skills-mcp/releases
+[contributing]: CONTRIBUTING.md
+[security]: SECURITY.md

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 KDPA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,383 @@
+<div align="center">
+
+# 🎯 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]
+[![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)
+
+</div>
+
+---
+
+## 📑 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
+- **🎯 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 18+, 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
+
+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
+```
+
+Then request it in your AI client: `"Use the my-skill skill"`
+
+The AI auto-discovers available skills and loads them on-demand.
+
+## 📝 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 self-documenting skills that explain how to use Local Skills MCP and create new skills. These are available immediately after installation.
+
+**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?**
+A: 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?**
+A: 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?**
+A: Yes! Auto-aggregates from `~/.claude/skills/` along with other directories.
+
+**Q: Do I need to restart after adding skills?**
+A: Yes, currently requires restart. Hot reloading planned for future releases.
+
+**Q: How much context does this consume?**
+A: Minimal! Only names/descriptions initially (~50 tokens/skill). Full content loads on-demand, preserving 95%+ of context.
+
+**Q: Can I use multiple skill directories?**
+A: Yes! Auto-aggregates from package built-in skills, `~/.claude/skills/`, `./.claude/skills/`, `./skills`, and `$SKILLS_DIR`.
+
+**Q: What if I have duplicate skill names?**
+A: 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?**
+A: The package includes three self-documenting skills: `local-skills-mcp-usage` (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)?**
+A: Yes! Works with any MCP-compatible LLM setup. Skills are structured prompts that work with any model.
+
+**Q: Works offline?**
+A: Yes! Runs entirely on local filesystem (though your LLM may need internet depending on the model).
+
+**Q: How to create a good skill?**
+A: Follow [SKILL.md format](#-skillmd-format). Use clear descriptions with trigger keywords, specific instructions, and examples.
+
+**Q: Where can I get help?**
+A: Open an [issue on GitHub][repo-issues].
+
+**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].
+
+## 💖 Support This Project
+
+If you find Local Skills MCP useful, please consider supporting its development!
+
+<div align="center">
+
+[![GitHub Sponsors][sponsor-github-badge]][sponsor-github]
+[![Buy Me A Coffee][sponsor-coffee-badge]][sponsor-coffee]
+[![PayPal][sponsor-paypal-badge]][sponsor-paypal]
+
+</div>
+
+**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][license-file] file. **Copyright © 2025 KDPA**
+
+## 🙏 Acknowledgments
+
+Built with [Model Context Protocol SDK][mcp-sdk] • Inspired by [Claude Skills][claude-skills]
+
+---
+
+<div align="center">
+
+**[⬆ Back to Top](#-local-skills-mcp)**
+
+Made with ❤️ by KDPA
+
+</div>
+
+<!-- Reference Links -->
+<!-- Badges - Top of README -->
+
+[npm-version-badge]: https://img.shields.io/npm/v/local-skills-mcp.svg
+[npm-package]: https://www.npmjs.com/package/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/CD Badges -->
+
+[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
+
+<!-- GitHub Badges -->
+
+[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
+
+<!-- Repository Links -->
+
+[repo]: https://github.com/kdpa-llc/local-skills-mcp
+[pulls]: https://github.com/kdpa-llc/local-skills-mcp/pulls
+
+<!-- Documentation Links -->
+
+[contributing]: CONTRIBUTING.md
+[security]: SECURITY.md
+[changelog]: CHANGELOG.md
+[code-of-conduct]: CODE_OF_CONDUCT.md
+[license-file]: LICENSE
+
+<!-- Sponsorship Links -->
+
+[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
+
+<!-- External Links -->
+
+[mcp-sdk]: https://github.com/modelcontextprotocol/sdk
+[claude-skills]: https://docs.claude.com/en/docs/claude-code/skills

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Get all skills directories to aggregate from.
+ *
+ * Scans for skill directories in the following order (lowest to highest priority):
+ * 1. `<package-root>/skills` - Package built-in skills (self-documenting, always available)
+ * 2. `~/.claude/skills` - Global Claude skills
+ * 3. `{cwd}/.claude/skills` - Project-level Claude skills
+ * 4. `{cwd}/skills` - Default project skills directory
+ * 5. `$SKILLS_DIR` - Custom directory from environment variable
+ *
+ * For duplicate skill names, later directories take precedence. This allows
+ * users to override built-in skills with their own versions.
+ *
+ * @returns Array of directory paths that exist on the filesystem
+ *
+ * @example
+ * ```typescript
+ * const dirs = getAllSkillsDirectories();
+ * console.log(dirs);
+ * // ['/usr/lib/node_modules/local-skills-mcp/skills', '/home/user/.claude/skills', '/home/user/project/skills']
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With SKILLS_DIR environment variable
+ * process.env.SKILLS_DIR = '/custom/skills';
+ * const dirs = getAllSkillsDirectories();
+ * // Returns: [...standard paths..., '/custom/skills']
+ * ```
+ */
+export declare function getAllSkillsDirectories(): string[];
+/**
+ * Main MCP server class for serving skills to AI clients.
+ *
+ * LocalSkillsServer handles MCP protocol communication, manages skill discovery
+ * and loading through SkillLoader, and formats responses for clients.
+ *
+ * @example
+ * ```typescript
+ * const server = new LocalSkillsServer();
+ * await server.run();
+ * // Server is now running and listening on stdio
+ * ```
+ */
+export declare class LocalSkillsServer {
+    private server;
+    private skillLoader;
+    /**
+     * Creates a new LocalSkillsServer instance.
+     *
+     * Initializes the MCP server with capabilities, creates a SkillLoader
+     * for all configured directories, and sets up request handlers.
+     */
+    constructor();
+    private setupErrorHandling;
+    private setupHandlers;
+    private handleGetSkill;
+    /**
+     * Starts the MCP server and connects it to stdio transport.
+     *
+     * This method initializes the stdio transport for MCP communication,
+     * connects the server, and logs startup information including the
+     * list of skill directories being monitored.
+     *
+     * @throws {Error} If the server fails to connect or start
+     *
+     * @example
+     * ```typescript
+     * const server = new LocalSkillsServer();
+     * await server.run();
+     * // Output to stderr:
+     * // Local Skills MCP Server v0.1.0 running on stdio
+     * // Aggregating skills from 3 directories:
+     * //   - /home/user/.claude/skills
+     * //   - /home/user/project/.claude/skills
+     * //   - /home/user/project/skills
+     * ```
+     */
+    run(): Promise<void>;
+    /**
+     * Closes the server and releases all resources.
+     *
+     * This method properly shuts down the MCP server and waits for all
+     * file handles and resources to be released. This is particularly
+     * important on Windows where file handles may take longer to release.
+     *
+     * @example
+     * ```typescript
+     * const server = new LocalSkillsServer();
+     * await server.run();
+     * // ... do work ...
+     * await server.close();
+     * ```
+     */
+    close(): Promise<void>;
+}