Mercury Agent Skills: a SKILL.md registry for agents that read markdown
A curated registry of reusable Mercury Agent, Open Claw or Hermes Agent skills designed for real developer workflows, persistent memory, and token-efficient execution.
At a glance
- What is it?
- Mercury Skills is a curated library of 132 SKILL.md playbooks across 23 categories, installable through the Mercury CLI or by copying files into an agent's skills directory. The format is portable; the install tooling is not.
- Who is it for?
- Adopt it if you already run Mercury Agent, OpenClaw, Hermes, Claude Code, Codex CLI, Cursor, or Gemini CLI and want versioned playbooks that install with one command into a known directory. Do not adopt it if you need a maintained, testable library: there are no releases, no CI signals in the supplied material, and 23 categories means the median category holds roughly five files.
- 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 22 days ago.
- What is it written in?
- Mainly JavaScript, 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 gap Mercury Skills fills: agent instructions that live in your repo, not in a prompt
Most agent setups keep their instructions in a system prompt or a CLAUDE.md-style file that grows until nobody reads it. Mercury Skills takes the opposite position: one skill per file, one concern per skill, installed on demand. The README describes the library as "an open-source library of SKILL.md playbooks for AI agents" and states it holds 132 skills across 23 categories, from Development (16 skills) and AI & ML (11) down to Data (1).
The intended user is a developer who wants an agent to follow a specific procedure (a code review rubric, a Dockerfile convention, a threat model checklist) without pasting that procedure into every conversation. The registry is the distribution layer: browse on the web, install with a CLI, or clone the repo and copy files. If you already maintain a folder of prompt fragments and wish they were addressable by name, this is the shape you were looking for.
The category list is worth reading before anything else, because it tells you what the maintainers think an agent should be good at. Alongside backend, frontend and DevOps sit Shop & Restaurant (10 skills, including Zomato ordering and an Amazon assistant), Media Download (6, mostly yt-dlp wrappers), Career (5), and Health & Wellness (5). That spread is either the point or the problem, depending on whether you want a general assistant or a work tool.
What a SKILL.md actually contains, and why the format travels
Each skill is a single markdown file with YAML frontmatter. The README gives this example structure: a name field, a description field quoted as 'What this skill does and when to use it', and a metadata block carrying author, version, category, and a tags array. The body holds what the README calls "full instructions, frameworks, scoring rubrics, and ac" (the excerpt is truncated at that point).
The portability claim rests entirely on that frontmatter plus plain markdown. The README says one SKILL.md "works in any agent that supports the standard. No per-agent forks." There is no compiled artifact, no runtime, no dependency graph. That is why the same file can be dropped into .claude/skills/, .codex/skills/, .cursor/skills/, or ~/.mercury/skills/ and be picked up. The trade-off is that a skill cannot execute anything on its own. If a procedure needs a script, the script has to be described in prose and re-derived by the model, or shipped separately outside the format.
The metadata block is the part with real consequences. Version is declared per skill and the README states the CLI supports version pinning, so the frontmatter is not decoration. It is the unit of upgrade. A skill that changes its rubric between 1.0.0 and 1.1.0 changes agent behaviour with no diff in your own repository.
Installing skills: the CLI path and the copy path
The README's recommended route is the Mercury CLI. Three commands cover the documented workflow:
mercury skills search "react patterns" mercury skills install frontend/react-patterns mercury skills install ai-ml/prompt-engineering devops/docker security/threat-modeling
Installed files land at ~/.mercury/skills/<category>/<slug>/SKILL.md and, per the README, are picked up automatically by the agent. The install command accepts multiple category/slug arguments in one invocation. The README also claims atomic writes, version pinning, and rollback on failure, which is the strongest statement in the document and the one hardest to check from the outside.
If you are not on Mercury, the CLI is not the path. The README provides a table mapping each supported agent to its skills directory: .claude/skills/ for Claude Code, .codex/skills/ for Codex CLI, .openclaw/skills/ for OpenClaw, .hermes/skills/ for Hermes, .cursor/skills/ for Cursor, .gemini/skills/ for Gemini CLI, and ~/.mercury/skills/ for Mercury. For anything else, the README's own wording is "wherever your agent reads SKILL.md from". That is a clean escape hatch and also an admission that the standard is descriptive rather than enforced.
Cloning the whole repository with git clone https://github.com/cosmicstack-labs/mercury-agent-skills.git gives you every skill at once, at which point you are managing a vendored directory rather than a package. The web registry at skills.mercuryagent.sh advertises per-skill install steps for each agent, so you can copy the exact command or file path without reading the CLI docs.
The registry site and its JSON feed are the part other tools can build on
skills.mercuryagent.sh is described as the canonical browse-and-install surface. The README lists what it serves: a searchable categorized index, a trending leaderboard ranked by likes and installs, per-skill detail pages containing the full SKILL.md plus install steps, local bookmarking with no account, and per-skill OpenGraph imagery.
Two endpoints matter for anyone wiring this into a pipeline. The feed at /api/feed.json exposes the catalog as JSON, and /api/skills/<category>/<slug> returns a single skill. The README frames these as being "for tooling builders", which is the most interesting line in the document. A registry with a stable JSON feed can back an internal mirror, a lint step that checks which skills your team has installed, or a diff job that flags when a pinned skill changes upstream.
I would treat the leaderboard with more caution than the feed. Likes and installs are popularity signals, and the README says the ranking is based on them. Popularity is not the same as correctness for your stack, and a skill in a crowded category will outrank a more specific one. Use search and the category pages, not the leaderboard, when you are picking something to depend on.
Where the registry model breaks down
The repository has no releases. The supplied material returns none, and the last push is dated 2026-08-25. That means there is no changelog to read, no tag to diff against, and no way to see what changed in a skill between two points in time short of reading git history yourself. Version pinning in the CLI mitigates this for installed skills. It does not tell you what an upgrade contains.
Second, 132 skills across 23 categories means the median category holds about five files, and several hold one or two. Data has a single skill. Design, Product, Business, Marketing and Security have two or three each. A category with one entry is a placeholder more than a library, and the README's own framing of the site as "curated, not crowded" reads differently once you count.
Third, and most important: a skill is prose your agent will follow. Nothing in the install path validates it. The frontmatter schema is not described as enforced by a linter or a CI check in the material provided. If a skill's rubric is wrong for your codebase, the agent will apply it confidently. The failure mode is not a crash. It is a review comment that cites a convention you never adopted.
Finally, the category spread is a signal about maintenance surface. Shop & Restaurant skills that wrap Zomato ordering and an Amazon assistant depend on third-party interfaces. When those change, the skill text goes stale silently, because there is no test that can fail.
How this differs from prompt libraries and from agent-native tool registries
The closest comparison is a prompt library such as the collections people keep in a shared Notion page or a prompts/ folder. The difference is operational, not conceptual. A prompt library is copied by hand and drifts per person. Mercury Skills adds a naming scheme (category/slug), a directory convention the agent already scans, a version field in frontmatter, and a CLI that writes the file for you. The content may be similar; the install and upgrade path is not.
The second comparison is an agent-native tool registry, where a capability is exposed as a callable function with a typed schema. That approach lets the agent invoke real code with validated arguments. Mercury Skills cannot do that. It ships instructions, and the agent decides how to act on them. If your procedure needs deterministic execution (run this scanner, parse this output, fail the build), a SKILL.md is the wrong container and you want a tool or a script instead. If your procedure is judgement (how to review a diff, how to structure an ADR), prose is the right container and a typed schema would be overkill.
A third option is to write your own skills and skip the registry entirely. The format is plain markdown with frontmatter, so nothing stops you. What you lose is discovery and the shared vocabulary of category/slug paths that the CLI resolves.
Licence, contribution, and what an upgrade costs you
The repository is MIT licensed. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. It does not grant trademark rights, and it comes with no warranty. If you vendor skills into a product, keep the licence text with the files. This is a description of the licence, not legal advice; check with counsel if the skills end up inside something you ship.
Contribution runs through pull requests, with CONTRIBUTING.md as the reference. The README states every skill is hand-written against real workflows and that duplicates are rejected, which is a curation policy rather than a technical control. Nothing in the supplied material describes a review checklist, a test harness, or a schema validator for incoming skills.
Upgrade cost has two parts. The mechanical part is small: mercury skills install <category>/<slug> rewrites a file, and the README claims rollback on failure. The cognitive part is the real expense. Every skill your agent loads occupies context, and the README's own framing of the AI & ML category includes token budgets and memory skills, which suggests the maintainers are aware that skill count and token spend trade off against each other. Installing 40 skills because they are one command away is the predictable mistake here. Start with the handful that match a procedure you already follow, and read each SKILL.md before it goes into ~/.mercury/skills/.
Editorial conclusion
Adopt it if you already run Mercury Agent, OpenClaw, Hermes, Claude Code, Codex CLI, Cursor, or Gemini CLI and want versioned playbooks that install with one command into a known directory. Do not adopt it if you need a maintained, testable library: there are no releases, no CI signals in the supplied material, and 23 categories means the median category holds roughly five files. Before installing anything, open the raw SKILL.md on GitHub and read it end to end, because a skill is prose your agent will follow and nothing in the install path validates the instructions.
Community notes