DEV Community

femto Zheng
femto Zheng

Posted on

Minion Skills: An Open Source Implementation of Claude Code Skills

#agents #opensource #architecture #ai

Introduction

Claude recently released an exciting feature—the Skills system. It allows AI Agents to dynamically load specialized capabilities, “learning” on-demand skills for handling professional documents like PDFs, Excel files, and PowerPoint presentations.

As an open source enthusiast, I immediately recognized the value of this design and implemented a complete open source version in the Minion framework. This article introduces the design philosophy of Skills and the details of my open source implementation.

What Problem Do Skills Solve?

When developing AI Agents, there’s a core contradiction:

Limited Context Window vs. Unlimited Capability Requirements

The traditional approach is to cram all tools and instructions into the system prompt:

System Prompt = Base Instructions + All Tool Descriptions + All Domain Knowledge
            = 50K+ tokens
            = High Latency + High Cost + Low Efficiency
Enter fullscreen mode Exit fullscreen mode

Worse, users typically only need a small portion of these capabilities. When a user asks “help me process this PDF,” the system loads context for Excel, databases, code, and all other capabilities.

The Core Philosophy of Skills

Claude Code’s Skills design is inspired by a simple analogy:

Human experts don’t keep all knowledge in their heads—they consult manuals and invoke specialized knowledge when needed.

The Skills system gives AI Agents this same capability:

User Request → Agent identifies need for PDF skill → Dynamically loads PDF processing instructions
                                                  → Executes specialized task
                                                  → Returns result
Enter fullscreen mode Exit fullscreen mode

Minion’s Open Source Implementation

After seeing Claude Code’s Skills design, I decided to implement a fully compatible open source version in the Minion framework, allowing more developers to use this feature.

1. Skill Definition: Simple Yet Powerful

Each Skill is simply a directory containing a SKILL.md file:

.minion/skills/
├── pdf/
│   ├── SKILL.md          # Skill definition and instructions
│   ├── references/       # Reference materials
│   ├── scripts/          # Helper scripts
│   └── assets/           # Resource files
├── xlsx/
│   └── SKILL.md
└── docx/
    └── SKILL.md
Enter fullscreen mode Exit fullscreen mode

SKILL.md uses YAML frontmatter + Markdown body format:

---name: pdfdescription: PDF document processing skill, supports text extraction, table parsing, form filling, etc.license: MIT---## When Using This SkillYou now have professional PDF processing capabilities...### Text ExtractionUse the pypdf2 library for text extraction:...### Table RecognitionUse tabula-py for table extraction:...
Enter fullscreen mode Exit fullscreen mode

2. Intelligent Discovery: Load on Demand

The Skill Loader searches for available skills in multiple locations:

