MagicSkills: A Local Skill Pool for Agents That Read AGENTS.md
MagicSkills：Stop copying skills between agents. MagicSkills turns scattered SKILL.md folders into reusable, composable, tool-ready capabilities.
At a glance
- What is it?
- MagicSkills is a Python CLI and library that installs SKILL.md folders into one shared pool, lets you carve named subsets for individual agents, and syncs those subsets into AGENTS.md or exposes them as tools. The idea is sound; the documentation around failure modes and versioning is where it thins out.
- Who is it for?
- Adopt MagicSkills if you already maintain SKILL.md folders and run more than one agent app or framework that should share them, and if your runtimes either read AGENTS.md or can call a CLI. Skip it if you have a single agent, or if your framework's native tool registry already covers your needs.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 161 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The copy-paste problem MagicSkills is aimed at
The README frames the problem in concrete terms: you have one reusable skill, and many different agent apps and agent frameworks all need it. Its own example is a skill called c_2_ast that has to reach Claude Code, Cursor, Windsurf, Aider, Codex, AutoGen, CrewAI, LangChain, LangGraph, Haystack, Semantic Kernel, smolagents and LlamaIndex. Without a layer in between, the README says multi-agent projects drift into familiar states: the same skill copied into several agent folders and diverging, SKILL.md files that exist as documents rather than operational units, agents loading more skills than they need, and AGENTS.md, prompt glue and framework tools evolving independently. The target user is therefore a maintainer of several agents, not someone with one agent and one skill folder. If you have a single agent, the install and sync steps add a layer with nothing on the other side of it.
Four objects: Skill, Allskills, Skills and REGISTRY
The core model is small and worth stating precisely, because the CLI verbs map onto it. A Skill is one concrete skill directory. ALL_SKILLS() gives access to the current built-in Allskills view, which is the total installed pool. Skills is the subset an agent or workflow actually uses, created as a named collection. REGISTRY is the global named-collection registry that persists across runs. That split is the whole design: installed pool, per-agent subset, persistence layer. The README describes MagicSkills as separating exactly those three things. The practical consequence is that installing a skill and giving it to an agent are two separate operations. Nothing is exposed to an agent until you build a Skills collection and then either sync it or call it, which means a freshly installed skill is inert until you name it into a collection.
Install paths and the shared pool convention
MagicSkills supports four standard install locations by default: ./.claude/skills/ for the current project, ~/.claude/skills/ with --global, ./.agent/skills/ with --universal, and ~/.agent/skills/ with --global --universal. The -t or --target flag installs into any explicit path instead. The README recommends one shared skills root such as ~/allskills so that all agents and frameworks reuse the same local pool and discover skills from the built-in Allskills view. That recommendation is the load-bearing part of the design. The four defaults are convenient, but if you spread skills across ./.claude/skills/ and ./.agent/skills/ you are back to multiple pools, and the Allskills view only reflects what you actually installed into it. Pick one root and pass it with -t consistently.
Getting it running: install, addskills, syncskills
From source the README gives: git clone https://github.com/Narwhal-Lab/MagicSkills.git, then cd MagicSkills, python -m pip install -e ., then magicskills -h. From PyPI it is pip install MagicSkills followed by the same help command. Skills come in with magicskills install anthropics/skills -t ~/allskills for a remote repository, or magicskills install skill_template -t ~/allskills for a local directory. Collections are built with magicskills addskills agent1_skills --skill-list pdf docx --agent-md-path /agent_workdir/AGENTS.md, which resolves pdf and docx from Allskills, creates the named collection, and stores the AGENTS.md path as its default sync target. Then magicskills syncskills agent1_skills writes it out. The README notes that if you only installed the repo's local skill_template, you should use c_2_ast in place of pdf and docx, which is a small but useful signal that the examples assume skills you may not have.
Two sync modes and why the choice is not cosmetic
syncskills supports two AGENTS.md modes. The none mode keeps the standard <usage> plus <available_skills> structure, for agents that can directly discover and use skills from the skill information list in AGENTS.md. The cli_description mode writes only <usage>, using the collection's cli_description, for agents that cannot use that list and instead need CLI guidance through magicskills skill-tool. This is the part of the design that earns its keep: the same collection can serve a runtime that reads a file and a runtime that shells out to a tool. It also means you must know which kind of runtime you are targeting before you sync, because the two modes produce different file contents. The README does not describe what happens to an AGENTS.md you already edited by hand, and that is the first thing I would check on a real repository rather than a template.
Where the material runs out
The README lists frameworks and apps that MagicSkills is meant to serve, but the integration story for the framework column is stated as a capability (any agent framework with tool or function integration support) rather than shown with a worked example. There is a doc/python-api.md and a doc/cli.md referenced from the header, so the detail exists somewhere, but the README itself gives no Python snippet and no worked framework binding. I cannot confirm from the supplied material how a LangGraph or CrewAI agent actually consumes a Skills collection, and I will not guess. The same applies to error behaviour: nothing in the material describes what syncskills does when a named skill is missing from Allskills, or whether REGISTRY survives a move between machines. Treat those as unknowns to test, not as documented guarantees.
MagicSkills versus hand-maintained AGENTS.md files
The obvious alternative is what most teams do now: keep a skills directory per agent and edit each AGENTS.md by hand. The difference in approach is where the source of truth lives. Hand-maintained files make the agent folder the source of truth, so adding a skill means editing every agent that needs it, and divergence is the default outcome. MagicSkills inverts that: the shared pool is the source of truth, the collection is a named subset, and syncskills regenerates the agent-facing file from it. The cost of the inversion is a new stateful layer. REGISTRY persists across runs, so your collections are not reproducible from the repository alone unless you commit whatever backs the registry, and the README does not say where that state is stored. That is the trade: you stop copying skills, and you start tracking a registry.
Licence, releases and what to verify first
MagicSkills is MIT licensed, which permits commercial use and modification, but the repository does not state a copyright holder line in the material supplied, so confirm the LICENSE file before redistributing. Releases visible in the material are v0.1.1 on 2025-12-31, v1.0 on 2026-03-10 and v1.1 on 2026-03-22, with the last push on 2026-04-08. That is a fast cadence for a young tool, and the README does not document a deprecation policy or a migration path between minor versions. Python support is stated as 3.10 through 3.13. The concrete next step is to run magicskills install skill_template -t ~/allskills on a scratch directory, run addskills against it, and read the AGENTS.md that syncskills produces in both none and cli_description modes before pointing it at a repository you care about.
Editorial conclusion
Adopt MagicSkills if you already maintain SKILL.md folders and run more than one agent app or framework that should share them, and if your runtimes either read AGENTS.md or can call a CLI. Skip it if you have a single agent, or if your framework's native tool registry already covers your needs. Before committing, verify two things yourself: that the four default install locations match where your agents actually look for skills, and what syncskills writes into an existing AGENTS.md you already maintain by hand.
Community notes