Stop Copying Skills Into Every Agent: Share One Skill Pool with MagicSkills

The same SKILL.md directory gets copied into the Claude Code folder, the Cursor folder, the Codex folder — and three weeks later the copies have quietly diverged. MagicSkills, a 308-star project from Narwhal-Lab at Peking University, replaces the copying with one shared, local-first skill pool.

Why This Skill Matters

MagicSkills describes itself as "local-first skill infrastructure for multi-agent projects". Instead of scattering skill directories per project, you maintain one pool and build named Skills collections from it — each agent sees only the subset it needs, exposed the way that runtime actually consumes skills.

The object model has three layers: Skill (one concrete skill directory), Skills (an operable collection), and REGISTRY (the persistence layer that stores named collections across runs in ~/.magicskills/collections.json — it saves paths and descriptions, not copies of skill contents).

The coverage story splits by runtime. Agent apps that read AGENTS.md — the README names Claude Code, Cursor, Windsurf, Aider, and Codex — sync a collection into that file. Agent frameworks that integrate through tools or functions — AutoGen, CrewAI, LangChain, LangGraph, Haystack, Semantic Kernel, smolagents, and LlamaIndex — call the same collection through a unified tool interface.

Installation

MagicSkills is on PyPI and requires Python 3.10 through 3.13, plus Git for installing skills from remote repositories:

pip install MagicSkills
magicskills -h

Or from source:

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

Real Workflow: One Skill Pool, Synced Per Agent

The recommended flow for agents that read AGENTS.md is install, compose, sync. First install skills into a shared pool — from a GitHub repository or a local directory:

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

# from a local directory (this repo's own template skill)
magicskills install skill_template -t ~/allskills

Four standard locations work out of the box: ./.claude/skills/ for the current project, --global for ~/.claude/skills/, --universal for ./.agent/skills/, and --global --universal for ~/.agent/skills/ — or any path via -t. The README recommends one shared root such as ~/allskills so every agent reuses the same pool.

Then compose a named collection for one agent:

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

And sync it:

magicskills syncskills agent1_skills

syncskills has two modes. none keeps the standard <usage> + <available_skills> structure for agents that can use skills directly from the list in AGENTS.md; cli_description writes only <usage> with CLI guidance for agents that must go through magicskills skill-tool instead. If the target file already has a skills section it is replaced; otherwise one is appended.

Real Workflow: Expose the Same Collection to a Framework

For frameworks that never read AGENTS.md, the CLI dispatches list, read, and exec in tool style:

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"

From Python, reuse a CLI-created collection through the registry, wrap it in a @tool, and hand it to the framework:

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)

You can also build a temporary Skills(...) object in memory without registering it — useful for one-off compositions that should not persist.

Tips

• When two skills share a name, stop passing the name and pass an explicit path — magicskills readskill ./skills/demo/SKILL.md. Names are for convenience, paths are for disambiguation.
• execskill runs commands in the current process working directory, not inside the skill directory — cd yourself if the command depends on location.
• uploadskill submits a local skill to the MagicSkills repo through an automated fork, push, and PR workflow, so others can install it back down.
• magicskills -h plus the full command reference in doc/cli.md covers the remaining commands, from showskill to deleteskills.

When Not to Use This

If you run one agent in one project, a plain skills directory already works — the pool, collections, and registry are architecture for the multi-agent case. Everything is Python CLI plus local files, so runtimes with no way to call a CLI or read a synced AGENTS.md are out of scope. And Git is required for remote installs, which rules out fully offline setups pulling from GitHub.

See the leaderboard for more skills.