open-skills-mcp 0.1.0

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

Open Skills

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

English | 简体中文

---

"Open Skills" was born to solve the security and dependency nightmares of running Agent code directly. We perfectly replicate Anthropic's powerful Skills protocol and encapsulate it in a secure, isolated, out-of-the-box Docker sandbox.

🚀 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 Claude Desktop, Cursor, Windsurf) to securely execute complex tasks, while addressing two major pain points:

1. Dependency Hell: No more configuring complex Python environments for every script.
2. Security Risks: Completely eliminate the risk of AI modifying system files or executing malicious code on your host machine.

✨ Features

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

🔐 Architecture & Design

Open Skills is carefully verified 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) 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 (cwd).
• ☁️ upload_to_s3 / download_from_s3: Cloud Transfer. After configuring .env, the agent can automatically transfer files to and from S3.

💡 Best Practices

Adapting Agents to the Sandbox Environment

Since we have completely decoupled the system-level execution environment of Skills, redesigned the sandbox mechanism, and converted it into an MCP tool, I suggest adding a Prompt Secret to your Agent Prompt to help it better master the sandbox environment.

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"

Do not use tools like skill-creator (that let AI write skills) in production.

• Risk: Bypasses security reviews.
• Recommendation: Human reviews code, AI executes operations.

⚡ Quick Start

1. Build Image (Required)

This is a mandatory step. To ensure fast startup, the image must be pre-built:

docker build -t open-skills:latest open_skills/

2. Install

cd apps/open-skills
pip install -e .

3. Configure MCP

We recommend using SSE (Server-Sent Events) mode as it supports remote connections and is easier to debug.

🚀 Mode A: SSE (Recommended - HTTP Server)

First, start the HTTP server:

# Requires uvicorn (pip install uvicorn)
uvicorn open_skills.cli:mcp.sse_app --port 8000

Then, configure your client:

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

📁 Workspace Binding

By default, the workspace is bound to the current directory where you run uvicorn. To specify a different directory, use the .env file in the project root:

1. Copy template: cp env.template .env
2. Update config:

# .env
HOST_WORK_DIR="E:\Your_Projects"

Mode B: Stdio (Legacy - Claude Desktop / VSCode)

This is the standard mode where the server starts automatically with the host app.

Critical Point: You MUST explicitly specify cwd (Current Working Directory), otherwise generated files will end up in your home directory!

Windows

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "open-skills": {
      "command": "python",
      "args": ["-m", "open_skills.cli"],
      "cwd": "E:\\Your_Projects" 
    }
  }
}

macOS / Linux

{
  "mcpServers": {
    "open-skills": {
      "command": "python3",
      "args": ["-m", "open_skills.cli"],
      "cwd": "/home/user/projects/your-project"
    }
  }
}

---

Made with ❤️ for the Agentic Future

📄 License

This project is licensed under the MIT License.