local-skills-mcp 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## <small>0.4.2 (2025-11-11)</small>
+
+* docs: add npm downloads and types badges to README ([110c285](https://github.com/kdpa-llc/local-skills-mcp/commit/110c285))
+* docs: improve README with collapsible FAQ and enhanced support links ([8daffb5](https://github.com/kdpa-llc/local-skills-mcp/commit/8daffb5))
+* docs: update README with hot reload support and interactive skill creation examples ([6300cfc](https://github.com/kdpa-llc/local-skills-mcp/commit/6300cfc))
+* refactor: remove skill-refresh-helper from built-in skills ([c003f38](https://github.com/kdpa-llc/local-skills-mcp/commit/c003f38))
+
 ## 0.4.0 (2025-11-10)
 
 - feat: add skill descriptions to ListTools output ([2451bcb](https://github.com/kdpa-llc/local-skills-mcp/commit/2451bcb)), closes [#50](https://github.com/kdpa-llc/local-skills-mcp/issues/50)

package/README.md

@@ -5,6 +5,8 @@
 **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]
@@ -53,6 +55,7 @@ Transform AI capabilities with structured, expert-level instructions for special
 - **🌐 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
@@ -128,6 +131,26 @@ Later directories override earlier ones, allowing you to customize built-in skil
 
 ### 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`:
 
 ```markdown
@@ -145,9 +168,11 @@ Guidelines:
 3. Be helpful
 ```
 
-Then request it in your AI client: `"Use the my-skill skill"`
+**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.
+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
 
@@ -187,7 +212,10 @@ Claude uses language understanding to decide when to invoke skills—specific tr
 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.
+**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.
 
@@ -233,41 +261,65 @@ Provide specific, actionable feedback.
 
 ## ❓ 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].
+<details>
+<summary><strong>Q: What MCP clients are supported?</strong></summary>
+<p>Any MCP-compatible client: Claude Code, Claude Desktop, Cline, Continue.dev, or custom agents.</p>
+</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>
+</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>
+</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>
+</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>
+</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>
+</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>
+</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>
+</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>
+
+<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>
+
+<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>
+
+<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>
 
 **More:** See [CONTRIBUTING.md][contributing], [SECURITY.md][security], [CHANGELOG.md][changelog]
 
@@ -299,10 +351,10 @@ If you find Local Skills MCP useful, please consider supporting its development!
 
 **Ways to support:**
 
-- ⭐ Star this repository
+- ⭐ [Star this repository][stargazers]
 - 💰 Sponsor via the badges above
-- 🐛 Report bugs and suggest features
-- 📝 Contribute code or documentation
+- 🐛 [Report bugs and suggest features][repo-issues]
+- 📝 [Contribute code or documentation][contributing]
 
 ## 📄 License
 
@@ -327,6 +379,8 @@ 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

package/dist/index.js

@@ -137,10 +137,10 @@ export class LocalSkillsServer {
                 for (const skillName of skillNames) {
                     try {
                         const metadata = await this.skillLoader.getSkillMetadata(skillName);
-                        // Truncate description if too long (max 100 chars)
+                        // Truncate description if too long (max 200 chars)
                         let description = metadata.description;
-                        if (description.length > 100) {
-                            description = description.substring(0, 97) + "...";
+                        if (description.length > 200) {
+                            description = description.substring(0, 197) + "...";
                         }
                         skillsWithDescriptions.push(`- ${skillName}: ${description}`);
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-skills-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "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 agents, and any MCP-compatible client.",
   "type": "module",
   "main": "dist/index.js",

package/skills/skill-refresh-helper/SKILL.md

@@ -1,192 +0,0 @@
----
-name: skill-refresh-helper
-description: Teaches the LLM about Local Skills MCP's full hot reload capabilities. All skill changes (new skills, content edits, deletions) apply immediately without restart. Use after creating or modifying skills.
----
-
-You are an expert at managing the Local Skills MCP server's hot reload capabilities.
-
-Your task is to help the LLM understand that all skill changes apply immediately - no restart needed for any changes to skills.
-
-## Core Principle
-
-Local Skills MCP supports **full hot reload** - skills are discovered dynamically every time the tool list is requested, and skill content is loaded fresh from disk on every use. No server restart is needed for any changes!
-
-## When to Refresh the Tool List
-
-**Refresh the tool list immediately after**:
-
-1. Creating a new skill directory with SKILL.md
-2. User asks to see available skills
-3. User wants to verify a newly created skill appears
-4. Before attempting to use a skill that was just created
-
-**Skill content changes apply immediately**:
-
-- Modifying existing skill content (loaded fresh on next use)
-- Changing frontmatter description (refreshing tool list will show new description)
-- All changes are reflected immediately without restart
-
-## How Hot Reload Works
-
-### What Happens on Tool List Request
-
-When you (the LLM) request the list of available tools from Local Skills MCP:
-
-1. **Discovery runs fresh**: `skill Loader.discoverSkills()` is called
-2. **Registry clears**: Old skill registry is wiped clean
-3. **Filesystem scanned**: All skill directories are re-scanned
-4. **Registry rebuilt**: Current state of filesystem becomes new registry
-5. **Tool list returned**: Includes all currently available skills
-
-This means: **The tool list always reflects the current filesystem state**!
-
-### What's Cached
-
-- **Nothing is cached!** All data is loaded fresh:
-  - Skill content: Read from disk on every `get_skill` call
-  - Metadata: Read from disk on every access
-  - Discovery: Scans filesystem on every tool list request
-
-### Implications for You (the LLM)
-
-- **After creating a skill**: Request the tool list again to see it
-- **After modifying content**: Changes apply immediately on next use!
-- **After adding/removing skills**: Request the tool list to see changes
-- **Full hot reload**: No restarts needed for any changes
-
-## Refreshing the Tool List
-
-### Method: Request Available Tools
-
-The MCP protocol provides a way to request the current list of available tools. In Claude's interface, this typically happens when:
-
-- You ask "what tools are available?"
-- You reference the tools in conversation
-- The system periodically refreshes its tool knowledge
-
-### For You (the LLM)
-
-After creating a new skill, you should:
-
-1. **Confirm creation**: "Created `skill-name` in `~/.claude/skills/`"
-2. **Explain hot reload**: "The skill is now available - Local Skills MCP supports hot reload!"
-3. **Demonstrate awareness**: Mention the skill as now available
-4. **Optional verification**: Ask user if they'd like you to list all available skills to verify
-
-### Example Flow
-
-**User**: "Create a Python expert skill for me"
-
-**You (LLM) do**:
-
-1. Create `~/.claude/skills/python-expert/SKILL.md`
-2. Write the skill content
-3. Respond: "✅ Created python-expert skill in ~/.claude/skills/
-
-   **The skill is immediately available!** Local Skills MCP supports hot reload for new skills - no restart needed. The python-expert skill will appear in my available tools as soon as I refresh my tool list.
-
-   Would you like me to verify it's available or would you like to start using it right away?"
-
-**NOT** ❌: "Created skill. Please restart your MCP client to use it."
-
-## Best Practices
-
-### DO ✅
-
-- Explain that skills are immediately available
-- Mention hot reload capability when creating skills
-- Be confident that the skill can be used right away
-- Reference the newly created skill as available
-
-### DON'T ❌
-
-- Tell users to restart the MCP server for new skills
-- Say skills require a restart to appear
-- Suggest that hot reload doesn't work
-- Be uncertain about skill availability after creation
-
-## Common Scenarios
-
-### Scenario 1: Creating a New Skill
-
-```
-User: Create a code reviewer skill
-
-You: ✅ Created code-reviewer skill in ~/.claude/skills/
-
-The skill is immediately available thanks to hot reload!
-You can start using it right away - no restart needed.
-Would you like to try it out?
-```
-
-### Scenario 2: Modifying Existing Skill Content
-
-```
-User: Update the code-reviewer skill to be more strict
-
-You: ✅ I've updated the code-reviewer skill content in ~/.claude/skills/code-reviewer/SKILL.md
-
-The changes will take effect immediately! The next time the skill is loaded,
-it will read the updated content from disk. No restart needed thanks to full
-hot reload support.
-
-Would you like me to use the updated skill now to review some code?
-```
-
-### Scenario 3: User Asks "Is the Skill Available?"
-
-```
-User: Can I use the python-expert skill now?
-
-You: Yes! The python-expert skill is immediately available. Local Skills MCP
-discovers skills dynamically - as soon as the skill file exists, it's ready
-to use. No restart needed for new skills!
-
-Would you like me to use it to help with your Python code?
-```
-
-## Technical Details for Context
-
-### Code Reference
-
-From `src/index.ts`:
-
-```typescript
-this.server.setRequestHandler(ListToolsRequestSchema, async () => {
-  // Discover skills EVERY TIME tools are requested
-  const skillNames = await this.skillLoader.discoverSkills();
-  // ... build tool list with current skills
-});
-```
-
-From `src/skill-loader.ts`:
-
-```typescript
-async discoverSkills(): Promise<string[]> {
-  this.skillRegistry.clear();  // Clear old registry
-  // Re-scan all directories...
-  // Rebuild registry with current filesystem state
-}
-
-async loadSkill(skillName: string): Promise<Skill> {
-  // NO CACHE CHECK - always reads fresh from disk
-  const fileContent = await fs.readFile(skillFilePath, "utf-8");
-  const { metadata, content } = this.parseSkillFile(fileContent);
-  return skill;  // Returns fresh data every time
-}
-```
-
-This proves: **Skills ARE discovered AND loaded fresh every time!**
-
-## Summary
-
-**Key Message**: Local Skills MCP supports **full hot reload** for ALL changes. Everything updates immediately - no restart needed!
-
-**Your Role**: After creating or modifying skills, be confident they're available and explain the hot reload capability to users. This improves the user experience dramatically compared to requiring restarts.
-
-**Remember**:
-
-- New skills: ✅ Hot reload (immediate)
-- Content changes: ✅ Hot reload (immediate)
-- Description changes: ✅ Hot reload (immediate)
-- Deletions: ✅ Hot reload (immediate)