open-skills-mcp 0.2.3

"Open Skills" was born to solve the dependency hell where Claude Code's Skills functionality might fail in various differentiated environments, and the security risks of running unknown community Skill code directly on the local machine. I have perfectly replicated Anthropic's powerful Skills protocol as a plug-and-play MCP mode and encapsulated it in a secure, isolated, out-of-the-box Docker sandbox, allowing you to enjoy the power of Skills in any AI application that supports MCP.

🚀 Mission

Open Skills is NOT a specific "Skill", but a true universal "Agent Skills" module.

Following Anthropic's release of Claude Code, its powerful "Skills" extension mechanism left a strong impression. However, these Skills are currently limited to the official Claude Code CLI tool. Open Skills was born to break this wall, replicating Anthropic's Skills protocol as a generic MCP (Model Context Protocol) service.

This means: You can now directly load and run the community's rich Skills resources in Trae, Windsurf, or any MCP-supported AI application with a workspace-less environment, while enjoying enterprise-grade Docker sandbox isolation.

🆚 Comparison (Claude Code vs Open Skills)

🛠️ How it works

Open Skills is not simply "executing scripts", but a complete replication of the Agent Skills lifecycle:

1. Discovery: Attributes to manage_skills tool to read Skill header metadata, allowing the Agent to know "what capabilities I have" with minimal Token consumption.
2. Progressive Loading: When the Agent decides to use a skill, it calls manage_skills again to retrieve the full SOP (Standard Operating Procedure) and script instructions, mirroring the official "Progressive Disclosure" mechanism.
3. Execution: The Skill documentation (SKILL.md) itself serves as a high-quality execution plan. The Agent follows the document steps strictly within the Docker sandbox calling execute_command to complete tasks.

This design perfectly solves two major pain points:

1. Dependency Hell: No more need to configure complex Python environments for every script, or have an agent install a massive amount of unknown dependency packages on your local machine due to execution failures. The sandbox comes pre-installed with necessary dependencies and grants the agent temporary permission to install packages, purifying your local environment.

2. Security Risks: Completely eliminate the risk of AI modifying system files or executing malicious code. The sandbox environment mounts your /skills (read-only) directory and workspace /share (read-write) directory. Malicious code runs within the sandbox environment and cannot modify or read important files outside of the local workspace.

✨ Features

🔐 Architecture & Design

Open Skills is carefully designed to balance security and usability:

1. The Agent Model

The Agent runs as a agent (uid=1000) user inside the container, not Root.

• Permission Boundary: The capability to destroy the system (e.g., apt-get, rm -rf /bin) is stripped, but all permissions for creative work (code read/write, script execution, pip/npm install) are retained.
• File Ownership: The agent user has full read/write access to the /share workspace via Docker mounting. This ensures files generated by the Agent are owned by a regular user on the host, preventing "root user only" file locking issues.

2. Smart Node.js Setup

To solve the classic deadlock where "Agent wants to install a package but lacks permission", we used an Environment Injection design:

• Seamless Installation: Configured NPM_CONFIG_PREFIX="/share/.npm-global". When the Agent executes npm install package, the package is automatically installed under /share where it has write permissions. The Agent thinks it's installing globally, but it's actually installing locally—Zero Config, Zero Error.

📂 Directory & Architecture

open-skills/
├── open_skills/               # [Core] Core logic package
│   ├── cli.py                 # MCP Server entry point
│   ├── sandbox.py             # Docker container manager
│   ├── Dockerfile             # Batteries-included image definition
│    ├── skills/                # Skills Library (Only for dev; UVX mounts any dir via args)
├── docs/                      # [Docs] Documentation & Guides
│   ├── EN/                    # English Documentation
│   └── ZH/                    # Chinese Documentation
├── README.md                  # English Documentation
├── README_zh.md               # Chinese Documentation
└── LICENSE                    # MIT License

🛠️ Toolbox

Once connected to the Open Skills MCP service, your Agent gains the following superpowers:

• 📚 manage_skills: Skills Librarian. Adopts a Progressive Loading mechanism: first reads the header descriptions of all Skills to let the Agent quickly perceive capabilities (list), then reads the full documentation as execution SOP upon selection (inspect). The Skill documentation itself IS the plan, so no extra planning mode is needed.
• 💻 execute_command: Execution Engine. Run Bash commands (Python, Node, Shell, etc.) inside the secure container.
• 📂 read_file / write_file: File Operations. Securely read and write files in the workspace (read_file supports pagination).
• 🧱 append_file: Large File Append. Append content in chunks to bypass LLM output token limits.
• ☁️ upload_to_s3 / download_from_s3: Cloud Transfer. After configuring .env, the agent can automatically transfer files to and from S3.
• 👀 list_directory: Environment Perception. Securely list directory contents in the workspace, needed for non-IDE environments.

