open-skills-mcp 0.1.3

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

⚡ 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)

     # 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 claude_desktop_config.json (Claude Desktop) or mcp_config.json (VS Code):

{
  "mcpServers": {
    "open-skills": {
      "command": "uvx",
      "args": [
        "--from", "open-skills-mcp", "open-skills",
        "--skills-dir", "E:\\Your_Projects\\my-skills",  // [Optional] Mount local Skills directory
        "--work-dir", "E:\\Your_Projects\\workspace"      // [Optional] Specify workspace directory
      ],
      "env": {
        // [Optional] If S3 features are needed
        "S3_ENDPOINT": "...",
        "S3_ACCESS_KEY": "..."
      }
    }
  }
}

Note: Using uvx --from open-skills-mcp open-skills ensures that the open-skills command is correctly invoked even though the package name is open-skills-mcp. uvx will automatically download and run the latest version.

---

🔧 Development Installation

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

1. Install

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

2. 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:

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.