DOCSEARCHbyAlgolia
Submit Docs

skillz

repository·main·Indexed 19 days ago

https://github.com/intellectronica/skillz

An MCP (Model Context Protocol) server that converts Claude-style skills, defined by SKILL.md files and resources, into callable tools for MCP-compatible agents such as Cursor, Copilot, and Gemini CLI. It supports skill discovery via directories, ZIP archives, and nested directories, providing a bridge to expose instructions and resources to AI agents.

Tokens
3.3K
Snippets
10
Records
15
Agent score
64%

What's inside skillz

  1. How Skillz skill discovery and packaging works

    main

    Skillz discovers skills within a root directory (defaulting to ~/.skillz).

    Skill Structure

    Each skill must contain a SKILL.md file with YAML front matter describing the skill. Any other files in the skill directory (scripts, datasets, etc.) are exposed as downloadable resources for the agent.

    Supported Formats

    Skillz is more flexible than Claude Code and supports three main layouts:

    1. Directories: A folder containing SKILL.md and helper files.
    2. ZIP Archives: A .zip or .skill file containing SKILL.md at the root or inside a single top-level directory.
    3. Nested Directories: Unlike Claude Code, Skillz can discover skills organized in nested subdirectories.

    Example Directory Layout:

    ~/.skillz/
├── summarize-docs/
│   ├── SKILL.md
│   └── summarize.py
├── translate.zip
└── web-search/
    └── SKILL.md

    Note on Compatibility: If you need to share a skills directory with Claude Code, you must use a flat layout (no nested directories, no .zip or .skill files), as Claude Code only supports immediate subdirectories containing SKILL.md.

  2. Install and run Skillz as an MCP server

    main

    Skillz is an MCP server that converts Claude-style skills (SKILL.md plus resources) into callable tools for any MCP client.

    Using uvx (Recommended)

    To run the server using uvx, configure your agent with the following settings. By default, it looks for skills in ~/.skillz.

    {
  "skillz": {
    "command": "uvx",
    "args": ["skillz@latest"]
  }
}

    To specify a custom skills directory:

    {
  "skillz": {
    "command": "uvx",
    "args": ["skillz@latest", "/path/to/skills/directory"]
  }
}

    Using Docker (Isolated)

    For better isolation, run Skillz via Docker. You must mount your skills directory to /skillz inside the container.

    {
  "skillz": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-v",
      "/path/to/skills:/skillz",
      "intellectronica/skillz",
      "/skillz"
    ]
  }
}
    {
  "skillz": {
    "command": "uvx",
    "args": ["skillz@latest"]
  }
}

  3. Install the Gemini CLI extension

    main

    You can enable Anthropic-style Agent Skills in the Gemini CLI by installing the gemini-cli-skillz extension. This extension uses the Skillz MCP server to bridge the functionality.

    gemini extensions install https://github.com/intellectronica/gemini-cli-skillz

  4. Define a Skill using SKILL.md

    main

    A Skill is a package of instructions and resources. You can define a skill using either a directory or a .zip/.skill file. The core of a skill is a SKILL.md file containing YAML front matter and a Markdown body.

    Front Matter Requirements

    The YAML front matter must include name and description. Other optional fields include license and allowed_tools (which constrains which tools the agent should use).

    Example SKILL.md

    ---
name: Data Analyst
description: Specialized instructions for performing statistical analysis.
license: MIT
allowed_tools: [python_interpreter, sql_executor]
extra_info: some-value
---

# Instructions
When analyzing data, always check for outliers first...

  5. Skillz CLI Reference

    main

    The Skillz CLI follows the pattern: skillz [skills_root] [options].

    Use skillz --list-skills to verify which skills the server will expose before connecting it to your agent.

    | Flag / Option | Description |
| --- | --- |
| positional `skills_root` | Optional skills directory (defaults to `~/.skillz`). |
| `--transport {stdio,http,sse}` | Choose the FastMCP transport (default `stdio`). |
| `--host HOST` | Bind address for HTTP/SSE transports. |
| `--port PORT` | Port for HTTP/SSE transports. |
| `--path PATH` | URL path when using the HTTP transport. |
| `--list-skills` | List discovered skills and exit. |
| `--verbose` | Emit debug logging to the console. |
| `--log` | Mirror verbose logs to `/tmp/skillz.log` |

  6. Register Skill Resources in FastMCP

    main

    To make files within a skill available to an MCP client as resources, use register_skill_resources. This function iterates through the skill's files (excluding SKILL.md) and registers them with the FastMCP instance.

    Resources are identified by URIs in the format: resource://skillz/{skill-slug}/{path}

    Supported behaviors:

    • MIME Type: Automatically detected from file extensions.
    • Encoding: Files are served as UTF-8 text if possible; otherwise, they are base64-encoded binary data.
    • Zip Support: Works for both directory-based skills and compressed .zip/.skill files.
    from fastmcp import FastMCP
