<p align="center">
  <img src="https://img.shields.io/pypi/v/skillforge-mcp?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI" alt="PyPI"/>
  <img src="https://img.shields.io/badge/MCP-Server-blueviolet?style=for-the-badge" alt="MCP Server"/>
  <img src="https://img.shields.io/badge/python-≥3.10-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python"/>
  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License"/>
  <img src="https://img.shields.io/github/stars/CatVinci-Studio/skillForge?style=for-the-badge&logo=github" alt="Stars"/>
</p>

<h1 align="center">🛠️ SkillForge</h1>

<p align="center">
  <strong>An MCP server that makes your AI agent learn and evolve — one skill at a time.</strong>
</p>

<p align="center">
  <em>Skills are reusable instructions that get better with every conversation.</em>
</p>

<p align="center">
  <a href="README_CN.md">🇨🇳 中文文档</a> · <a href="https://pypi.org/project/skillforge-mcp/">📦 PyPI</a> · <a href="https://github.com/CatVinci-Studio/skillForge/issues">🐛 Issues</a>
</p>

---

## ✨ What is SkillForge?

SkillForge is a **Model Context Protocol (MCP) server** that gives your AI agent a persistent, evolving skill library. Instead of repeating the same corrections and preferences every session, SkillForge captures them as **skills** — structured instructions that the agent loads and follows automatically.

> 💡 Think of it as **muscle memory for your AI** — it learns your conventions once and applies them forever.

### 🔄 The Feedback Loop

```
  👤 User gives feedback
        │
        ▼
  🔍 Agent detects improvement signal
        │
        ▼
  🔀 Triage: reuse / improve / create?
        │
        ▼
  ✏️ Draft skill following guide + plan
        │
        ▼
  🛡️ Validation gate (reject or pass)
        │
        ▼
  💾 Skill saved (auto-backed up)
        │
        ▼
  ✅ Next task uses improved skill
```

---

## 🚀 Quick Start

### 📦 Installation

```bash
# Install from PyPI (recommended)
pip install skillforge-mcp

# Or with uv
uv pip install skillforge-mcp
```

### ⚡ Run the Server

```bash
# Run directly
skillforge

# Or run without installing via uvx
uvx skillforge-mcp
```

### 🔌 Connect to Claude Code

Add to your MCP config:

```json
{
  "mcpServers": {
    "skillforge": {
      "command": "uvx",
      "args": ["skillforge-mcp"]
    }
  }
}
```

<details>
<summary>💡 Alternative: install from source</summary>

```bash
git clone https://github.com/CatVinci-Studio/skillForge.git
cd skillForge
pip install -e .
```

</details>

---

## 🧩 Architecture

```
src/skillforge/
├── 🏠 server.py              # MCP server definition & prompts
├── 📨 response.py            # Response formatting & feedback monitor
├── 🛡️ validator.py           # Hard validation gates for skill quality
├── 📁 skill_manager.py       # Core CRUD, backup, restore logic
├── 🔧 tools/
│   ├── 🔍 discovery.py       # list_skills, get_skill
│   ├── ✏️  crud.py            # save_skill (with validation), delete_skill
│   ├── 💾 backup.py          # list_backups, restore_skill
│   ├── 🔀 triage.py          # triage_skill_request
│   └── 🧠 optimization.py    # get_skill_guide, request_skill_optimization
└── 📖 guide/
    └── skill_writing_guide.md # Best practices for skill authoring
```

### 📂 Runtime Data

SkillForge stores its data in `~/.skillforge/`:

| Directory | Purpose |
|-----------|---------|
| `~/.skillforge/skills/` | 📚 Active skill library |
| `~/.skillforge/backups/` | 🗄️ Automatic version history |

> 🔒 Override with `SKILLFORGE_SKILLS_DIR` and `SKILLFORGE_BACKUP_DIR` environment variables.

---

## 🔧 Available Tools

| Tool | Description |
|------|-------------|
| 🔍 `list_skills` | List all skills — **mandatory first call** before any task |
| 📖 `get_skill` | Load full skill instructions by name |
| 🔀 `triage_skill_request` | Check existing skills before creating/improving — prevents duplication |
| 🧠 `request_skill_optimization` | Get a structured plan for skill improvement |
| 📖 `get_skill_guide` | Load the skill writing best practices guide |
| ✏️ `save_skill` | Create or update a skill — **validates and rejects if quality is insufficient** |
| 🗑️ `delete_skill` | Remove a skill (two-step confirmation, auto-backup) |
| 📋 `list_backups` | View version history for a skill |
| ⏪ `restore_skill` | Roll back to a previous version |
| 📊 `get_optimization_history` | View the feedback log that drove skill changes |

