skillforge-mcp 0.2.0

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

🛠️ 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"]
    }
  }
}

💡 Alternative: install from source

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

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:

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

• 🛡️ 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. 🔨