Metadata-Version: 2.4
Name: open-skills-mcp
Version: 0.1.0
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

### 1. Build Image (Required)

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

```powershell
docker build -t open-skills:latest open_skills/
```

### 2. Install

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

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

Then, configure your client:

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

```bash
# .env
HOST_WORK_DIR="E:\Your_Projects"
```

<details>
<summary><strong>Mode B: Stdio (Legacy - Claude Desktop / VSCode)</strong></summary>

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

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

#### macOS / Linux

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

</details>

---

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

## 📄 License

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