Skillz

The Skillz MCP Server is a single-file Python script that exposes Claude-style skills to any MCP client.

It works by recursively scanning a directory for skills, each defined by a SKILL.md file, and then registers them as distinct tools.

You can use it to quickly connect a folder of local scripts to an AI model for tasks like rapid prototyping or building a personal AI assistant.

Features

• 📂 Recursive Skill Discovery: Automatically finds and loads every SKILL.md file within a specified root directory and its subdirectories.
• 🛠️ Automatic Tool Registration: Creates a unique MCP tool for each skill discovered, using the skill’s name to generate the tool’s slug.
• ⚡ Helper Script Execution: Can run scripts associated with a skill, which is useful for performing actions on the local machine.
• 📡 Flexible Transport Options: Communicates over stdio by default, with support for http and Server-Sent Events (sse) for network-based clients.
• 📄 Single-File Simplicity: The entire server is contained in a single skillz.py file, requiring no complex setup or installation.

How to Use It

1. Organize your skills. Create a root directory and then a subdirectory for each skill. Inside each skill’s subdirectory, you need a SKILL.md file that begins with YAML front-matter.

2. Start the server.

The server defaults to using stdio for communication. If your client requires a network connection, you can specify a different transport.

uv run skillz.py /path/to/your/skills --verbose

3. To check if the server is correctly parsing your skills without starting the transport, use the --list-skills flag:

uv run skillz.py /path/to/your/skills --list-skills

4. Options and Parameters

• /path/to/skills: The required argument specifying the root directory of your skills.
• --transport: Sets the communication method. Accepts stdio (default), http, or sse.
• --host: Defines the listening host address for network transports (e.g., 127.0.0.1).
• --port: Defines the listening port for network transports (e.g., 8080).
• --path: Specifies the URL path for network transports (e.g., /mcp).
• --list-skills: Validates and lists discovered skills without activating the server.
• --verbose: Enables more detailed logging output.

5. One important detail is that Skillz returns absolute file paths for resources but does not register MCP resources for file access. Your client application must handle reading files directly from the disk.

FAQS

Q: How does Skillz handle nested skill directories?
A: The server recursively walks through all subdirectories of your specified skills root, loading every SKILL.md file it encounters. This means you can organize skills in any directory structure that makes sense for your workflow.

Q: How are tool names generated from skill names?
A: The server converts the skill’s name field to a URL-friendly slug format. For example, a skill named “Data Analysis Tools” would become available as the tool data-analysis-tools.

Q: Does Skillz sandbox the executed scripts?
A: No, not in a meaningful security sense. It executes helper scripts in a temporary directory, but there are no further security restrictions. You should only use this with skills you have written yourself or completely trust. For any untrusted code, run the entire server inside a container or a more secure environment.

Q: Why does the server only return file paths instead of file content?
A: This design keeps the server minimal and is intended for local-first workflows where the MCP client has direct filesystem access. The responsibility for reading file content is left to the client.

Q: What are Claude Skills?
A: Claude Skills are customizable, reusable workflows that you can create to teach Claude how to perform specialized tasks consistently. They package instructions, scripts, and resources into a folder that Claude can load and apply when the task is relevant, making it more efficient for repetitive or complex jobs like generating reports, following brand guidelines, or analyzing data.