💡 Best Practices

Adapting Agents to the Sandbox Environment

Since we have completely decoupled the system-level execution environment of Skills and redesigned the sandbox mechanism, I suggest adding a Prompt Secret to your Agent Prompt to help it better master skills and the sandbox environment. (Optional, enable if you feel MCP service performance is suboptimal)

Agent Guide (MD) > Insert this prompt into your original System Prompt.

This solves:

1. Spatial Awareness: Clarifies that /share corresponds to the current directory.
2. Standard Procedure: Enforces the SOP of "Read Docs -> Write Code -> Run Tests".
3. Permission Confidence: Gives the Agent confidence to execute commands within the sandbox.

⚠️ About "Meta-Skills"

Please test in the sandbox environment before transferring. Tools like skill-creator that let AI write skills generate Skills , That you need to manually transfer from the workspace to the /skills directory.

• Risk: AI-generated scripts have uncertainties; running them directly on the local machine may pose risks.
• Recommendation: Human reviews code, AI executes operations.

⚡ Quick Start

1. Prerequisites

Since Open Skills runs in a secure, isolated Docker sandbox, this is a mandatory step:

1. Install and start Docker Desktop.

   v0.2.2 Update: Lazy Connection is supported. You can start the MCP service without Docker (entering Offline Mode), and connect to Docker only when the Agent actually executes a task. This prevents IDE crashes caused by service startup failures.

2. Prepare the Image (Choose One):

   • Option A: Pull Official Image (Recommended)

     docker pull forever17/open-skills:latest
     

   • Option B: Build Manually (For Developers)

     Manually modify the Dockerfile to pre-install your most used dependency packages, then rebuild the image.

     # Run in the source code directory
     docker build -t open-skills:latest open_skills/
     

2. Configuration

We strongly recommend using uvx (no need to manually install Python environment) to run directly.

🚀 Recommended Configuration (via uvx)

Add to your mcp_config.json (Google Antigravity) or any AI tool that supports the MCP protocol:

{
  "mcpServers": {
    "open-skills": {
      "command": "uvx",
      "args": [
        "open-skills-mcp",
        "--skills-dir", "E:\\Your_Projects\\skills",  // [Required] Mount local Skills directory
        "--work-dir", "E:\\Your_Projects\\workspace"      // [Required] Specify workspace directory
      ],
      "env": {
        // [Optional] If S3 features are needed
        "S3_BUCKET": "your_bucket",
        "S3_REGION": "default",
        "S3_ENDPOINT": "https://***.com",
        "S3_CUSTOM_DOMAIN": "https://***.com",
        "S3_ACCESS_KEY": "your_key",
        "S3_SECRET_KEY": "your_secret"
      }
    }
  }
}

• Parameters are Mandatory: "--skills-dir" Mount local Skills directory (Any location) Required, "--work-dir" Manually specify your workspace directory (Must match your IDE workspace) Required.

• Known Limitation: When running in the "uvx" mode, closing the IDE may fail to properly transmit the exit signal, resulting in residual Docker containers. When switching workspaces, you must manually clean up the container using "docker rm -f open-skills-sandbox" or click to delete it in Docker Desktop. The container will be automatically recreated after restarting the client.

• IDE Task Mode: It is recommended NOT to use Planning, Task, or Spec based Agent task modes. These modes enforce a defined task flow. Skills need to be executed strictly according to SKILL.md. SKILL.md IS the definition of the Plan that must be strictly adhered to and does not need to be redefined. This is often the culprit when Agents in Claude Code occasionally fail to follow the SKILL.md flow.

uvicorn open_skills.cli:mcp.sse_app --port 8000

{
  "mcpServers": {
    "open-skills": {
      "serverUrl": "http://localhost:8000/sse"
    }
  }
}

git clone https://github.com/justForever17/open-skills.git
cd open-skills
pip install -e .

{
  "mcpServers": {
    "open-skills": {
      "command": "python",
      "args": ["-m", "open_skills.cli"],
      "cwd": "E:\\Projects\\open-skills" // Source code directory
    }
  }
}

{
  "mcpServers": {
    "open-skills": {
      "command": "python3",
      "args": ["-m", "open_skills.cli"],
      "cwd": "/path/to/open-skills"
    }
  }
}

📄 License

This project is licensed under the MIT License.

💖 Sponsorship

Maintaining open source projects is hard. If you find open-skills helpful, please consider buying me a coffee!

Platform	Link	Payment Methods
Aifadian (Afdian)		WeChat, Alipay