Minion Skills：Claude Skills 的开源实现

引言

Claude 最近推出了一个令人兴奋的特性——Skills 系统。它让 AI Agent 能够动态加载专业能力，按需"学习"处理 PDF、Excel、PPT 等专业文档的技能。

作为一个开源爱好者，我立刻意识到这个设计的价值，并在 Minion 框架中实现了完整的开源版本。本文将介绍 Skills 的设计理念，以及我的开源实现细节。

Skills 解决了什么问题？

在开发 AI Agent 的过程中，有一个核心矛盾：

Context Window 的有限性 vs 能力需求的无限性

传统做法是把所有工具、所有指令都塞进 system prompt：

System Prompt = 基础指令 + 所有工具描述 + 所有专业知识

        = 50K+ tokens
        = 高延迟 + 高成本 + 低效率

更糟的是，大多数时候用户只需要其中一小部分能力。当用户问"帮我处理这个 PDF"时，系统却加载了处理 Excel、数据库、代码等所有能力的上下文。

Skills 的核心理念

Claude Code 的 Skills 设计灵感来自一个简单的类比：

人类专家不是把所有知识都装在脑子里，而是在需要时查阅手册、调用专业知识。

Skills 系统让 AI Agent 也具备这种能力：

用户请求 → Agent 识别需要 PDF 技能 → 动态加载 PDF 处理指令

                             → 执行专业任务
                             → 返回结果

Minion 的开源实现

看到 Claude Code 的 Skills 设计后，我决定在 Minion 框架中实现一个完全兼容的开源版本，让更多开发者能够使用这一特性。

1. Skill 的定义：简洁而强大

每个 Skill 就是一个包含 SKILL.md 文件的目录：

.minion/skills/

├── pdf/

│ ├── SKILL.md # 技能定义和指令

│ ├── references/ # 参考资料

│ ├── scripts/ # 辅助脚本

│ └── assets/ # 资源文件

├── xlsx/

│ └── SKILL.md

└── docx/

└── SKILL.md

SKILL.md 采用 YAML frontmatter + Markdown body 的格式：

name: pdf

description: PDF 文档处理技能，支持文本提取、表格解析、表单填写等

license: MIT

当使用此技能时

你现在具备了专业的 PDF 处理能力...

文本提取

使用 pypdf2 库进行文本提取：

...

表格识别

使用 tabula-py 进行表格提取：

...

2. 智能发现：按需加载

Skill Loader 会在多个位置搜索可用技能：

class SkillLoader:

SKILL_DIRS = [
    ".claude/skills",   # 兼容Claude Code
    ".minion/skills",   # Minion原生
]


def get_search_paths(self):
    paths = []
    # 项目级优先
    for skill_dir in self.SKILL_DIRS:
        paths.append((self.project_root / skill_dir, "project"))
    # 用户级次之
    for skill_dir in self.SKILL_DIRS:
        paths.append((self.home_dir / skill_dir, "user"))
    return paths

这种分层设计带来了灵活性：

项目级 Skills：针对特定项目的专业能力

用户级 Skills：跨项目的通用能力

优先级机制：项目级覆盖用户级，允许定制化

兼容性：同时支持.claude/skills 和.minion/skills 路径

3. 优雅的注册表：快速查找

class SkillRegistry:

def register(self, skill: Skill) -> bool:
    """注册技能，高优先级覆盖低优先级"""
    existing = self._skills.get(skill.name)
    if existing:
        priority = {"project": 0, "user": 1, "managed": 2}
        if priority[skill.location] >= priority[existing.location]:
            return False  # 已有更高优先级的同名技能


    self._skills[skill.name] = skill
    return True


def generate_skills_prompt(self, char_budget=10000):
    """生成可用技能列表，控制context消耗"""
    # 智能截断，确保不超预算
    ...

4. Skill Tool：执行入口

class SkillTool(BaseTool):

name = "Skill"
description = "动态加载并执行专业技能"


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


    # 获取技能的完整指令
    prompt = skill_obj.get_prompt()


    return {
        "success": True,
        "skill_name": skill_obj.name,
        "prompt": prompt,  # 注入到对话上下文
    }

实际效果

场景 1：处理复杂 PDF 报告