from skillz import SkillRegistry, register_skill_resources

mcp = FastMCP("My Server")
registry = SkillRegistry("path/to/skills")
registry.load()

# Registering the first discovered skill
for skill in registry.skills:
    resources = register_skill_resources(mcp, skill)
    # Note: register_skill_tool is typically used alongside this

  7. Run the Skillz MCP server via CLI

    main
    The skillz package includes entrypoints for running the server as a command-line application. Use main to start the server process and parse_args to handle command-line arguments. This is typically used when configuring the server in an MCP client (like Claude Desktop or Cursor).

  8. Manage Skills with SkillRegistry

    main

    The SkillRegistry is used to discover and manage skills located in a specific root directory.

    Key Methods

    • load(): Scans the root directory for skills. It prioritizes directory-based skills (those containing a SKILL.md) over zip-based skills (.zip or .skill files).
    • get(slug: str): Retrieves a specific Skill object by its slug.
    • skills: A property returning all discovered Skill objects.

    Skill Discovery Order

    1. Directories: If a directory contains SKILL.md, it is registered as a directory-based skill.
    2. Zip Files: If a .zip or .skill file is found, it is registered if it contains SKILL.md at the root or within a single top-level directory.
    from pathlib import Path
from skillz import SkillRegistry

registry = SkillRegistry(Path("~/.skillz"))
registry.load()

# Accessing a specific skill
my_skill = registry.get("data-analyst")
print(f"Loaded: {my_skill.metadata.name}")

  9. Register a Skill Tool in FastMCP

    main

    To expose a skill as a callable tool to an AI agent, use register_skill_tool. This creates a tool named after the skill's slug. When invoked with a task string, the tool returns:

    • instructions: The Markdown body from SKILL.md.
    • metadata: The skill's name, description, and allowed_tools.
    • resources: A list of available resource URIs.
    • usage: Guidance on how the agent should apply the instructions.

    Note: The tool is designed to provide instructions for the agent to follow, not to perform the task directly.

    from fastmcp import FastMCP
from skillz import SkillRegistry, register_skill_resources, register_skill_tool

mcp = FastMCP("Skillz Server")
registry = SkillRegistry("~/.skillz")
registry.load()

for skill in registry.skills:
    # 1. Register the files as resources
    resources = register_skill_resources(mcp, skill)
    # 2. Register the skill itself as a tool
    register_skill_tool(mcp, skill, resources=resources)

  10. Core Skillz API components

    main

    The skillz package provides the core abstractions for defining and managing skills within an MCP (Model Context Protocol) server.

    Key components include:

    • Skill: The primary class used to define a specific capability or tool.
    • SkillRegistry: A container used to manage and organize multiple Skill instances.
    • SkillMetadata: Data structures for describing skill properties.
    • build_server: A utility function to instantiate an MCP server using registered skills.
    • SkillError, SkillValidationError: Exception classes for handling errors during skill execution or definition.

  11. Use the fetch_resource tool as an MCP fallback

    main

    If your MCP client does not support native MCP resource fetching, you can use the fetch_resource tool to retrieve skill resources.

    Important: Only use this tool if native resource fetching is unavailable. If your client supports native MCP resources, use those instead.

    Supported URIs follow the format: resource://skillz/{skill-slug}/{path}. These URIs are typically provided in the resources field of skill tool responses.

    // Example tool call for a client without native resource support
{
  "name": "fetch_resource",
  "arguments": {
    "resource_uri": "resource://skillz/my-skill-slug/config.json"
  }
}

  12. Skillz CLI Reference

    main

    The following command-line arguments are available when running the Skillz MCP server:

    Positional Arguments:
  skills_root             Directory containing skill folders (default: [DEFAULT_SKILLS_ROOT])

Options:
  --transport [stdio|http|sse]  Transport to use when running the server (default: stdio)
  --host <host>           Host for HTTP/SSE transports (default: 127.0.0.1)
  --port <port>           Port for HTTP/SSE transports (default: 8000)
  --path <path>           Path for HTTP transport (default: /mcp)
  --verbose               Enable debug logging
  --log                   Write very verbose logs to /tmp/skillz.log
  --list-skills            List parsed skills and exit without starting the server