@skilljack/mcp
Advanced tools
An MCP server that jacks Agent Skills directly into your LLM's brain.
Recommended: For best results, use an MCP client that supports
tools/listChangednotifications (e.g., Claude Code). This enables dynamic skill discovery - when skills are added or modified, the client automatically refreshes its understanding of available skills. Alternatively, use--staticmode for predictable behavior with a fixed skill set.
tools/listChanged so clients can refresh available skills/skill prompt with auto-completion or per-skill promptsskill:// URIs with batch collection supportnotifications/resources/updatedThis repo demonstrates a way to approach integrating skills using existing MCP primitives.
MCP already has the building blocks:
skill tool with dynamically updated descriptions)skill:// URIs)tools/listChanged, resources/updated)/my-server-skill)This approach provides separation of concerns. Rather than every MCP server needing to embed skill handling, the server acts as a dedicated 'skill gateway'. Server authors can bundle skills alongside their MCP servers without modifying the servers themselves. If MCP registries support robust tool discovery, skill tools become discoverable like any other tool.
npm install @skilljack/mcp
Or run directly with npx:
npx @skilljack/mcp /path/to/skills
git clone https://github.com/olaservo/skilljack-mcp.git
cd skilljack-mcp
npm install
npm run build
Configure one or more skills directories containing your Agent Skills:
# Single directory
skilljack-mcp /path/to/skills
# Multiple directories (separate args or comma-separated)
skilljack-mcp /path/to/skills /path/to/more/skills
skilljack-mcp /path/to/skills,/path/to/more/skills
# Using environment variable (comma-separated for multiple)
SKILLS_DIR=/path/to/skills skilljack-mcp
SKILLS_DIR=/path/to/skills,/path/to/more/skills skilljack-mcp
Each directory is scanned along with its .claude/skills/ and skills/ subdirectories for skills. Duplicate skill names are handled by keeping the first occurrence.
By default, Skilljack MCP watches skill directories for changes and notifies clients when skills are added, modified, or removed.
Enable static mode to freeze the skills list at startup:
skilljack-mcp --static /path/to/skills
# or
SKILLJACK_STATIC=true skilljack-mcp /path/to/skills
In static mode:
tools.listChanged and prompts.listChanged capabilities are falseUse static mode when you need predictable behavior or have a fixed set of skills that won't change during the session.
Windows note: Use forward slashes in paths when using with MCP Inspector:
skilljack-mcp "C:/Users/you/skills"
In MCP clients that support MCP Apps (like Claude Desktop), you can manage skill directories through an interactive UI.
To open the configuration UI, ask your assistant to show the skilljack config:
"show me the skilljack config"
The UI displays:
Changes made through the UI are persisted to the server's configuration. Clients that support tools/listChanged notifications will see updates immediately; others may require reconnection.
View all available skills and customize their invocation settings through the skill display UI.
To open the skill display UI, ask your assistant:
"what skills are configured in skilljack?"
The UI displays:
Skills from GitHub repositories show the org/repo name (e.g., modelcontextprotocol/ext-apps), making it easy to identify where each skill originates.
The server implements the Agent Skills progressive disclosure pattern with dynamic updates:
tools/listChangedskill tool to load full SKILL.md contentskill-resource to load additional files┌─────────────────────────────────────────────────────────┐
│ Server starts │
│ • Discovers skills from configured directories │
│ • Starts watching for SKILL.md changes │
│ ↓ │
│ MCP Client connects │
│ • Skill tool description includes available skills │
│ • Prompts registered for each skill │
│ ↓ │
│ LLM sees skill metadata in tool description │
│ ↓ │
│ SKILL.md added/modified/removed │
│ • Server re-discovers skills │
│ • Updates skill tool description │
│ • Updates prompt list (add/remove/modify) │
│ • Sends tools/listChanged notification │
│ • Sends prompts/listChanged notification │
│ • Client refreshes tool and prompt definitions │
│ ↓ │
│ User invokes /skill prompt or /skill-name prompt │
│ OR LLM calls "skill" tool with skill name │
│ ↓ │
│ Server returns full SKILL.md content │
│ ↓ │
│ LLM calls "skill-resource" for additional files │
│ • Scripts, snippets, references, assets, etc. │
└─────────────────────────────────────────────────────────┘
This server exposes skills via tools, resources, and prompts:
skill, skill-resource) - For your agent to use autonomously. The LLM sees available skills in the tool description and calls them as needed./skill, /skill-name) - For explicit user invocation. Use /skill with auto-completion or select a skill directly by name.skill:// URIs) - For manual selection in apps that support it (e.g., Claude Desktop's resource picker). Useful when you want to explicitly attach a skill to the conversation.Most users will rely on tools for automatic skill activation. Prompts provide user-initiated loading with auto-completion. Resources provide an alternative for manual control.
This server implements the Agent Skills progressive disclosure pattern, which structures skills for efficient context usage:
| Level | Tokens | What's loaded | When |
|---|---|---|---|
| Metadata | ~100 | name and description | At startup, for all skills |
| Instructions | < 5000 | Full SKILL.md body | When skill is activated |
| Resources | As needed | Files in scripts/, references/, assets/ | On demand via skill-resource |
skill tool descriptionskill-resource as neededThe server doesn't automatically list all files in a skill directory. Instead, skill authors document available resources directly in their SKILL.md (e.g., "Copy the template from templates/server.ts"). This design choice follows the spec because:
For skill authors: Reference files using relative paths from the skill root (e.g., snippets/tool.ts, references/api.md). Keep your main SKILL.md under 500 lines; move detailed reference material to separate files. See the Agent Skills specification for complete authoring guidelines.
skillLoad and activate an Agent Skill by name. Returns the full SKILL.md content.
Input:
{
"name": "skill-name"
}
Output: Full SKILL.md content including frontmatter and instructions.
skill-resourceRead files within a skill's directory (scripts/, references/, assets/, snippets/, etc.).
This follows the Agent Skills spec's progressive disclosure pattern - resources are loaded only when needed.
Read a single file:
{
"skill": "mcp-server-ts",
"path": "snippets/tools/echo.ts"
}
Read all files in a directory:
{
"skill": "algorithmic-art",
"path": "templates"
}
Returns all files in the directory as multiple content items.
List available files (pass empty path):
{
"skill": "mcp-server-ts",
"path": ""
}
Security: Path traversal is prevented - only files within the skill directory can be accessed.
Skills can be loaded via MCP Prompts for explicit user invocation.
/skill PromptLoad a skill by name with auto-completion support.
Arguments:
name (string, required) - Skill name with auto-completionThe prompt description includes all available skills for discoverability. As you type the skill name, matching skills are suggested.
Each discovered skill is also registered as its own prompt (e.g., /mcp-server-ts, /algorithmic-art).
Example: If you have a skill named mcp-server-ts, you can invoke it directly as /mcp-server-ts.
Prompt responses include MCP content annotations for proper handling:
audience: ["assistant"] - Content is intended for the LLM, not the userpriority: 1.0 - High priority content that should be included in contextPrompts return embedded resources with the skill's skill:// URI, allowing clients to track the content source.
Skills are also accessible via MCP Resources using skill:// URIs.
| URI | Returns |
|---|---|
skill://{name} | Single skill's SKILL.md content |
skill://{name}/ | All files in skill directory (collection) |
Individual file URIs (skill://{name}/{path}) are not listed as resources to reduce noise. Use the skill-resource tool to fetch specific files on demand.
Clients can subscribe to resources for real-time updates when files change.
Capability: resources: { subscribe: true, listChanged: true }
Subscribe to a resource:
→ resources/subscribe { uri: "skill://mcp-server-ts" }
← {} (success)
Receive notifications when files change:
← notifications/resources/updated { uri: "skill://mcp-server-ts" }
Unsubscribe:
→ resources/unsubscribe { uri: "skill://mcp-server-ts" }
← {} (success)
How it works:
skill:// URISkills are treated as trusted content. This server reads and serves skill files directly to clients without sanitization. Only configure skills directories containing content you trust.
Protections in place:
MAX_FILE_SIZE_MB env var)Not protected against:
The server watches skill directories for changes. When SKILL.md files are added, modified, or removed:
skill tool's description is updated with current skill names and metadatatools/listChanged and prompts/listChanged notifications are sent to connected clientsThe skill tool description includes metadata for all available skills in XML format:
# Skills
When a user's task matches a skill description below: 1) activate it, 2) follow its instructions completely.
<available_skills>
<skill>
<name>mcp-server-ts</name>
<description>Build TypeScript MCP servers with composable code snippets...</description>
<location>C:/path/to/mcp-server-ts/SKILL.md</location>
</skill>
</available_skills>
This metadata is dynamically updated when skills change - clients supporting tools/listChanged will automatically refresh.
Skills are discovered at startup from the configured directories. For each directory, the server checks:
.claude/skills/ subdirectoryskills/ subdirectoryEach skill subdirectory must contain a SKILL.md file with YAML frontmatter including name and description fields.
Control which skills appear in tools vs prompts using optional frontmatter fields:
| Frontmatter | In Tool Description | In Prompts Menu | Use Case |
|---|---|---|---|
| (default) | Yes | Yes | Normal skills |
disable-model-invocation: true | No | Yes | User-triggered workflows (deploy, commit) |
user-invocable: false | Yes | No | Background context (model auto-loads when relevant) |
Hide from model auto-discovery, require explicit user invocation via /skill-name prompt:
---
name: deploy
description: Deploy to production
disable-model-invocation: true
---
Hide from prompts menu, model uses automatically when relevant:
---
name: codebase-context
description: Background information about this codebase
user-invocable: false
---
Note: Resources (skill:// URIs) always include all skills regardless of these settings, allowing explicit access when needed.
npm run build
npm run inspector -- /path/to/skills
The evals/ directory contains an evaluation framework for testing skill activation across different delivery modes. Evals are only available when developing from source (not included in the npm package).
# Clone the repo first
git clone https://github.com/olaservo/skilljack-mcp.git
cd skilljack-mcp
# Install dev dependencies (includes claude-agent-sdk for evals)
npm install
# Build and run evals
npm run build
npm run eval # Default: greeting task, MCP mode
npm run eval -- --task=xlsx-openpyxl # Specific task
npm run eval -- --mode=native # Native skill mode
npm run eval -- --mode=mcp+native # Both MCP and native enabled
See evals/README.md for details on available tasks, modes, and findings about activation behavior differences.
FAQs
MCP server that discovers and serves Agent Skills. I know kung fu.
The npm package @skilljack/mcp receives a total of 39 weekly downloads. As such, @skilljack/mcp popularity was classified as not popular.
We found that @skilljack/mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
The North Korean malware loader hides in a Packagist-listed package and its GitHub branch to fetch and execute remote code in a likely Contagious Interview-style lure.
Security News
The Rust project is moving toward formal rules on LLM use in contributions after months of internal debate over maintainer burden, code quality, and contributor experience.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.