# Skilljack Docs > Complete documentation for the Skilljack MCP server - tools, prompts, resources, configuration, and architecture reference. - **Type:** Skill - **Install:** `agentstack add skill-olaservo-skilljack-mcp-skilljack-docs` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [olaservo](https://agentstack.voostack.com/s/olaservo) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [olaservo](https://github.com/olaservo) - **Source:** https://github.com/olaservo/skilljack-mcp/tree/main/skills/skilljack-docs ## Install ```sh agentstack add skill-olaservo-skilljack-mcp-skilljack-docs ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Skilljack MCP Documentation An MCP server that jacks [Agent Skills](https://agentskills.io) directly into your LLM's brain. > **Recommended:** For best results, use an MCP client that supports `tools/listChanged` notifications (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 `--static` mode for predictable behavior with a fixed skill set. ## Features - **Dynamic Skill Discovery** - Watches skill directories and automatically refreshes when skills change - **Tool List Changed Notifications** - Sends `tools/listChanged` so clients can refresh available skills - **Skill Tool** - Load full skill content on demand (progressive disclosure) - **MCP Prompts** - Load skills via `/skill` prompt with auto-completion or per-skill prompts - **MCP Resources** - Access skills via `skill://` URIs aligned with [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640) - **Resource Subscriptions** - Real-time file watching with `notifications/resources/updated` - **Configuration UI** - Manage skill directories through an interactive UI in supported clients ## Motivation This server demonstrates a way to approach integrating skills using existing MCP primitives. MCP already has the building blocks: - **Tools** for on-demand skill loading (the `skill` tool with dynamically updated descriptions) - **Resources** for explicit skill access (`skill://` URIs) - **Notifications** for real-time updates (`tools/listChanged`, `resources/updated`) - **Prompts** for explicitly invoking skills by name (`/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. ## Usage Configure one or more skills directories containing your Agent Skills: ```bash # 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. ### Static Mode 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: ```bash skilljack-mcp --static /path/to/skills # or SKILLJACK_STATIC=true skilljack-mcp /path/to/skills ``` In static mode: - Skills are discovered once at startup and never refreshed - No file watchers are set up for skill directories - `tools.listChanged` and `prompts.listChanged` capabilities are `false` - Resource subscriptions remain fully dynamic (individual skill files can still be watched) Use 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: ```bash skilljack-mcp "C:/Users/you/skills" ``` ## Configuration UI In MCP clients that support [MCP Apps](https://blog.modelcontextprotocol.io/posts/2026-01-26-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: - Current skill directories with skill counts - Status indicators showing which directories are from config vs command-line - Options to add new directories or remove existing ones 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. ## Skill Display UI 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: - All discovered skills with name, description, and file path - **Source indicators** showing whether each skill is from a local directory or GitHub repository - **Invocation toggles** to enable/disable Assistant (model auto-invoke) and User (prompts menu) visibility - **Customized badge** when settings differ from frontmatter defaults Skills from GitHub repositories show the org/repo name (e.g., `modelcontextprotocol/ext-apps`), making it easy to identify where each skill originates. ## How It Works The server implements the [Agent Skills](https://agentskills.io) progressive disclosure pattern with dynamic updates: 1. **At startup**: Discovers skills from configured directories and starts file watchers 2. **On connection**: Skill tool description includes available skills metadata 3. **On file change**: Re-discovers skills, updates tool description, sends `tools/listChanged` 4. **On tool call**: Agent calls `skill` tool to load full SKILL.md content 5. **As needed**: Agent calls `skill-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. │ └─────────────────────────────────────────────────────────┘ ``` ## Tools vs Resources vs Prompts This server exposes skills via **tools**, **resources**, and **prompts**: - **Tools** (`skill`, `skill-resource`) - For your agent to use autonomously. The LLM sees available skills in the tool description and calls them as needed. - **Prompts** (`/skill`, `/skill-name`) - For explicit user invocation. Use `/skill` with auto-completion or select a skill directly by name. - **Resources** (`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. Skills are context delivered through MCP primitives. Tools enable autonomous activation by the agent. Prompts enable user-initiated loading with auto-completion. Resources provide explicit access for manual control. Each mechanism suits different workflows — skills aren't tied to any single delivery path. ## Progressive Disclosure Design This server implements the [Agent Skills progressive disclosure pattern](https://agentskills.io/specification#progressive-disclosure), which structures skills for efficient context usage: | Level | Tokens | What's loaded | When | |-------|--------|---------------|------| | **Metadata** | ~100 | `name` and `description` | At startup, for all skills | | **Instructions** | /SKILL.md` | The skill's `SKILL.md` (`text/markdown`). Listed in `resources/list`. | | `skill:///` | A supporting file inside the skill directory. Template-resolvable; not listed. | | `skill://index.json` | SEP-2640 discovery index (`application/json`). Listed in `resources/list`. | `` is `/` for prefixed skills (the prefix segments come from the skill's source — e.g., a local directory basename or `owner-repo` for GitHub-sourced skills) or just `` for bundled skills. The final `` segment always matches the `name` field in the skill's frontmatter, per SEP. ### Resource Subscriptions 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://skilljack-docs/SKILL.md" } ← {} (success) ``` **Receive notifications when files change:** ``` ← notifications/resources/updated { uri: "skill://skilljack-docs/SKILL.md" } ``` **Unsubscribe:** ``` → resources/unsubscribe { uri: "skill://skilljack-docs/SKILL.md" } ← {} (success) ``` Subscribing to `skill://index.json` watches every SKILL.md, so any skill change re-fires that subscription as well as `notifications/resources/updated` for `skill://index.json` directly when skills are added or removed. **How it works:** 1. Client subscribes to a `skill://` URI 2. Server resolves URI to file path(s) and starts watching with chokidar 3. When files change, server debounces (100ms) and sends notification 4. Client can re-read the resource to get updated content ## Security **Skills 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: - Path traversal prevention (symlink-aware) - File size limits (1MB default, configurable via `MAX_FILE_SIZE_MB` env var) - Directory depth limits - Skill content is confined to configured directories Not protected against: - Malicious content within trusted skill directories - Prompt injection via skill instructions (skills can influence LLM behavior by design) ## Dynamic Skill Discovery The server watches skill directories for changes. When SKILL.md files are added, modified, or removed: 1. Skills are re-discovered from all configured directories 2. The `skill` tool's description is updated with current skill names and metadata 3. Per-skill prompts are added, removed, or updated accordingly 4. `tools/listChanged` and `prompts/listChanged` notifications are sent to connected clients 5. Clients that support these notifications will refresh tool and prompt definitions ## Skill Metadata Format The `skill` tool description includes metadata for all available skills in XML format: ```markdown # Skills When a user's task matches a skill description below: 1) activate it, 2) follow its instructions completely. mcp-server-ts Build TypeScript MCP servers with composable code snippets... C:/path/to/mcp-server-ts/SKILL.md ``` This metadata is dynamically updated when skills change - clients supporting `tools/listChanged` will automatically refresh. ## Skill Discovery Skills are discovered at startup from the configured directories. For each directory, the server checks: - The directory itself for skill subdirectories - `.claude/skills/` subdirectory - `skills/` subdirectory Each skill subdirectory must contain a `SKILL.md` file with YAML frontmatter including `name` and `description` fields. ## Skill Visibility Control 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) | ### Example: User-Only Skill Hide from model auto-discovery, require explicit user invocation via `/skill-name` prompt: ```yaml --- name: deploy description: Deploy to production disable-model-invocation: true --- ``` ### Example: Model-Only Skill Hide from prompts menu, model uses automatically when relevant: ```yaml --- name: codebase-context description: Background information about this codebase user-invocable: false --- ``` Note: Resources (`skill://` URIs) always include all skills regardless of visibility settings, allowing explicit access when needed. ## Testing ### Manual Testing with MCP Inspector ```bash npm run build npm run inspector -- /path/to/skills ``` ### Automated Evals (Development Only) 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). ```bash # 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=local # Local skill mode npm run eval -- --mode=mcp+local # Both MCP and local enabled ``` See [evals/README.md](https://github.com/olaservo/skilljack-mcp/blob/main/evals/README.md) for details on available tasks, modes, and findings about activation behavior differences. ## Related - [Agent Skills Specification](https://agentskills.io) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - [Example MCP Clients](https://modelcontextprotocol.io/clients) ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [olaservo](https://github.com/olaservo) - **Source:** [olaservo/skilljack-mcp](https://github.com/olaservo/skilljack-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-olaservo-skilljack-mcp-skilljack-docs - Seller: https://agentstack.voostack.com/s/olaservo - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.