<div align="center"> <img src="./image/Logo.png" alt="MagicSkills" width="300" /> <br/> <br/>

🪄 MagicSkills: Build Skills Once, Reuse Them Across Every Agent

<br/>

Local-first skill infrastructure for multi-agent projects

Turn scattered SKILL.md directories into a reusable · composable · syncable · callable shared capability library

<br/> <table> <tr> <td align="center"><b>🤖 Agent Apps</b></td> <td align="center"><b>🧩 Agent Frameworks</b></td> </tr> <tr> <td align="center">Claude Code · Cursor · Windsurf · Aider · Codex<br/>_{Any agent app that can read `AGENTS.md`}</td> <td align="center">AutoGen · CrewAI · LangChain · LangGraph · Haystack<br/>Semantic Kernel · smolagents · LlamaIndex<br/>_{Any agent framework with tool / function integration support}</td> </tr> </table> <br/>

_{Initiated and maintained by Narwhal-Lab, Peking University}

<p align="center"> <a href="https://www.pku.edu.cn"> <img src="./image/image4.png" alt="Peking University" height="42" /> </a> <a href="https://github.com/Narwhal-Lab"> <img src="./image/image5.png" alt="Narwhal-Lab" height="42" /> </a> </p> <p> <a href="https://github.com/Narwhal-Lab/MagicSkills"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.10‑3.13"/></a> &nbsp; <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge" alt="License: MIT"/></a> &nbsp; <a href="https://github.com/Narwhal-Lab/MagicSkills"><img src="https://img.shields.io/github/stars/Narwhal-Lab/MagicSkills?style=for-the-badge&logo=github" alt="GitHub stars"/></a> </p> <br/> <br/>

English | 简体中文

Overview · Quick Start · How It Works · CLI · Python API · Tips

</div>

---

<a id="overview-en"></a>

🧭 Overview

MagicSkills is a local-first skill infrastructure layer for multi-agent projects.

It turns scattered SKILL.md directories into something you can:

• install into one shared skill pool
• compose into per-agent Skills collections
• sync into AGENTS.md
• expose as a tool through one stable API

The core model is simple:

• Skill: one concrete skill directory
• ALL_SKILLS(): access the current built-in Allskills view
• Skills: the subset an agent or workflow actually uses
• REGISTRY: the global named-collection registry persisted across runs

MagicSkills is most useful when:

• you maintain multiple agents that should reuse one skill library
• you already have SKILL.md content but no install, selection, or sync workflow
• some agents read AGENTS.md, while others need direct tool integration

A common real-world scenario is: you have one reusable shared skill, and many different agent apps and agent frameworks all need to use it.

For example, the same c_2_ast skill may need to be shared across Claude Code, Cursor, Windsurf, Aider, Codex, AutoGen, CrewAI, LangChain, LangGraph, Haystack, Semantic Kernel, smolagents, and LlamaIndex.

In that case, the recommended approach is not to copy that skill into every agent project separately. Instead, keep it in one shared skill pool, build one or more named Skills collections from that same underlying skill, and expose those collections differently depending on whether the target runtime reads AGENTS.md or integrates through tools / functions.

🤔 Why MagicSkills

Without a skill layer, multi-agent projects usually drift into one of these states:

• the same skill is copied into multiple agent folders and quickly diverges
• SKILL.md exists, but it is still just a document, not an operational unit
• every agent loads too many irrelevant skills
• AGENTS.md, prompt glue, and framework tools evolve independently
• changing frameworks means redoing the whole integration

MagicSkills solves that by separating:

• the total installed skill pool
• the subset each agent should actually see
• the persistence layer that stores named collections

<a id="quick-start-en"></a>

🚀 Quick Start

The shortest recommended workflow is:

1. Install MagicSkills.
2. Install one or more skills into the local pool.
3. Create a named Skills collection for one agent.
4. Sync that collection to AGENTS.md if the runtime reads AGENTS.md.
5. Or expose that collection through the CLI tool interface.
6. Or expose that collection from Python.

1. 📦 Install The Project

From source:

git clone https://github.com/Narwhal-Lab/MagicSkills.git
cd MagicSkills
python -m pip install -e .
magicskills -h

Or from PyPI:

pip install MagicSkills
magicskills -h

2. ⬇️ Install Skills

# remote repository example
magicskills install anthropics/skills -t ~/allskills

# local directory example (if you cloned this repo)
magicskills install skill_template -t ~/allskills