---

## 🛡️ Quality Gates (v0.2.0)

Unlike prompt-based quality control that depends on LLM compliance, SkillForge enforces quality through **hard validation gates** in `save_skill`:

| Check | Type | Rule |
|-------|------|------|
| 📏 Description length | ❌ Error | Must be ≥ 50 characters |
| 📏 Body length | ❌ Error | Must be 3–500 lines |
| 🔄 Description ≠ name | ❌ Error | Description must explain, not repeat the name |
| 🎯 Trigger conditions | ⚠️ Warning | Should include "when/whenever/use this skill..." |
| 🗣️ Rigid language | ⚠️ Warning | Prefer reasoning over "YOU MUST ALWAYS" imperatives |
| 📐 Description too long | ⚠️ Warning | Keep under 1000 chars, move details to body |

> 🔴 **Errors** block the save — fix them and retry.
> 🟡 **Warnings** allow the save but flag areas for improvement.

### 🔀 Skill Triage

Before creating a new skill, `triage_skill_request` returns all existing skills so the LLM can decide:

| Decision | Condition | Action |
|----------|-----------|--------|
| **REUSE** | Existing skill covers the need | Load it with `get_skill` |
| **IMPROVE** | Existing skill partially covers it | Optimize with `request_skill_optimization` |
| **CREATE** | No relevant skill exists | Create via `request_skill_optimization` |

---

## 📝 Skill Format

Each skill lives in its own directory as a `SKILL.md` file with YAML frontmatter:

```yaml
---
name: my-skill
description: >
  What this skill does and when to trigger it.
  Use this skill whenever the user asks for...
  Also activate when...
---

# Skill Instructions

Your markdown instructions here...
```

### 🏷️ Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | ✅ | Identifier (`lowercase-with-hyphens`, max 64 chars) |
| `description` | ✅ | Trigger conditions — WHAT it does + WHEN to use it (≥ 50 chars) |
| `disable-model-invocation` | ❌ | `true` = only user can invoke |
| `user-invocable` | ❌ | `false` = only LLM can invoke |
| `allowed-tools` | ❌ | Tools allowed without per-use approval |
| `context` | ❌ | `fork` = run in isolated sub-agent |

---

## 🧠 How Optimization Works

SkillForge continuously monitors conversations for improvement signals:

| Signal | Example | Action |
|--------|---------|--------|
| 🔴 **Correction** | "No, don't mock the database" | Update relevant skill |
| 🟡 **Preference** | "Always use snake_case" | Create or update skill |
| 🔵 **Pattern** | Same structure used 3+ times | Bundle into new skill |
| 🟢 **Explicit** | "Add this to the review skill" | Direct skill edit |

### 🔒 Safety Guarantees

- ✅ **Auto-backup** before every save and delete
- ✅ **One-click restore** from any backup timestamp
- ✅ **Path traversal protection** on all file operations
- ✅ **Atomic writes** with file locking for optimization logs
- ✅ **Hard validation gates** — quality enforced at the tool boundary, not by prompt

---

## 🌟 Why SkillForge?

| Without SkillForge | With SkillForge |
|---------------------|-----------------|
| 😤 Repeat the same corrections every session | 🧠 Agent remembers and applies automatically |
| 📋 Conventions scattered across docs | 📦 Single source of truth per topic |
| 🎲 Inconsistent agent behavior | ✅ Deterministic, skill-guided responses |
| 🔄 No learning from feedback | 📈 Skills evolve with every interaction |
| 🤞 Hope the LLM follows quality guidelines | 🛡️ Hard validation rejects low-quality skills |

---

## 🛣️ Roadmap

- [x] 🛡️ Hard validation gates for skill quality
- [x] 🔀 Skill triage to prevent duplication
- [ ] 🌐 Skill sharing & import from remote repositories
- [ ] 📊 Analytics dashboard for skill usage & effectiveness
- [ ] 🔗 Cross-skill dependency management
- [ ] 🧪 Skill testing framework with evaluation harness
- [ ] 🏪 Community skill marketplace

---

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

## 📄 License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

---

<p align="center">
  <strong>Built with ❤️ by <a href="https://github.com/CatVinci-Studio">CatVinci Studio</a></strong>
</p>

<p align="center">
  <em>Forging better AI, one skill at a time. 🔨</em>
</p>