class SkillLoader:
    SKILL_DIRS = [
        ".claude/skills",   # Claude Code compatible        ".minion/skills",   # Minion native    ]
    def get_search_paths(self):
        paths = []
        # Project-level takes priority        for skill_dir in self.SKILL_DIRS:
            paths.append((self.project_root / skill_dir, "project"))
        # User-level is secondary        for skill_dir in self.SKILL_DIRS:
            paths.append((self.home_dir / skill_dir, "user"))
        return paths
Enter fullscreen mode Exit fullscreen mode

This layered design provides flexibility:

  • Project-level Skills: Specialized capabilities for specific projects
  • User-level Skills: General capabilities across projects
  • Priority mechanism: Project-level overrides user-level, allowing customization
  • Compatibility: Supports both .claude/skills and .minion/skills paths

3. Elegant Registry: Fast Lookup 

class SkillRegistry:
    def register(self, skill: Skill) -> bool:
        """Register skill, higher priority overrides lower priority"""        existing = self._skills.get(skill.name)
        if existing:
            priority = {"project": 0, "user": 1, "managed": 2}
            if priority[skill.location] >= priority[existing.location]:
                return False  # Higher priority skill with same name already exists        self._skills[skill.name] = skill
        return True    def generate_skills_prompt(self, char_budget=10000):
        """Generate available skills list, control context consumption"""        # Smart truncation to stay within budget        ...
Enter fullscreen mode Exit fullscreen mode

4. Skill Tool: Execution Entry Point 

class SkillTool(BaseTool):
    name = "Skill"    description = "Dynamically load and execute specialized skills"    def execute_skill(self, skill: str) -> Dict[str, Any]:
        skill_obj = self.registry.get(skill)
        if skill_obj is None:
            return {
                "success": False,
                "error": f"Unknown skill: {skill}",
                "available_skills": self.registry.list_all()[:10]
            }
        # Get the skill's complete instructions        prompt = skill_obj.get_prompt()
        return {
            "success": True,
            "skill_name": skill_obj.name,
            "prompt": prompt,  # Inject into conversation context        }
Enter fullscreen mode Exit fullscreen mode

Real-World Results

Scenario 1: Processing Complex PDF Reports 

User: Help me analyze this financial report report.pdf, extract all table data

Agent:
1. Identifies need for PDF processing capability
2. Calls Skill("pdf") to load PDF skill
3. Receives professional PDF processing instructions
4. Uses pypdf2 to extract text
5. Uses tabula-py to extract tables
6. Returns structured data
Enter fullscreen mode Exit fullscreen mode

Scenario 2: Batch Processing Excel Files 

User: Merge these 10 Excel files and generate summary statistics

Agent:
1. Calls Skill("xlsx") to load Excel skill
2. Receives professional usage of pandas, openpyxl, etc.
3. Batch reads files
4. Merges data, calculates statistics
5. Generates new Excel report
Enter fullscreen mode Exit fullscreen mode

Performance Comparison

Metric Traditional Approach Skills Approach
Base Context 50K tokens 10K tokens
PDF Task Context 50K tokens 10K + 3K tokens
Initial Response Latency Longer Shorter
Specialized Task Quality Average More Precise

Design Highlights

1. Declarative Definition

Skills are defined through Markdown, allowing even non-technical users to create and maintain them:

---name: data-analysisdescription: Data analysis skill---## Data Cleaning Steps1. Check for missing values2. Handle outliers...
Enter fullscreen mode Exit fullscreen mode

2. Resource Binding

Skills can include reference materials, scripts, and other resources:

skill_obj.get_prompt()
# Returns:
# Loading: pdf
# Base directory: /Users/xxx/.minion/skills/pdf
#
# [Skill content, can reference references/api_doc.md etc.]
Enter fullscreen mode Exit fullscreen mode

3. Version and Source Tracking 

@dataclassclass Skill:
    name: str    description: str    content: str    path: Path
    location: str  # project, user, managed    license: Optional[str]
    metadata: Dict[str, Any]
Enter fullscreen mode Exit fullscreen mode

Why Create an Open Source Implementation?

Claude Code’s Skills is an excellent design, but it’s closed source and tied to the Claude ecosystem. My reasons for creating an open source version:

  1. LLM Agnostic: Minion supports multiple LLM backends (Claude, GPT-4, open source models)—Skills capabilities shouldn’t be locked to a single vendor
  2. Customizability: Open source implementation allows deep customization to meet special requirements
  3. Community Contributions: Open source enables more people to contribute Skills, forming a skill ecosystem
  4. Learning Value: Through implementation, gain deep understanding of this architecture’s design essence

Future Directions

1. Skills Marketplace

Imagine a Skills Marketplace where developers can publish and share specialized skills:

minion skill install data-science-toolkit
minion skill install legal-document-analysis
Enter fullscreen mode Exit fullscreen mode

2. Intelligent Recommendations

Automatically recommend relevant skills based on user history and current tasks:

def recommend_skills(user_request, history):
    # Analyze request content    # Match most relevant skills    # Preload potentially needed skills    ...
Enter fullscreen mode Exit fullscreen mode

3. Skill Composition

Multiple skills working together:

# Analyze data in PDF, generate Excel reportskills_used = ["pdf", "xlsx", "data-visualization"]
Enter fullscreen mode Exit fullscreen mode

4. Self-Learning Skills

Agent automatically generates new skills after completing complex tasks for future use:

async def learn_skill_from_session(session_log):
    # Analyze successful task execution process    # Extract reusable patterns and instructions    # Generate new SKILL.md    ...
Enter fullscreen mode Exit fullscreen mode

Video Demonstrations

Conclusion

Claude Code’s Skills system embodies a core design philosophy:

Don’t try to make AI know everything—instead, let it know where to find answers when needed.

This “expert system” mindset evolves AI Agents from “generalists” to “generalists who can quickly become experts.”

Through Minion’s open source implementation, this capability is now available to a broader developer community, not limited to specific LLM vendors or closed ecosystems.

Try it out and contribute:

Let’s build a more open and intelligent AI Agent ecosystem together.

Previous Articles:

Minion Framework Already Implements PTC: Agent Architecture Beyond Traditional Tool Calling

Top comments (0)