The first command shows installing from a GitHub repository. The second command uses this repo's local skill_template/ directory to simulate the common case where you have already downloaded skills locally and now want to install them into the shared pool.

MagicSkills supports four standard install locations by default:

• current project: ./.claude/skills/
• --global: ~/.claude/skills/
• --universal: ./.agent/skills/
• --global --universal: ~/.agent/skills/

You can also use -t / --target to install into any explicit path.

In practice, we recommend using one shared skills root such as ~/allskills, so all agents and frameworks can reuse the same local skill pool and discover them from the built-in Allskills view.

3. 🧩 Create One Agent Collection

Here pdf and docx are example skill names. Replace them with the skills currently available in your own Allskills view. If you only installed this repo's local skill_template/, use c_2_ast here instead.

magicskills addskills agent1_skills --skill-list pdf docx --agent-md-path /agent_workdir/AGENTS.md

This means:

• find the pdf and docx skills from Allskills
• create a named collection called agent1_skills
• remember /agent_workdir/AGENTS.md as its default sync target

4. 🔄 Sync To AGENTS.md

magicskills syncskills agent1_skills

syncskills supports two AGENTS.md sync modes:

• none: keep the standard <usage> + <available_skills> structure; use this for agents that can directly discover and use skills from the skill information list in AGENTS.md
• cli_description: write only <usage> using the collection's cli_description; use this for agents that cannot directly use skills from the skill information list in AGENTS.md and instead need CLI guidance through magicskills skill-tool

Examples:

magicskills syncskills agent1_skills --mode none
magicskills syncskills agent1_skills --mode cli_description

If the target file already contains a skills section, it is replaced. If not, a new one is appended.

5. 🛠️ Or Use The CLI Tool Interface Directly

For agents that do not read AGENTS.md, use the unified CLI tool entrypoint:

magicskills skill-tool listskill --name agent1_skills
magicskills skill-tool readskill --name agent1_skills --arg pdf
magicskills skill-tool execskill --name agent1_skills --arg "echo hello"

6. 🐍 Or Expose The Same Interface From Python

If you are integrating MagicSkills into an agent framework, there are two common Python-side patterns.

Option A: reuse a collection already created by the CLI

If you already created the collection with:

magicskills addskills agent1_skills --skill-list pdf docx --agent-md-path /agent_workdir/AGENTS.md

then Python can reuse that same named collection directly through REGISTRY.get_skills("agent1_skills"):

import json

from langchain_core.tools import tool
from magicskills import REGISTRY

agent1_skills = REGISTRY.get_skills("agent1_skills")


@tool("_skill_tool", description=agent1_skills.tool_description)
def _skill_tool(action: str, arg: str = "") -> str:
    return json.dumps(agent1_skills.skill_tool(action, arg), ensure_ascii=False)

Option B: build a temporary collection directly in Python

If you do not want to depend on a pre-created registry entry, you can also construct a Skills(...) object manually:

import json

from langchain_core.tools import tool
from magicskills import ALL_SKILLS, Skills

skill_a = ALL_SKILLS().get_skill("pdf")
skill_b = ALL_SKILLS().get_skill("docx")

agent1_skills = Skills(
    name="agent1_skills",
    skill_list=[skill_a, skill_b],
)


@tool("_skill_tool", description=agent1_skills.tool_description)
def _skill_tool(action: str, arg: str = "") -> str:
    return json.dumps(agent1_skills.skill_tool(action, arg), ensure_ascii=False)

This second form stays in memory only. A plain Skills(...) object is not persisted into the registry automatically, so it does not conflict with CLI-created collections unless you explicitly register and save it through REGISTRY.

Use syncskills if your runtime consumes AGENTS.md. Use the CLI tool interface or the Python API directly if it does not.

🧪 Examples and Ecosystem Integrations

MagicSkills provides integration examples for both agent / IDE products that can directly read AGENTS.md and mainstream agent frameworks that integrate through tools or functions.

One Shared Skill Across Many Agents

A common real-world scenario is: you have one reusable skill, and many different agent products or agent frameworks all need to use it.

For example, the same c_2_ast skill may need to be shared across Claude Code, Cursor, Windsurf, Aider, Codex, AutoGen, CrewAI, LangChain, LangGraph, Haystack, Semantic Kernel, smolagents, and LlamaIndex.

In that case, the recommended approach is not to copy the skill into every ag