用户：帮我分析这份财务报告 report.pdf，提取所有表格数据

Agent：

1. 识别需要 PDF 处理能力

2. 调用 Skill("pdf") 加载 PDF 技能

3. 获得专业的 PDF 处理指令

4. 使用 pypdf2 提取文本

5. 使用 tabula-py 提取表格

6. 返回结构化数据

场景 2：批量处理 Excel 文件

用户：把这 10 个 Excel 文件合并，并生成汇总统计

Agent：

1. 调用 Skill("xlsx") 加载 Excel 技能

2. 获得 pandas、openpyxl 等库的专业用法

3. 批量读取文件

4. 合并数据、计算统计

5. 生成新的 Excel 报告

性能对比

| 指标 | 传统方式 | Skills 方式 |

|------|---------|-----------|

| 基础 Context | 50K tokens | 10K tokens |

| PDF 任务 Context | 50K tokens | 10K + 3K tokens |

| 首次响应延迟 | 较长 | 较短 |

| 专业任务质量 | 一般 | 更精准 |

设计亮点

1. 声明式定义

技能通过 Markdown 定义，非技术人员也能创建和维护：

name: data-analysis

description: 数据分析技能

数据清洗步骤

1. 检查缺失值

2. 处理异常值

...

2. 资源绑定

技能可以带有参考资料、脚本等资源：

skill_obj.get_prompt()

返回：

Loading: pdf

Base directory: /Users/xxx/.minion/skills/pdf

[技能内容，可以引用 references/api_doc.md 等]

3. 版本和来源追踪

@dataclass

class Skill:

name: str
description: str
content: str
path: Path
location: str  # project, user, managed
license: Optional[str]
metadata: Dict[str, Any]

为什么做开源实现？

Claude Code 的 Skills 是一个出色的设计，但它是闭源的、与 Claude 生态绑定的。我实现开源版本的原因：

LLM 无关性：Minion 支持多种 LLM 后端（Claude、GPT-4、开源模型），Skills 能力不应被锁定在单一供应商

可定制性：开源实现允许深度定制，满足特殊需求

社区贡献：开源让更多人能够贡献 Skills，形成技能生态

学习价值：通过实现，深入理解这一架构的设计精髓

未来方向

1. 技能市场

想象一个 Skills Marketplace，开发者可以发布、分享专业技能：

minion skill install data-science-toolkit

minion skill install legal-document-analysis

2. 智能推荐

根据用户历史和当前任务，自动推荐相关技能：

def recommend_skills(user_request, history):

# 分析请求内容
# 匹配最相关的技能
# 预加载可能需要的技能
...

3. 技能组合

多个技能协同工作：

分析 PDF 中的数据，生成 Excel 报告

skills_used = ["pdf", "xlsx", "data-visualization"]

4. 自学习技能

Agent 在完成复杂任务后，自动生成新技能供未来使用：

async def learn_skill_from_session(session_log):

# 分析成功的任务执行过程
# 提取可复用的模式和指令
# 生成新的SKILL.md
...

视频演示

PDF 摘要提取: https://youtu.be/r1nngYLI-pw

长 PDF 翻译（穷人版 Paper PDF Reader）: https://youtu.be/C7p8yffBZ-Q

DOCX 文档处理: https://youtu.be/PByDtqY_17Y

PPTX 演示文稿处理(穷人版 pptx 生成): https://youtu.be/ek00e5m4yXI

结语

Claude Code 的 Skills 系统体现了一个核心设计哲学：

不要试图让 AI 什么都懂，而是让它知道在需要时去哪里找到答案。

这种"专家系统"思维，让 AI Agent 从"通才"进化为"能快速变身专家的通才"。

通过 Minion 的开源实现，这一能力现在可以被更广泛的开发者使用，不受限于特定的 LLM 供应商或闭源生态。

欢迎试用和贡献：

GitHub: https://github.com/femto/minion

https://github.com/femto/minion-agent

文档: https://github.com/femto/minion/blob/main/docs/skills.md

让我们一起构建更开放、更智能的 AI Agent 生态。

往期文章：

《Minion 框架早已实现 PTC：超越传统 Tool Calling 的 Agent 架构》