open-skills-mcp 0.2.0

A universal MCP skill runtime executing in a secure Docker sandbox.

Secure, Standardized, "Copy-Paste" Compatible Agent Skills Runtime

English | 简体中文

---

"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 a generic skills runtime based on the Model Context Protocol (MCP). It aims to enable any MCP-supported AI application (such as Google Antigravity, Cursor, Windsurf) to quickly access popular Skills capabilities and securely execute complex tasks, while addressing 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

Feature	Description
📦 Out of the Box	Copy-Paste Compatibility. Simply copy folders from anthropics/skills or community Skills without modifying a single line of code. The smart adapter handles path mapping automatically.
🛡️ Sandbox Security	All code runs inside a Docker Container that is disposed of after use. Agents can only access the mounted /skills and /share directories, keeping your host system absolutely safe.
🔋 Batteries Included	Pre-installed with mainstream dependencies like Python, Node, Pandas, Numpy, LibreOffice, etc. Say goodbye to pip/npm install troubles and focus on the task.

🔐 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 (Put your Skills here)
├── 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. List and view detailed documentation for available skills (with automatic sandbox path injection).
• 💻 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.

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": [
        "--from", "open-skills-mcp", "open-skills",
        "--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"
      }
    }
  }
}

Known Limitation: When running with uvx, closing the IDE might not correctly propagate the exit signal, leaving the Docker container running. If this happens, please manually run docker rm -f open-skills-sandbox or delete it via Docker Desktop.

---

🔧 Development Installation

If you are a developer and want to run or debug from source code:

Running Modes

Mode A: SSE (Recommended for Development/Debugging)

Start the HTTP service:

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

SSE Client Configuration:

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

Mode B: Stdio (Local Source Run)

If you don't use uvx and want to run the source code directly:

Install

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

Windows:

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

macOS / Linux:

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

---

Made with ❤️ for the Agentic Future

📄 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