local-skills-mcp 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -2,12 +2,81 @@
 
 All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## 0.5.0 (2026-08-20)
+
+- fix: align evaluate_skill with anthropics run loop ([83f1357](https://github.com/kdpa-llc/local-skills-mcp/commit/83f1357))
+- fix: correct anthropics skills submodule url ([0c5cb51](https://github.com/kdpa-llc/local-skills-mcp/commit/0c5cb51))
+- fix: cross-platform test paths and insecure temp file usage ([12de1a8](https://github.com/kdpa-llc/local-skills-mcp/commit/12de1a8))
+- fix: exclude vendored submodule from prettier ([bbf3823](https://github.com/kdpa-llc/local-skills-mcp/commit/bbf3823)), closes [#95](https://github.com/kdpa-llc/local-skills-mcp/issues/95)
+- fix: re-add @semantic-release/git plugin and sync version to 0.4.4 ([5abe4ea](https://github.com/kdpa-llc/local-skills-mcp/commit/5abe4ea))
+- fix: re-pin anthropic-skills submodule to an existing commit ([9d5ce79](https://github.com/kdpa-llc/local-skills-mcp/commit/9d5ce79)), closes [#95](https://github.com/kdpa-llc/local-skills-mcp/issues/95)
+- fix: re-pin dead anthropic-skills submodule, unblocking clones and Dependabot (#96) ([39d37f6](https://github.com/kdpa-llc/local-skills-mcp/commit/39d37f6)), closes [#96](https://github.com/kdpa-llc/local-skills-mcp/issues/96)
+- fix: reject skill-name path traversal and resolve skills lazily ([9bfd144](https://github.com/kdpa-llc/local-skills-mcp/commit/9bfd144))
+- fix: reliable eval mechanism and sharper skill descriptions ([c7e1c6f](https://github.com/kdpa-llc/local-skills-mcp/commit/c7e1c6f))
+- fix: restore curated eval sets and separate them from run artifacts ([5ba769f](https://github.com/kdpa-llc/local-skills-mcp/commit/5ba769f)), closes [#94](https://github.com/kdpa-llc/local-skills-mcp/issues/94)
+- fix: return the skill name that round-trips and confine lookups to the registry ([64fd43e](https://github.com/kdpa-llc/local-skills-mcp/commit/64fd43e))
+- fix: skill_name traversal, get_skill name round-trip, and repo health (#95) ([ad21e60](https://github.com/kdpa-llc/local-skills-mcp/commit/ad21e60)), closes [#95](https://github.com/kdpa-llc/local-skills-mcp/issues/95)
+- fix: support claude oauth auth for evaluate_skill ([da03639](https://github.com/kdpa-llc/local-skills-mcp/commit/da03639))
+- fix: update prettier formatting for CI compatibility ([3798aaf](https://github.com/kdpa-llc/local-skills-mcp/commit/3798aaf))
+- fix: use path.join in test assertions for Windows compatibility ([97e319e](https://github.com/kdpa-llc/local-skills-mcp/commit/97e319e))
+- fix: use RELEASE_TOKEN to bypass repository rulesets ([f0a6ab9](https://github.com/kdpa-llc/local-skills-mcp/commit/f0a6ab9))
+- fix: use RELEASE_TOKEN to bypass repository rulesets (#57) ([c6f9d41](https://github.com/kdpa-llc/local-skills-mcp/commit/c6f9d41)), closes [#57](https://github.com/kdpa-llc/local-skills-mcp/issues/57)
+- fix(deps-dev): upgrade eslint to 10, lint-staged to 17, commitlint to 21 ([a225665](https://github.com/kdpa-llc/local-skills-mcp/commit/a225665))
+- fix(deps-dev): upgrade vitest to 4.x and fix the test isolation it exposed ([5876c65](https://github.com/kdpa-llc/local-skills-mcp/commit/5876c65)), closes [#95](https://github.com/kdpa-llc/local-skills-mcp/issues/95)
+- fix(deps): bring dependencies to latest, clearing all production advisories (#97) ([8e1c24f](https://github.com/kdpa-llc/local-skills-mcp/commit/8e1c24f)), closes [#97](https://github.com/kdpa-llc/local-skills-mcp/issues/97)
+- fix(deps): bump @modelcontextprotocol/sdk to 1.30.0 and yaml to 2.9.0 ([573540d](https://github.com/kdpa-llc/local-skills-mcp/commit/573540d))
+- fix(deps): pin conventionalcommits preset to a writer-8 compatible major ([f1a4eee](https://github.com/kdpa-llc/local-skills-mcp/commit/f1a4eee))
+- fix(deps): pin conventionalcommits preset to a writer-8 compatible major (#105) ([120b00f](https://github.com/kdpa-llc/local-skills-mcp/commit/120b00f)), closes [#105](https://github.com/kdpa-llc/local-skills-mcp/issues/105)
+- ci: allow the release workflow to be triggered manually ([c1cf0df](https://github.com/kdpa-llc/local-skills-mcp/commit/c1cf0df))
+- ci: allow the release workflow to be triggered manually (#104) ([b208604](https://github.com/kdpa-llc/local-skills-mcp/commit/b208604)), closes [#104](https://github.com/kdpa-llc/local-skills-mcp/issues/104)
+- ci: fail the release with a readable error when RELEASE_TOKEN is bad ([d7232a3](https://github.com/kdpa-llc/local-skills-mcp/commit/d7232a3))
+- ci: let production dependency bumps trigger a release ([8b1d63a](https://github.com/kdpa-llc/local-skills-mcp/commit/8b1d63a))
+- ci: run CI, CodeQL and dependency review on every pull request ([ea91535](https://github.com/kdpa-llc/local-skills-mcp/commit/ea91535)), closes [#97](https://github.com/kdpa-llc/local-skills-mcp/issues/97) [#98](https://github.com/kdpa-llc/local-skills-mcp/issues/98)
+- ci: set npm registry in release workflow so publishing can authenticate (#103) ([b57d60d](https://github.com/kdpa-llc/local-skills-mcp/commit/b57d60d)), closes [#103](https://github.com/kdpa-llc/local-skills-mcp/issues/103) [#99](https://github.com/kdpa-llc/local-skills-mcp/issues/99)
+- ci: set the npm registry in the release workflow ([3c6ccd9](https://github.com/kdpa-llc/local-skills-mcp/commit/3c6ccd9))
+- ci(deps): bump actions/checkout from 5 to 6 ([42ca7ac](https://github.com/kdpa-llc/local-skills-mcp/commit/42ca7ac))
+- ci(deps): bump actions/first-interaction from 1 to 3 ([3659f5b](https://github.com/kdpa-llc/local-skills-mcp/commit/3659f5b))
+- ci(deps): bump actions/github-script from 7 to 8 ([a805d4a](https://github.com/kdpa-llc/local-skills-mcp/commit/a805d4a))
+- ci(deps): bump actions/labeler from 5 to 6 ([7c3f8fa](https://github.com/kdpa-llc/local-skills-mcp/commit/7c3f8fa))
+- ci(deps): bump actions/stale from 9 to 10 ([88d3cf4](https://github.com/kdpa-llc/local-skills-mcp/commit/88d3cf4))
+- docs: add MCP Tool Aggregator as complementary project ([900ec1a](https://github.com/kdpa-llc/local-skills-mcp/commit/900ec1a))
+- docs: backfill changelog entries for 0.4.3 and 0.4.4 ([34bca80](https://github.com/kdpa-llc/local-skills-mcp/commit/34bca80))
+- docs: correct false claims in the bundled skills ([71d1465](https://github.com/kdpa-llc/local-skills-mcp/commit/71d1465))
+- docs: correct false security claims and a stale diagram in ARCHITECTURE ([78dc08f](https://github.com/kdpa-llc/local-skills-mcp/commit/78dc08f))
+- docs: document the Skill identity split and injectable skills directories ([8556000](https://github.com/kdpa-llc/local-skills-mcp/commit/8556000))
+- docs: drop phantom cache from the dev guide and unswap the skill scripts ([9d13955](https://github.com/kdpa-llc/local-skills-mcp/commit/9d13955)), closes [#100](https://github.com/kdpa-llc/local-skills-mcp/issues/100) [#101](https://github.com/kdpa-llc/local-skills-mcp/issues/101)
+- docs: fix nonexistent function and false caching claims in bundled skills (#101) ([160e2d3](https://github.com/kdpa-llc/local-skills-mcp/commit/160e2d3)), closes [#101](https://github.com/kdpa-llc/local-skills-mcp/issues/101)
+- docs: improve bundled skills using eval-driven pass ([fa48d15](https://github.com/kdpa-llc/local-skills-mcp/commit/fa48d15))
+- docs: polish README for improved clarity and organization (#69) ([6f1ac28](https://github.com/kdpa-llc/local-skills-mcp/commit/6f1ac28)), closes [#69](https://github.com/kdpa-llc/local-skills-mcp/issues/69)
+- docs: remove phantom cache from dev guide, fix README tool count and script names (#102) ([689c77e](https://github.com/kdpa-llc/local-skills-mcp/commit/689c77e)), closes [#102](https://github.com/kdpa-llc/local-skills-mcp/issues/102) [#100](https://github.com/kdpa-llc/local-skills-mcp/issues/100) [#101](https://github.com/kdpa-llc/local-skills-mcp/issues/101) [#101](https://github.com/kdpa-llc/local-skills-mcp/issues/101)
+- docs: update Complementary Projects to refer to MCP Compression Proxy ([3eef465](https://github.com/kdpa-llc/local-skills-mcp/commit/3eef465))
+- feat!: require Node.js 22+ and test on Node 22/24 (#98) ([9ca547d](https://github.com/kdpa-llc/local-skills-mcp/commit/9ca547d)), closes [#98](https://github.com/kdpa-llc/local-skills-mcp/issues/98)
+- chore: gitignore evals/ and remove tracked benchmark results ([950f77a](https://github.com/kdpa-llc/local-skills-mcp/commit/950f77a))
+- chore: gitignore evals/ and remove tracked benchmark results (#94) ([d7538ce](https://github.com/kdpa-llc/local-skills-mcp/commit/d7538ce)), closes [#94](https://github.com/kdpa-llc/local-skills-mcp/issues/94)
+- chore(deps-dev): bump @semantic-release/exec from 6.0.3 to 7.1.0 ([dac57c4](https://github.com/kdpa-llc/local-skills-mcp/commit/dac57c4))
+- chore(deps-dev): bump the development-dependencies group across 1 directory with 10 updates (#79) ([692d161](https://github.com/kdpa-llc/local-skills-mcp/commit/692d161)), closes [#79](https://github.com/kdpa-llc/local-skills-mcp/issues/79)
+- chore(deps-dev): bump the development-dependencies group with 4 updates (#71) ([69522ca](https://github.com/kdpa-llc/local-skills-mcp/commit/69522ca)), closes [#71](https://github.com/kdpa-llc/local-skills-mcp/issues/71)
+- chore(deps-dev): bump the development-dependencies group with 9 updates ([868d838](https://github.com/kdpa-llc/local-skills-mcp/commit/868d838))
+- chore(deps-dev): refresh in-range dev dependencies ([c2bfa06](https://github.com/kdpa-llc/local-skills-mcp/commit/c2bfa06))
+- chore(deps): bump @modelcontextprotocol/sdk ([c92fcf0](https://github.com/kdpa-llc/local-skills-mcp/commit/c92fcf0))
+- chore(deps): bump the production-dependencies group with 2 updates (#75) ([a7560f5](https://github.com/kdpa-llc/local-skills-mcp/commit/a7560f5)), closes [#75](https://github.com/kdpa-llc/local-skills-mcp/issues/75)
+- test: add coverage for eval-runner, skill-validator, and index handlers ([dbda456](https://github.com/kdpa-llc/local-skills-mcp/commit/dbda456))
+- test: add skill eval sets and benchmark snapshot ([0084c8c](https://github.com/kdpa-llc/local-skills-mcp/commit/0084c8c))
+- test: assert the real source path instead of a POSIX-shaped regex ([738bc2e](https://github.com/kdpa-llc/local-skills-mcp/commit/738bc2e))
+- test: build dist automatically and install the documented test UI ([ff75213](https://github.com/kdpa-llc/local-skills-mcp/commit/ff75213))
+- style: format tracked files with prettier and enforce it in CI ([4268563](https://github.com/kdpa-llc/local-skills-mcp/commit/4268563))
+- feat: add automated shipped-skill optimization workflow ([ce8c17b](https://github.com/kdpa-llc/local-skills-mcp/commit/ce8c17b))
+- feat: add repeatable shipped-skill benchmark and retune descriptions ([d6b324a](https://github.com/kdpa-llc/local-skills-mcp/commit/d6b324a))
+- feat: add skill validation and evaluation tools ([80caee1](https://github.com/kdpa-llc/local-skills-mcp/commit/80caee1))
+- feat: tune evaluate_skill controls and refresh shipped skill descriptions ([5fdc918](https://github.com/kdpa-llc/local-skills-mcp/commit/5fdc918))
+
+## <small>0.4.4 (2025-11-11)</small>
+
+- fix: add @semantic-release/git plugin and sync version to 0.4.3 ([4b5ef0c](https://github.com/kdpa-llc/local-skills-mcp/commit/4b5ef0c))
+
 ## <small>0.4.3 (2025-11-11)</small>
 
-* Merge pull request #54 from kdpa-llc/release-updates ([6886a58](https://github.com/kdpa-llc/local-skills-mcp/commit/6886a58)), closes [#54](https://github.com/kdpa-llc/local-skills-mcp/issues/54)
-* fix: revert release workflow to direct commits instead of PR creation ([3390139](https://github.com/kdpa-llc/local-skills-mcp/commit/3390139))
-* fix: revert release workflow to direct commits instead of PR creation ([606910a](https://github.com/kdpa-llc/local-skills-mcp/commit/606910a))
-* chore(release): update changelog and version [skip ci] ([8f40729](https://github.com/kdpa-llc/local-skills-mcp/commit/8f40729))
+- fix: revert release workflow to direct commits instead of PR creation ([3390139](https://github.com/kdpa-llc/local-skills-mcp/commit/3390139))
 
 ## <small>0.4.2 (2025-11-11)</small>
 

package/README.md

@@ -38,7 +38,6 @@
 - [🚀 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)
 
@@ -46,51 +45,55 @@
 
 ## 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.
+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. Lazy loading preserves context—only skill names and descriptions load initially; full content loads on-demand.
+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, 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
+- **🌐 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
+- **✨ Focused API** - Three tools: `get_skill` to load one, `validate_skill` to check a SKILL.md, `evaluate_skill` to measure how reliably it triggers
 
 ## 🚀 Quick Start
 
-### Install
+### 1. Install
 
-**From npm (recommended):**
+**Requirements:** Node.js 22+
+
+Choose one installation method:
 
 ```bash
+# From npm (recommended)
 npm install -g local-skills-mcp
-```
 
-**Alternative: From GitHub:**
-
-```bash
+# From GitHub
 npm install -g github:kdpa-llc/local-skills-mcp
-```
-
-**Or clone locally:**
 
-```bash
+# Or clone and build locally
 git clone https://github.com/kdpa-llc/local-skills-mcp.git
 cd local-skills-mcp
-npm install  # The prepare script auto-builds
+npm install  # Automatically builds via prepare script
 ```
 
-**Requirements:** Node.js 18+, any MCP-compatible client
+### 2. Configure MCP Client
 
-### Configure MCP Client
+Add to your MCP client configuration:
 
-Add to your MCP client configuration (e.g., `~/.config/claude-code/mcp.json`):
-
-**If installed globally:**
+**For Claude Code/Desktop** (`~/.config/claude-code/mcp.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
@@ -102,7 +105,11 @@ Add to your MCP client configuration (e.g., `~/.config/claude-code/mcp.json`):
 }
 ```
 
-**If cloned locally:**
+**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
 {
@@ -115,41 +122,32 @@ Add to your MCP client configuration (e.g., `~/.config/claude-code/mcp.json`):
 }
 ```
 
-**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.
+**Skill Discovery:**
 
-The server auto-aggregates skills from multiple directories in this priority order (lowest to highest):
+The server auto-aggregates skills from multiple directories (priority: low to high):
 
-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)
+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, allowing you to customize built-in skills.
+Later directories override earlier ones, letting you customize built-in skills.
 
-### Create & Use Skills
+### 3. Create & Use Skills
 
-**Option 1: Ask Claude to Create Skills (Recommended)**
+**Create Skills (Option 1: Ask AI - Recommended)**
 
-After installing Local Skills MCP, you can ask Claude to create skills for you:
+Simply ask your AI to create skills:
 
 ```
-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.
+"Create a Python expert skill for clean, idiomatic code"
+"Make a PR review skill focusing on security and best practices"
 ```
 
-```
-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!
-```
+The AI uses the built-in `skill-creator` skill to generate well-structured skills with proper YAML frontmatter and trigger keywords.
 
-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 Skills (Option 2: Manual)**
 
 Create `~/.claude/skills/my-skill/SKILL.md`:
 
@@ -163,16 +161,16 @@ You are an expert at [domain]. Your task is to [specific task].
 
 Guidelines:
 
-1. Be specific
+1. Be specific and actionable
 2. Provide examples
-3. Be helpful
+3. Include best practices
 ```
 
-**Using Skills:**
+**Use Skills**
 
-Request any skill in your AI client: `"Use the my-skill skill"`
+Request any skill: `"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!
+Skills are auto-discovered and load on-demand. **All changes apply instantly** with hot reload—no restart needed!
 
 ## 📝 SKILL.md Format
 
@@ -194,38 +192,58 @@ Your skill instructions in Markdown format...
 
 **Writing Effective Descriptions:**
 
-Pattern: `[What it does]. Use when [trigger conditions/keywords].`
+Use pattern: `[What it does]. Use when [trigger conditions/keywords].`
+
+✅ **Good Examples:**
 
-- ✅ **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"
+- "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."
 
-Claude uses language understanding to decide when to invoke skills—specific trigger keywords help Claude make better decisions.
+❌ **Poor Example:**
+
+- "Helps with Excel files"
+
+Specific trigger keywords help the AI make better decisions when selecting skills.
 
 ## 🎯 Usage
 
-**Single Tool:** `get_skill` - loads expert prompt instructions for specific tasks
+**How It Works:**
 
-**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
 
-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:**
+
+Three self-documenting skills are included:
 
-**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.
+**Skill Directories:**
+
+Auto-aggregates from multiple locations (later ones override earlier):
 
-**Custom Directory:** Add via environment variable:
+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
 {
-  "command": "local-skills-mcp",
-  "env": {
-    "SKILLS_DIR": "/custom/path/to/skills"
+  "mcpServers": {
+    "local-skills": {
+      "command": "local-skills-mcp",
+      "env": {
+        "SKILLS_DIR": "/custom/path/to/skills"
+      }
+    }
   }
 }
 ```
@@ -243,22 +261,12 @@ You are a code reviewer with expertise in software engineering best practices.
 Analyze the code for:
 
 1. Correctness and bugs
-2. Best practices
+2. Best practices and maintainability
 3. Performance and security issues
-4. Maintainability
 
-Provide specific, actionable feedback.
+Provide specific, actionable feedback with examples.
 ```
 
-## 🆚 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
 
 <details>
@@ -267,75 +275,80 @@ Provide specific, actionable feedback.
 </details>
 
 <details>
-<summary><strong>Q: How is this different from Claude's built-in skills?</strong></summary>
-<p>Works with any MCP client (not just Claude), aggregates from multiple directories, explicit invocation control, and better context efficiency via lazy loading.</p>
+<summary><strong>Q: Can I use existing Claude skills from ~/.claude/skills/?</strong></summary>
+<p>Yes! The server automatically aggregates skills from <code>~/.claude/skills/</code> along with other directories.</p>
 </details>
 
 <details>
-<summary><strong>Q: Can I use existing Claude skills?</strong></summary>
-<p>Yes! Auto-aggregates from <code>~/.claude/skills/</code> along with other directories.</p>
+<summary><strong>Q: Do I need to restart after adding or editing skills?</strong></summary>
+<p>No! Hot reload is fully supported. All changes (new skills, edits, deletions) apply instantly without restarting the MCP server.</p>
 </details>
 
 <details>
-<summary><strong>Q: Do I need to restart after adding skills?</strong></summary>
-<p>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.</p>
+<summary><strong>Q: How do I override a built-in skill?</strong></summary>
+<p>Create a skill with the same name in a higher-priority directory. Priority order: package built-in → <code>~/.claude/skills</code> → <code>./.claude/skills</code> → <code>./skills</code> → <code>$SKILLS_DIR</code>.</p>
 </details>
 
 <details>
-<summary><strong>Q: How much context does this consume?</strong></summary>
-<p>Minimal! Only names/descriptions initially (~50 tokens/skill). Full content loads on-demand, preserving 95%+ of context.</p>
+<summary><strong>Q: Does this work with local LLMs (Ollama, LM Studio)?</strong></summary>
+<p>Yes! Works with any MCP-compatible client and LLM. Skills are structured prompts that work with any model.</p>
 </details>
 
 <details>
-<summary><strong>Q: Can I use multiple skill directories?</strong></summary>
-<p>Yes! Auto-aggregates from package built-in skills, <code>~/.claude/skills/</code>, <code>./.claude/skills/</code>, <code>./skills</code>, and <code>$SKILLS_DIR</code>.</p>
+<summary><strong>Q: Does this work offline?</strong></summary>
+<p>Yes! The MCP server runs entirely on your local filesystem (though your LLM may require internet depending on the provider).</p>
 </details>
 
 <details>
-<summary><strong>Q: What if I have duplicate skill names?</strong></summary>
-<p>Later directories override earlier ones: package built-in → <code>~/.claude/skills</code> → <code>./.claude/skills</code> → <code>./skills</code> → <code>$SKILLS_DIR</code>. This lets you customize built-in skills.</p>
+<summary><strong>Q: How do I create effective skills?</strong></summary>
+<p>See the <a href="#-skillmd-format">SKILL.md format section</a>. Use clear descriptions with trigger keywords, specific instructions, and examples. Or ask your AI to create skills using the built-in <code>skill-creator</code> skill.</p>
 </details>
 
 <details>
-<summary><strong>Q: What built-in skills are included?</strong></summary>
-<p>The package includes three self-documenting skills: <code>local-skills-mcp-usage</code> (quick usage guide), <code>local-skills-mcp-guide</code> (comprehensive documentation), and <code>skill-creator</code> (skill authoring guide). These are available immediately after installation.</p>
+<summary><strong>Q: Where can I get help?</strong></summary>
+<p>Open an <a href="https://github.com/kdpa-llc/local-skills-mcp/issues">issue on GitHub</a> or check the built-in <code>local-skills-mcp-guide</code> skill.</p>
 </details>
 
-<details>
-<summary><strong>Q: Works with local LLMs (Ollama, LM Studio)?</strong></summary>
-<p>Yes! Works with any MCP-compatible LLM setup. Skills are structured prompts that work with any model.</p>
-</details>
+**More:** See [CONTRIBUTING.md][contributing], [SECURITY.md][security], [CHANGELOG.md][changelog]
 
-<details>
-<summary><strong>Q: Works offline?</strong></summary>
-<p>Yes! Runs entirely on local filesystem (though your LLM may need internet depending on the model).</p>
-</details>
+## 🤝 Contributing
 
-<details>
-<summary><strong>Q: How to create a good skill?</strong></summary>
-<p>Follow <a href="#-skillmd-format">SKILL.md format</a>. Use clear descriptions with trigger keywords, specific instructions, and examples.</p>
-</details>
+Contributions welcome! See [CONTRIBUTING.md][contributing] for detailed guidelines.
 
-<details>
-<summary><strong>Q: Where can I get help?</strong></summary>
-<p>Open an <a href="https://github.com/kdpa-llc/local-skills-mcp/issues">issue on GitHub</a>.</p>
-</details>
+**Quick start:**
 
-**More:** See [CONTRIBUTING.md][contributing], [SECURITY.md][security], [CHANGELOG.md][changelog]
+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
 
-## 🤝 Contributing
+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:**
 
-Contributions welcome! See [CONTRIBUTING.md][contributing] for guidelines.
+- **Local Skills MCP** - Expert skills with lazy loading (~50 tokens/skill)
+- **MCP Compression Proxy** - Compressed tool descriptions (50-80% token reduction)
 
-Quick start:
+**Together they enable:**
 
-1. Fork the repository
-2. Create your feature branch
-3. Make your changes and test
-4. Commit and push
-5. Open a Pull Request
+- 🎯 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
 
-Note: This project follows a [Code of Conduct][code-of-conduct].
+[Learn more about MCP Compression Proxy →][mcp-tool-aggregator]
 
 ## 💖 Support This Project
 
@@ -435,3 +448,4 @@ Made with ❤️ by KDPA
 
 [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

package/dist/eval-runner.d.ts

@@ -0,0 +1,31 @@
+export interface EvaluateSkillInput {
+    skill_name: string;
+    skill_path?: string;
+    eval_set_path?: string;
+    max_iterations?: number;
+    model?: string;
+    num_workers?: number;
+    runs_per_query?: number;
+    timeout_seconds?: number;
+    holdout?: number;
+    trigger_threshold?: number;
+    description_override?: string;
+}
+export interface EvaluateSkillResult {
+    best_description?: string;
+    scores?: Record<string, number>;
+    iteration_history?: unknown[];
+    [key: string]: unknown;
+}
+type RunLoopInvocation = "module" | "script";
+interface PrerequisiteCheck {
+    ok: boolean;
+    pythonCommand?: string;
+    runLoopPath: string;
+    runLoopCwd: string;
+    runLoopInvocation: RunLoopInvocation;
+    missing: string[];
+}
+export declare function checkEvaluatePrerequisites(repoRoot: string): PrerequisiteCheck;
+export declare function evaluateSkill(input: EvaluateSkillInput, repoRoot: string): Promise<EvaluateSkillResult>;
+export {};