🪄 MagicSkills: **一次构建技能，供每个 Agent 复用**

🪄 MagicSkills: **一次构建技能，供每个 Agent 复用**

面向多 Agent 项目的**本地优先** skill 基础设施

将分散的 `SKILL.md` 目录沉淀为可复用、可组合、可同步、可调用的共享能力库

🤖 Agent 应用	🧩 Agent 框架
Claude Code · Cursor · Windsurf · Aider · Codex 任何能读取 `AGENTS.md` 的 Agent 应用	AutoGen · CrewAI · LangChain · LangGraph · Haystack Semantic Kernel · smolagents · LlamaIndex 任何支持 tool / function 集成的 Agent 框架

由北京大学 Narwhal-Lab 发起并维护

   

[English](./README.md) | 简体中文

[概览](#overview-cn) · [快速开始](#quick-start-cn) · [工作原理](#how-it-works-cn) · [CLI](./doc/cli.zh-CN.md) · [Python API](./doc/python-api.zh-CN.md) · [使用建议](#tips-cn)

演示视频

https://github.com/user-attachments/assets/dd04d9bf-00f9-4a00-94d5-9d3de2c74600

🧭 概览

MagicSkills 是面向多 Agent 项目的本地优先 skill 基础设施层。

它把分散的 `SKILL.md` 目录整理成一套可以：

• 安装到共享 skill 池
• 按 agent 组合成各自的 Skills 集合
• 同步到 AGENTS.md
• 通过一个稳定 API 暴露为工具

核心模型很简单：

• Skill：一个具体的 skill 目录
• ALL_SKILLS()：访问当前内置的 Allskills 视图
• Skills：某个 agent 或工作流实际使用的 skill 子集
• REGISTRY：跨运行持久化的全局命名集合注册表

MagicSkills 特别适合这些场景：

• 你维护多个需要复用同一套 skill 库的 agent
• 你已经有 SKILL.md 内容，但还没有安装、选配和同步流程
• 某些 agent 读取 AGENTS.md，而另一些 agent 需要直接接入工具

一个很常见的真实场景是：你有一个可复用的共享 skill，而多个不同的 Agent 应用和 Agent 框架都需要使用它。

例如，同一个 `c_2_ast` skill，可能需要同时供 Claude Code、Cursor、Windsurf、Aider、Codex、AutoGen、CrewAI、LangChain、LangGraph、Haystack、Semantic Kernel、smolagents 和 LlamaIndex 使用。

在这种情况下，推荐做法不是把这个 skill 分别复制到每个 agent 项目里，而是把它统一维护在共享 skill 池中，再基于同一份底层 skill 构建一个或多个命名的 `Skills` 集合，并根据目标运行时是读取 `AGENTS.md` 还是通过 tools / functions 接入，用不同方式把这份能力暴露出去。

🤔 为什么需要 MagicSkills

没有 skill 层时，多 Agent 项目通常会逐渐滑向以下状态：

• 同一个 skill 被复制到多个 agent 目录中，并很快产生分叉
• SKILL.md 明明已经存在，但仍然只是文档，而不是可操作单元
• 每个 agent 都加载了过多无关 skill
• AGENTS.md、提示词胶水层和框架工具接口彼此独立演化
• 一旦更换框架，就得把整套集成方式重做一遍

MagicSkills 通过分离以下几层来解决这些问题：

• 总体已安装的 skill 池
• 每个 agent 实际应该看到的 skill 子集
• 负责保存命名集合的持久化层