📄 What is an agent skill
An agent skill is, in practice, a single file: SKILL.md. It has two parts — a YAML frontmatter with the required fields name e description, and a Markdown body with the instructions themselves. When the conversation context matches the description, the agent reads this file and incorporates the instruction for its own behavior—as if you had explained the convention at that moment.
💡 Core concept
A skill isn’t a plugin that runs code. It’s knowledge packaged in text that the agent comes to “know.” The canonical one here is the skill-creator from Anthropic, which defines the SKILL.md structure as the standard.
- •Format: Markdown with YAML front matter
- •Required: name + description
- •Activation: automatic, based on contextual relevance
- •Distribution: versioned via git, installable via skills.sh
Minimal SKILL.md:
--- name: react-best-practices description: Aplica boas práticas React ao gerar ou revisar componentes. Use quando o usuário cria ou edita arquivos .jsx/.tsx. --- # React Best Practices Ao gerar componentes React, sempre: - Use componentes funcionais com hooks - Prefira TypeScript com tipos explícitos - Siga nomenclatura PascalCase para componentes
🎯 Practical tip
Think of a skill as the agent’s persistent memory. Without it, you have to explain the conventions again every session. With it, the agent already knows—and the knowledge lives in a file the whole team shares.
🧠 Instructions, not scripts
The most common mistake programmers make is treating a skill like a function. A skill doesn’t run — it is read. There is no "call"; activation happens through context. The agent compares the current situation with the description each installed skill and, when relevant, applies its instructions. You describe what e when, not the mechanical steps.
✗ Thinking like a script
- ✗"Step 1, step 2, step 3..." rigid
- ✗Wait for the skill to "run" and return
- ✗Vague description ("helps with code")
- ✗Assumes deterministic control flow
✓ Think like an instruction
- ✓Describe the behavior and why
- ✓Trusts that the agent applies it at the right moment
- ✓Description says WHAT it does AND WHEN to use it
- ✓Leaves room for the agent’s judgment
The description is the trigger
Because activation is context-based, the description is literally what determines whether the skill triggers. It needs to say what it does e when to use, and even be a little "pushy" — agents tend to under-trigger skills.
That’s why the skill body should explain the why things, instead of stacking MUSTs in all caps. Instructions with a reason are followed better than blunt commands.
🏆 Why the format won
There were many ways to teach an agent behavior—proprietary files, specific configs, binary plugins. The one that caught on was the simplest: Plain Markdown. For three reinforcing reasons: portability across agents, versioning via git, and a network effect measured in millions of installations.
Portable across 50+ agents
Markdown is the lowest common denominator. A skill written once works in Claude Code, Cursor, Copilot, Codex, and dozens of others. Your investment isn’t tied to one tool.
Versionable via git
Because it’s text, the skill fits into the workflows teams already know: PRs, diffs, review, history. Changed the convention? That’s a commit. No opaque binary format.
53.9M combined installs
The network effect has already happened: skills.sh totals 53.9 million installs. When everyone publishes in the same format, that format becomes the de facto standard — and reinforces itself.
💡 Why this matters to you
Writing a skill is one of the rare things in AI with a low risk of "vendor lock-in." The artifact is a .md. If the tool changes tomorrow, your skill will still be useful.
🔀 Skill vs. prompt vs. CLAUDE.md vs. MCP vs. subagent
A skill doesn’t replace the other layers—it coexists with them. The mistake is turning everything into a skill, or nothing. Each mechanism solves a different problem. The mental model below helps you choose.
💬 Prompt
Ephemeral; it only applies to that message. Use it for something one-off that you won't repeat. It doesn't scale or get versioned.
📌 CLAUDE.md (project rules)
Context always active that repository. Use it for rules that apply in every session of the project. It costs tokens all the time — so keep it to the essentials.
🔌 MCP
Gives the agent tools and data (call an API, read a database). It’s a capability, not knowledge. A skill says how to act; MCP provides what to use.
🤖 Subagent
One isolated executor with its own context, to delegate a heavy task without cluttering the main conversation. It's execution architecture, not reusable instructions.
🧩 Skill
Reusable knowledge that triggers based on context. Use it when a behavior repeats across many situations and is worth loading only when relevant—without taking up context all the time (unlike CLAUDE.md).
Rule of thumb for choosing:
é só desta vez? -> prompt vale sempre, neste repo? -> CLAUDE.md preciso de uma ferramenta? -> MCP quero delegar execução? -> subagente conhecimento que se repete? -> skill
💡 Watch context costs
The big advantage of a skill over CLAUDE.md is on-demand loading: only the name+description stay in context; the body is included only when the skill triggers. Extensive knowledge that isn’t always needed should become a skill, not a project rule.
📦 skills.sh as a registry — the “npm for skills”
If the skill is the “package,” the skills.sh is the registry — the npm of this world. It catalogs skills by repository, shows the installation count (the best public signal of quality and trust) and installs with one command.
📦 npm (Node.js)
- →
npm install react— installs a package - →downloads/week — adoption signal
- →central registry (npmjs.com)
- →package.json — local registry
🧩 skills.sh (agents)
- →
npx skills add owner/repo— installs a skill - →install count — adoption signal
- →central catalog (skills.sh)
- →GitHub repos — versioned source
Catalog usage flow:
# 1. descobrir no leaderboard / buscar npx skills find react # 2. instalar pelo caminho owner/repo npx skills add vercel-labs/skills # 3. listar o que está instalado npx skills list
Install count is your quality radar
As with any open registry, there are plenty of poor skills alongside great ones. Installation count is the cheapest filter: the most-installed skill in the catalog, find-skills (vercel-labs/skills), has 1.802.925 installs. frontend-design (anthropics/skills) has 488.299.
It’s not proof of quality, but it’s a strong indicator that many people trusted it—and kept using it.
👥 Who publishes
The ecosystem isn’t a walled garden belonging to one company. Major players and thousands of community members publish skills — altogether 5.075 source repos feed the catalog. That’s what gives the format its strength: no one owns it.
🟢 vercel-labs
Owner of installation champions like find-skills (1,8M), vercel-react-best-practices (443k) e web-design-guidelines (358k). Focused on web/frontend and agent tools.
🟢 anthropics
Publish the skill-creator (246k) — the canonical guide to writing skills — and frontend-design (488k). It’s the format’s structural reference.
🟢 microsoft
Via azure-skills, it dominates DevOps/Cloud: microsoft-foundry (360k), azure-ai (358k) and the azure-deploy/diagnostics/prepare family.
🟢 community
Most repos. Examples: obra/superpowers (test-driven-development, 107k), larksuite/cli (lark-slides, 139k), supabase, stripe, coreyhaines31.
Anatomy of a skill path in the catalog:
vercel-labs/skills # repo fonte (owner/repo) └── find-skills # a skill (1.802.925 installs) └── SKILL.md # o arquivo de instrução
💡 What this tells you
Big names dominate the hottest topics (web, cloud, agents). There’s plenty of room left in the niches they don’t cover—and that’s exactly where your community skill can lead. The full map is the subject of Module 1.2.
✅ Module Summary
Next:
1.2 — 🗺️ The skills.sh Map: 39k Skills, the Power Law, and the 16 Groups. Where the opportunities are and why most skills get almost no installs.