Metadata-Version: 2.4
Name: open-skills-mcp
Version: 0.1.3
Summary: A universal MCP skill runtime executing in a secure Docker sandbox.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: boto3
Requires-Dist: docker
Requires-Dist: mcp[cli]
Requires-Dist: python-dotenv
Requires-Dist: pyyaml
Requires-Dist: requests
Description-Content-Type: text/markdown

<div align="center">

# Open Skills

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

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![MCP Status](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io/)
[![Docker](https://img.shields.io/badge/Docker-Sandboxed-2496ED)](https://www.docker.com/)

[English](README.md) | [简体中文](README_zh.md)

</div>

---

> **"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)](https://modelcontextprotocol.io/). 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](https://github.com/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

```text
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)](docs/EN/AGENT_PROMPT.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](https://www.docker.com/products/docker-desktop/).
2. Prepare the Image (**Choose One**):

    * **Option A: Pull Official Image (Recommended)**

        ```powershell
        docker pull forever17/open-skills:latest
        ```

    * **Option B: Build Manually (For Developers)**

        ```powershell
        # 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):

```json
{
  "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.

---

<details>
<summary><strong>🔧 Development Installation</strong></summary>

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

### 1. Install

```powershell
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:

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

SSE Client Configuration:

```json
{
  "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**:

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

**macOS / Linux**:

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

</details>

---

<div align="center">
Made with ❤️ for the Agentic Future
</div>

## 📄 License

This project is licensed under the [MIT License](LICENSE).
