Skip to main content
Glama
dearsoft-skills
by dearsoft-bd
README.md
# DearSoft Skills Engine โšก

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0%20(stdlib%20only)-brightgreen.svg)]()
[![MCP Compatible](https://img.shields.io/badge/MCP-JSON--RPC%202.0-purple.svg)](https://modelcontextprotocol.io/)

> **A high-speed, zero-dependency Universal AI Agent Skills Hub, REST API microservice, and Model Context Protocol (MCP) server.**

Built by [DearSoft](https://dearsoft.com.bd) (Dhaka, Bangladesh). Designed to manage, sync, and serve AI agent runbooks (`SKILL.md`) seamlessly across **any AI platform** (Claude Code, OpenAI/ChatGPT, Google Gemini, Codex Desktop, Cursor) and **any web/SaaS application**.

---

## ๐ŸŒŸ Why DearSoft Skills Engine?

* **Zero External Dependencies**: Built 100% on Python standard library (`http.server`, `urllib`, `json`, `dataclasses`). Runs anywhere instantly without `pip install` issues.
* **Multi-Agent Sync**: 1-click symlink or copy to Claude Code (`~/.claude/skills`), Codex (`~/.codex/skills`), and Antigravity/Cursor (`~/.agents/skills`).
* **Universal LLM Prompting**: Formats any skill runbook into OpenAI, Google Gemini, or Anthropic system instruction payloads.
* **Secured REST API**: Multithreaded HTTP microservice protected with profile-based login, API keys, and RBAC category filtering.
* **Native MCP Server**: Exposes skills as tools directly to Cursor, Claude Desktop, Antigravity, and OpenClaw via standard JSON-RPC 2.0 over stdio.

---

## ๐Ÿš€ Quick Start

### 1. Installation

```bash
git clone https://github.com/dearsoft-bd/dearsoft-skills-engine.git
cd dearsoft-skills-engine
pip install -e .
```

### 2. CLI Usage

```bash
# List available skills
dearsoft-skills list

# Search skills
dearsoft-skills search "seo"

# Format skill prompt for Gemini API or OpenAI
dearsoft-skills get seo-audit --format gemini
dearsoft-skills get code-reviewer --format openai

# Sync skills to all local coding agents (Claude, Codex, Antigravity)
dearsoft-skills sync --target all

# Sync skills to a specific workspace
dearsoft-skills sync --dest ./my-app/.agents/skills
```

---

## ๐ŸŒ HTTP REST API Microservice

Run the microservice:

```bash
dearsoft-skills serve --port 8765
```

### Endpoints

| Method | Endpoint | Description |
| :--- | :--- | :--- |
| `GET` | `/health` | Service health check |
| `POST` | `/api/auth/login` | Login and receive a 7-day Bearer token |
| `GET` | `/api/skills` | List permitted skills for the authenticated profile |
| `GET` | `/api/skills/{name}/prompt` | Get ready-to-inject prompt formatted for target LLM |
| `POST` | `/api/skills/inject` | Inject skills directly into an existing chat request |
| `POST` | `/api/skills/{name}/render` | Render skill prompt with dynamic template variables |

### Example cURL Request

```bash
# 1. Login
curl -X POST "http://127.0.0.1:8765/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "dearsoft-admin", "password": "YOUR_PASSWORD"}'

# 2. Get prompt with Bearer token
curl "http://127.0.0.1:8765/api/skills/seo-audit/prompt?target_llm=gemini" \
  -H "Authorization: Bearer <TOKEN>"
```

---

## ๐Ÿ”Œ Model Context Protocol (MCP) Server

Add to your `claude_desktop_config.json`, `cursor_mcp.json`, or Antigravity `mcp_config.json`:

```json
{
  "mcpServers": {
    "dearsoft-skills": {
      "command": "dearsoft-skills",
      "args": ["mcp"]
    }
  }
}
```

Exposed MCP Tools:
- `list_skills(category)`
- `search_skills(query)`
- `get_skill_prompt(skill_name, target_llm)`

---

## ๐Ÿงช Running Tests

```bash
python3 -m unittest discover -s tests
```

---

## ๐Ÿ“„ License

Apache License 2.0. Developed by [DearSoft](https://dearsoft.com.bd).