🛠️ SkillForge

An MCP server that makes your AI agent learn and evolve — one skill at a time.

Skills are reusable instructions that get better with every conversation.

🇨🇳 中文文档 · 📦 PyPI · 🐛 Issues

✨ 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

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

# Or with uv
uv pip install skillforge-mcp

⚡ Run the Server

# Run directly
skillforge

# Or run without installing via uvx
uvx skillforge-mcp

🔌 Connect to Claude Code

Add to your MCP config:

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

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

🧩 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/:

🔒 Override with SKILLFORGE_SKILLS_DIR and SKILLFORGE_BACKUP_DIR environment variables.

🔧 Available Tools

🛡️ 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:

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

📝 Skill Format

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

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

🧠 How Optimization Works

SkillForge continuously monitors conversations for improvement signals:

🔒 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?

🛣️ Roadmap

• 🛡️ Hard validation gates for skill quality
• 🔀 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 file for details.

Built with ❤️ by CatVinci Studio

Forging better AI, one skill at a time. 🔨