🧩 What is an Agent Skill (and why this format won)
From what a skill is to why the SKILL.md format became the de facto standard — and how skills.sh became the “npm of skills.”
A skill is a single file SKILL.md — YAML frontmatter (name + description) plus a Markdown body — which describes a behavior. The agent reads and incorporates this instruction into its own reasoning.
It’s the atomic unit of the entire ecosystem. Without understanding what a SKILL.md is, the rest (catalog, install count, groups) doesn’t make sense.
SKILL.md · YAML frontmatter · name + description · Markdown body
A skill isn’t code that runs. It’s text the agent reads and follows when the conversation context matches the description. Activation is automatic and based on relevance, not an explicit call.
This difference changes how you write. You don't program steps — you describe when and why, and let the agent decide how to apply them.
context-based activation · description as trigger · no direct execution
SKILL.md is plain text: it works across 50+ agents, is versioned through git like any repository file, and already adds up 53.9M installs in the skills.sh aggregate. Markdown won because it’s the lowest common denominator.
Understanding why the format caught on explains why it's worth investing in instead of locking knowledge into proprietary tools.
portability across 50+ agents · git versioning · 53.9M installs
These are distinct layers: a prompt is ephemeral; CLAUDE.md is fixed project context; MCP provides tools/data; a subagent is an isolated executor; a skill is reusable knowledge triggered by context.
Knowing how to choose the right layer keeps you from turning everything into a skill (or nothing into one). Each problem has a suitable mechanism.
ephemeral prompt · always-active CLAUDE.md · MCP = tools · subagent = execution · skill = on-demand knowledge
skills.sh is the public catalog: it indexes skills by repo, shows install count (quality signal) and installs with npx skills add owner/repo. It’s the npm of the skills world.
It’s where you find out what already exists before creating something, and where you publish for others to install.
catalog · install count · npx skills add · leaderboard
Published by major players—vercel-labs, anthropics, microsoft—and thousands of community members, totaling 5.075 source repos. It’s not a walled garden for a single company.
Knowing who’s in charge and who hasn’t arrived yet shows where there’s room for your skill.
vercel-labs · anthropics · microsoft · community · 5.075 repos
🗺️ The skills.sh Map: 39k Skills, the Power Law, and the 16 Groups
The catalog’s actual size, the brutal install curve, and the 16 topic groups — and what it all teaches you before you create your skill.
skills.sh catalogs 39.366 skills from 5.075 source repos, totaling 53.9M installs distributed across 16 thematic groups.
The total number gives you a sense of scale: the ecosystem is large enough to already have almost everything — and specific enough to still have gaps.
39.366 skills · 5.075 repos · 53,9M installs · 16 groups
The distribution follows a power law: 60,2% of skills have fewer than 100 installs, and only 0.3% (131 skills) exceed 100k. Most are in the long tail.
It dispels the illusion that "publishing = success." The vast majority of skills are barely installed.
power law · long tail · 60.2% <100 · 0.3% = 131 skills 100k+
The 100 most installed skills concentrate 43,7% of all installs. Almost half the pie is in 100 names, among nearly 40,000.
Show the “winner takes almost all” effect—and why competing head-on with the leaders is difficult.
top 100 = 43.7% · network effect · winner-takes-most
The catalog is divided into 16 groups. By count, the leader is AI/LLM/Agents (12.693 skills, 12,9M installs); per-installation per skill shines DevOps&Cloud (907 skills, 8,3M installs). Web&Frontend has 4,694 skills.
Viewing volume vs. installs by group reveals where there’s plenty of supply and where a few skills capture a lot of demand.
AI/Agents 12.693 · Web 4.694 · DevOps 8,3M · Backend 2.685 · Testing 1.339
Skills aren’t the only thing that concentrates—sources do, too. A few repos (vercel-labs, anthropics, microsoft, larksuite) account for a huge share of installs, even among 5.075 repos.
Brand and distribution matter. A great skill in an unknown repo starts at a disadvantage.
vercel-labs · anthropics · microsoft · larksuite · brand + distribution
The practical lesson: find out what already exists before creating something; target empty niches instead of going head-to-head with leaders; and position your skill on the right side of the curve (solving a real pain point, not just repeating what’s already there).
It’s the bridge from Track 1 to the rest of the course: the map guides you on where and how to create.
research before creating · empty niche · the right side of the curve
⭐ The Best Ones to Start With (Starter Pack)
The canonical skills everyone should know and install first — eight names that teach you the ecosystem faster than any tutorial, plus the recommended minimum kit.
A small set of widely installed, well-written skills from trusted sources (vercel-labs, anthropics, supabase) that you install and read first.
Installing these skills is the fastest way to understand what a good skill looks like on the inside—each one becomes an annotated example.
curation · trusted source · installing means reading · 4-8 core skills
find-skills (vercel-labs/skills, 1,802,925 installs) teaches the agent to find, evaluate, and install other skills from the catalog on its own. npx skills add vercel-labs/skills.
It’s the most installed skill on the planet and the entry point to everything—it turns the agent into a curator of its own ecosystem.
find-skills · meta-skill · 1.8M installs · vercel-labs/skills
frontend-design (488k, anthropics), vercel-react-best-practices (443k), and web-design-guidelines (358k, vercel-labs) — the three references for UI design and code. npx skills add anthropics/skills e vercel-labs/agent-skills.
Show how to write a “guideline” skill—style instructions the agent applies without you having to repeat them, even if you’re not a front-end developer.
frontend-design 488k · vercel-react 443k · web-design-guidelines 358k · guideline skill
skill-creator (246k, anthropics) guides the agent in writing and optimizing SKILL.md; agent-browser (332k, vercel-labs) gives the agent a browser for automation and scraping.
Change what the agent can do: one creates new skills (you’ll use it in 1.4), the other unlocks real-world use cases on the web.
skill-creator 246k · agent-browser 332k · meta + tool
supabase-postgres-best-practices (203k, supabase) teaches SQL/RLS/schema; test-driven-development (107k, obra/superpowers) has the agent write the test before the code.
Show a vendor skill (made by the product team) and a process skill (changes behavior, doesn’t provide a tool)—two flavors beyond front-end.
supabase 203k · TDD 107k · vendor · process
The minimum kit is find-skills + skill-creator (+ TDD if you code). Frontend adds frontend-design + web-design-guidelines; the rest comes in as needed.
Each skill consumes context: a lean, relevant pack works better than 40 skills competing for attention. Install what you use.
minimum kit · find-skills + skill-creator · expand on demand · less is more
🛠️ How to Create: Your First Skill in 10 Minutes
Hands-on from zero to working: choose a real use case (commit conventions), write the minimal SKILL.md, install it locally, and see it trigger—with the file ready to copy.
A convention you repeat and hate repeating—the ideal first use case. Our example: the commit message format (Conventional Commits).
Small, concrete cases you can test in 1 minute teach the format; large cases ("full deploy") frustrate users and don't trigger.
real-world case · testable · conventional-commits · small by design
One file: YAML frontmatter with name + description required, with an imperative Markdown body below.
name is the identifier; description is the trigger (it says WHAT and WHEN); the body contains the instructions. Know all three and you know how to write any skill.
YAML frontmatter · name · description = trigger · imperative body
The complete conventional-commits skill, to save in skills/conventional-commits/SKILL.md: frontmatter, description with triggers, concise body with types and rules.
Viewing a real, concise SKILL.md demystifies the format — the description does the heavy lifting with a "ALWAYS use when..." and concrete triggers.
SKILL.md ready · concrete triggers · short body · good/bad example
Four steps: create the folder/file, install with npx skills add ./skills/conventional-commits, trigger it with a real request and confirm the output format.
You don’t need to publish it to use it — install from a local path. No build, no deploy, no dependency. Ten real minutes.
npx skills add ./ · local installation · triggers by context · confirm
The error buckets: vague description, no WHEN to use it, huge body, broken frontmatter, shouted rules in ALL CAPS with no explanation.
If the skill exists but the agent ignores it, 9 times out of 10 the description is weak, not the body. Knowing this saves hours.
vague description · no WHEN · bloated body · broken YAML
Incremental evolution: refine the description based on what failed, add examples as needed, and version the SKILL.md along with the repo.
A 30-line skill used and tweaked every week is worth more than a 500-line one written as "complete" and never tested. Let real use trim and grow it.
refine description · on-demand examples · version in git · incremental
🚀 Advanced Tips: Reading the Ecosystem Like a Pro
Install count is a little misleading. Learn to read the catalog critically: early-adopter bias, finding rising skills and empty niches, evaluating the source, using the CLI, and knowing when NOT to install.
Install count is cumulative: it favors those who arrived early, have a brand, and became a prerequisite. find-skills (1,8M) leads because it's a dependency in almost every workflow, not because it's "better".
It’s reputation, not a rating. Use it as an initial filter (“worth a look”), never as the final decision—it doesn’t tell you whether the skill is maintained or suits your needs.
cumulative bias · first-mover · brand · reputation ≠ rating
60.2% of skills have <100 installs, and only 131 exceed 100k. The undervalued gems are in the 100 to 10k install range and in small groups (Office, Finance, Productivity).
The top is locked down. Hunting for recent + trending skills in the middle tier and looking for gaps (a search that returns nothing = a niche) pays off more than going head-to-head with the leaders.
middle range · on the rise · empty niche · small groups
Four profiles: official provider (supabase, stripe) and platform (anthropics) = high trust; recognized community = medium; unknown repo = read the SKILL.md first.
A skill is an instruction the agent adopts and sometimes executes. An untrustworthy source may embed bad instructions—and SKILL.md is text you can read in 30 seconds.
official vendor · platform · community · read the SKILL.md
npx skills find search, add installs, list shows the installed, update update. With find-skills, the agent does everything for you.
Search for the problem (not the name) and compare descriptions before installing. But updates aren't free—they can change behavior; test afterward.
npx skills find/add/list/update · search by pain point · agent operates the CLI
Don’t install it for one-off use (a prompt will do), when there’s already a similar skill, from an unread source you don’t know, for fixed context (put that in CLAUDE.md), or "just in case."
Each skill consumes context and adds an unwanted trigger. The 3-question test (recurring use? trust the source? nothing similar already?) prevents bloat.
3-question test · context costs · periodic cleanup · CLAUDE.md vs skill
Six habits: read the description, not the number; prefer recent + trending over old + popular; search by pain point and install the minimum; treat the catalog as a map of niches; update/review in cycles; know when not to install.
These habits separate people who just watch the leaderboard from those who get real value — and wrap up Track 1 with the full map for Track 2 (quality).
description > number · movement > size · minimum > accumulation · niche map
Learning path overview
A text file that became the standard across 50+ agents and has 53.9M installs.
39 thousand skills, a steep curve, and 100 names accounting for 43,7% of everything.
Eight canonical skills and the starter kit: a shortcut to understanding the ecosystem.
From zero to working: a real, copyable SKILL.md, installed and triggering.
Install count is misleading: find niches, evaluate the source, and know when NOT to install.