Skip to content
Back to search

open-skills

OpenSkills: Run Claude Skills Locally using any LLM

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/instavm--open-skills/badge.svg)](/listings/instavm--open-skills)

HTML

<a href="/listings/instavm--open-skills"><img src="/api/listings/instavm--open-skills/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** Mac with macOS and Apple Silicon (M1/M2/M3/M4/M5), Python 3.10+

git clone https://github.com/BandarLabs/open-skills.git
cd open-skills
chmod +x install.sh
./install.sh

Installation takes ~2 minutes. The MCP server will be available at `http://open-skills.local:8222/mcp`

**Install required packages** (use virtualenv and note the python path):

pip install -r examples/requirements.txt

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 357 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. [![Start](https://img.shields.io/github/stars/BandarLabs/open-skills?color=yellow&style=flat&label=%E2%AD%90%20stars)](https://github.com/BandarLabs/open-skills/stargazers)
  3. [![License](http://img.shields.io/:license-Apache%202.0-green.svg?style=flat)](https://github.com/BandarLabs/open-skills/blob/master/LICENSE)
  4. </div>
  5. ```
  6. ___ ____ _____ _ _ ____ _ _____ _ _ ____
  7. / _ \| _ \| ____| \ | | / ___|| |/ /_ _| | | | / ___|
  8. | | | | |_) | _| | \| | \___ \| ' / | || | | | \___ \
  9. | |_| | __/| |___| |\ | ___) | . \ | || |___| |___ ___) |
  10. \___/|_| |_____|_| \_| |____/|_|\_\___|_____|_____|____/
  11. ```
  12. # OpenSkills: Run Claude Skills Locally on Your Mac
  13. Anthropic recently announced [Skills for Claude](https://www.anthropic.com/news/skills) - reusable folders with instructions, scripts, and resources that make Claude better at specialized tasks. This tool lets you run these skills **entirely on your local machine** in a sandboxed environment.
  14. **What this means:** You can now process your files (documents, spreadsheets, presentations, images) using these specialized skills while keeping all data on your Mac. No uploads, complete privacy.
  15. > This tool executes AI-generated code in a truly isolated sandboxed environment on your Mac using Apple's native containers.
  16. ## Demo
  17. Watch Open-Skills in action with Gemini CLI:
  18. ![Open-Skills Demo with Gemini CLI](demo-gemini.gif)
  19. ## Why Run Skills Locally?
  20. - **Privacy:** Process sensitive documents, financial data
  21. - **Full Control:** Skills execute in an isolated container with VM-level isolation
  22. - **Compatibility:** Works with Claude Desktop, Gemini CLI, Qwen CLI, or any MCP-compatible tool
  23. - **Extensibility:** Import Anthropic's official skills or create your own custom skills
  24. ## Quick Start
  25. **Prerequisites:** Mac with macOS and Apple Silicon (M1/M2/M3/M4/M5), Python 3.10+
  26. ```bash
  27. git clone https://github.com/BandarLabs/open-skills.git
  28. cd open-skills
  29. chmod +x install.sh
  30. ./install.sh
  31. ```
  32. Installation takes ~2 minutes. The MCP server will be available at `http://open-skills.local:8222/mcp`
  33. **Install required packages** (use virtualenv and note the python path):
  34. ```bash
  35. pip install -r examples/requirements.txt
  36. ```
  37. ## Setup: Connect Your AI Tool
  38. This MCP server works with any MCP-compatible tool. All execution happens locally on your Mac.
  39. ### Option 1: Claude Desktop Integration
  40. Configure Claude Desktop to use this MCP server:
  41. 1. **Copy the example configuration:**
  42. ```bash
  43. cd examples
  44. cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json
  45. ```
  46. 2. **Edit the configuration file** and replace the placeholder paths:
  47. - Replace `/path/to/your/python` with your actual Python path (e.g., `/usr/bin/python3` or `/opt/homebrew/bin/python3`)
  48. - Replace `/path/to/open-skills` with the actual path to your cloned repository
  49. Example after editing:
  50. ```json
  51. {
  52. "mcpServers": {
  53. "open-skills": {
  54. "command": "/opt/homebrew/bin/python3",
  55. "args": ["/Users/yourname/open-skills/examples/claude_desktop/mcpproxy.py"]
  56. }
  57. }
  58. }
  59. ```
  60. 3. **Update Claude Desktop configuration:**
  61. - Open Claude Desktop
  62. - Go to Settings → Developer
  63. - Add the MCP server configuration
  64. - Restart Claude Desktop
  65. ### Option 2: OpenCode Configuration
  66. For OpenCode users, create `~/.config/opencode/opencode.json`:
  67. ![OpenCode Example](opencode-example.png)
  68. ```json
  69. {
  70. "$schema": "https://opencode.ai/config.json",
  71. "mcp": {
  72. "open-skills": {
  73. "type": "remote",
  74. "url": "http://open-skills.local:8222/mcp",
  75. "enabled": true
  76. }
  77. }
  78. }
  79. ```
  80. ### Option 3: Gemini CLI Configuration
  81. Edit `~/.gemini/settings.json`:
  82. ```json
  83. {
  84. "theme": "Default",
  85. "selectedAuthType": "oauth-personal",
  86. "mcpServers": {
  87. "open-skills": {
  88. "httpUrl": "http://open-skills.local:8222/mcp"
  89. }
  90. }
  91. }
  92. ```
  93. For system instructions, replace `~/.gemini/GEMINI.md` with [GEMINI.md](examples/gemini_cli/GEMINI.md)
  94. ### Option 3: Python OpenAI Agents
  95. Use this server with OpenAI's Python agents library:
  96. 1. **Set your OpenAI API key:**
  97. ```bash
  98. export OPENAI_API_KEY="your-openai-api-key-here"
  99. ```
  100. 2. **Run the client:**
  101. ```bash
  102. python examples/openai_agents/openai_client.py
  103. ```
  104. ### Other Supported Tools
  105. - **Qwen CLI:** Configure similar to Gemini CLI
  106. - **Kiro by Amazon:** See examples in this repository for configuration
  107. - **Any MCP client:** Point to `http://open-skills.local:8222/mcp`
  108. ## Example Use Cases
  109. Once configured, you can ask your AI to:
  110. - "Create a professional PowerPoint presentation from this markdown outline"
  111. - "Extract all tables from these 10 PDFs and combine into one Excel spreadsheet"
  112. - "Generate ASCII art logo for my project"
  113. - "Fill out this tax form PDF with data from my CSV file"
  114. - "Batch process these 100 images: crop to 16:9 and rotate 90 degrees"
  115. ## Adding New Skills
  116. You can extend this server with additional skills in two ways:
  117. ### Option 1: Import Anthropic's Official Skills
  118. Download skills from [Anthropic's skills repository](https://github.com/anthropics/skills/) and copy to:
  119. ```
  120. ~/.open-skills/assets/skills/user/<new-skill-folder>
  121. ```
  122. **Available Official Skills:**
  123. - Microsoft Word (docx)
  124. - Microsoft PowerPoint (pptx)
  125. - Microsoft Excel (xlsx)
  126. - PDF manipulation
  127. - Image processing
  128. - Slack GIF creator
  129. - And more...
  130. ### Skills Directory Structure
  131. Here's an example with 4 imported skills:
  132. ```shell
  133. ~/.open-skills/assets/skills/
  134. ├── public
  135. │ ├── image-crop-rotate
  136. │ │ ├── scripts
  137. │ │ └── SKILL.md
  138. │ └── pdf-text-replace
  139. │ ├── scripts
  140. │ └── SKILL.md
  141. └── user
  142. ├── docx
  143. │ ├── docx-js.md
  144. │ ├── LICENSE.txt
  145. │ ├── ooxml
  146. │ ├── ooxml.md
  147. │ ├── scripts
  148. │ └── SKILL.md
  149. ├── pptx
  150. │ ├── html2pptx.md
  151. │ ├── LICENSE.txt
  152. │ ├── ooxml
  153. │ ├── ooxml.md
  154. │ ├── scripts
  155. │ └── SKILL.md
  156. ├── slack-gif-creator
  157. │ ├── core
  158. │ ├── LICENSE.txt
  159. │ ├── requirements.txt
  160. │ ├── SKILL.md
  161. │ └── templates
  162. └── xlsx
  163. ├── LICENSE.txt
  164. ├── recalc.py
  165. └── SKILL.md
  166. ```
  167. ### Option 2: Create Your Own Skills
  168. Create a folder matching the structure shown above. The only mandatory file is `SKILL.md`. See [Anthropic's skills documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) for details.
  169. **Quick Method:**
  170. Ask Claude to generate a skill for you:
  171. > "Can you write a skill which creates ASCII art of words?"
  172. Claude will create the skill and offer a ZIP download. Place the ZIP file directly in `~/.open-skills/assets/skills/user` (no need to expand).
  173. **Manual Method:**
  174. Create your own skill folder structure:
  175. ```
  176. ~/.open-skills/assets/skills/user/my-custom-skill/
  177. ├── SKILL.md # Documentation and usage examples
  178. ├── scripts/ # Your Python/bash scripts
  179. │ └── process.py
  180. └── requirements.txt # (optional) Python dependencies
  181. ```
  182. ## How Folder Mapping Works
  183. This MCP server provides a compatibility layer that lets you run Claude's skills locally without modification:
  184. **Path Translation:**
  185. - Claude's path: `/mnt/user-data` → Local path: `/app/uploads`
  186. - Skills designed for Claude work locally without any changes
  187. **File Sharing - How to Share Files with Skills:**
  188. To share your local files with skills for processing:
  189. 1. **Place files in the outputs directory:**
  190. ```bash
  191. cp your-file.pdf ~/.open-skills/assets/outputs/
  192. cp your-image.png ~/.open-skills/assets/outputs/
  193. ```
  194. 2. **Files become available inside the container:**
  195. - Your files in `~/.open-skills/assets/outputs/` are automatically mounted
  196. - Skills can access them via `/mnt/user-data/` (the standard Claude path)
  197. - No manual copying or cloud uploads required
  198. 3. **Processed files appear in the same directory:**
  199. - Output files are saved back to `~/.open-skills/assets/outputs/`
  200. - You can access results immediately on your Mac
  201. **Skill Structure:**
  202. - No changes needed to imported skills
  203. - Original folder hierarchy and file organization remain identical
  204. - Import Claude skills and use them directly
  205. ## Live Demo: ASCII Art Skill
  206. Here's a real example using Gemini CLI:
  207. ```
  208. > /mcp
  209. Configured MCP servers:
  210. 🟢 open-skills - Ready (5 tools)
  211. Tools:
  212. - execute_python_code
  213. - get_skill_file
  214. - get_skill_info
  215. - list_skills
  216. - navigate_and_get_all_visible_text
  217. > can you generate ascii art for my project
  218. ✦ I will generate the ASCII art you desire. First, I must survey my available skills.
  219. ✓ list_skills (open-skills MCP Server)
  220. ✦ I have located a relevant skill: ascii-art. I will now retrieve its instructions.
  221. ✓ get_skill_info (open-skills MCP Server) {"skill_name":"ascii-art"}
  222. ✦ Your ASCII art is ready:
  223. ___ ____ _____ _ _ ____ _ _____ _ _ ____
  224. / _ \| _ \| ____| \ | | / ___|| |/ /_ _| | | | / ___|
  225. | | | | |_) | _| | \| | \___ \| ' / | || | | | \___ \
  226. | |_| | __/| |___| |\ | ___) | . \ | || |___| |___ ___) |
  227. \___/|_| |_____|_| \_| |____/|_|\_\___|_____|_____|____/
  228. Using: 1 GEMINI.md file | 3 MCP servers (ctrl+t to view)
  229. ```
  230. **What happened:**
  231. 1. AI discovered available skills via `list_skills`
  232. 2. Found the relevant `ascii-art` skill
  233. 3. Retrieved skill instructions with `get_skill_info`
  234. 4. Executed the skill locally in the sandbox
  235. 5. Returned results - all without uploading any data to the cloud
  236. ## Security
  237. Code runs in an isolated container with VM-level isolation. Your host system and files outside the sandbox remain protected.
  238. From [@apple/container](https://github.com/apple/container/blob/main/docs/technical-overview.md):
  239. >Each container has the isolation properties of a full VM, using a minimal set of core utilities and dynamic libraries to reduce resource utilization and attack surface.
  240. ## Architecture
  241. This MCP server consists of:
  242. - **Sandbox Container:** Isolated execution environment with Jupyter kernel
  243. - **MCP Server:** Handles communication between AI models and the sandbox
  244. - **Skills System:** Pre-packaged tools for common tasks (PDF manipulation, image processing, etc.)
  245. ## Available MCP Tools
  246. When connected, this server exposes these tools to your AI:
  247. - `execute_python_code` - Execute code in the sandbox
  248. - `get_skill_file` - Read skill files
  249. - `get_skill_info` - Get skill documentation
  250. - `list_skills` - List all available skills
  251. - `navigate_and_get_all_visible_text` - Web scraping with Playwright
  252. ## Learn More
  253. - **GitHub Repository:** [github.com/BandarLabs/open-skills](https://github.com/BandarLabs/open-skills)
  254. - **Anthropic Skills:** [github.com/anthropics/skills](https://github.com/anthropics/skills)
  255. - **Skills Documentation:** [docs.claude.com/skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview)
  256. - **Blog: Building Offline Workspace:** [instavm.io/blog/building-my-offline-workspace-part-2-skills](https://instavm.io/blog/building-my-offline-workspace-part-2-skills)
  257. - **Report Issues:** [github.com/BandarLabs/open-skills/issues](https://github.com/BandarLabs/open-skills/issues)
  258. ## Contributing
  259. We welcome contributions! If you create useful skills or improve the implementation, please share them with the community.
  260. ## License
  261. This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.