skillforge-mcp 0.1.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.

---

✨ 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
        │
        ▼
  🤖 Sub-agent optimizes the skill
        │
        ▼
  💾 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
├── 📁 skill_manager.py       # Core CRUD, backup, restore logic
├── 🔧 tools/
│   ├── 🔍 discovery.py       # list_skills, get_skill
│   ├── ✏️  crud.py            # save_skill, delete_skill
│   ├── 💾 backup.py          # list_backups, restore_skill
│   └── 🧠 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	Who Calls It
🔍 list_skills	List all skills (mandatory first call!)	🤖 Agent
📖 get_skill	Load full skill instructions	🤖 Agent
✏️ save_skill	Create or update a skill	🤖 Sub-agent
🗑️ delete_skill	Remove a skill (with confirmation)	🤖 Sub-agent
📋 list_backups	View version history for a skill	🤖 Agent
⏪ restore_skill	Roll back to a previous version	🤖 Agent
📖 get_skill_guide	Load the skill writing guide	🤖 Sub-agent
🧠 request_skill_optimization	Trigger skill improvement	🤖 Agent
📊 get_optimization_history	View optimization log	🤖 Agent

---

📝 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.
  Be specific about trigger contexts.
---

# 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
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
• ✅ Sub-agent isolation — skill edits don't interrupt your main task

---

🌟 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

---

🛣️ Roadmap

• 🌐 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. 🔨