Agent skills — install from marketplaces and author your own

Scorecard question: How do you use agent skills (SKILL.md)? Max‑score answer (3 pts): I also author my own skills in ~/.claude/skills/, .cursor/skills/, or ~/.agents/skills/.

Why this matters in 2026

Skills are the most under‑used Tier‑1 feature in the 2026 agent stack. They’re reusable, model‑invoked playbooks: a folder with a SKILL.md (plus optional scripts and templates) that the model loads on its own when the situation matches the skill’s description — no slash command, no manual import, no MCP server, no subagent. In December 2025 Anthropic published the Agent Skills spec as an open standard at agentskills.io, and within weeks OpenAI adopted the same SKILL.md format in Codex CLI and ChatGPT, followed by Cursor’s .cursor/skills/ folder. As of May 2026 the format is genuinely cross‑tool: the same SKILL.md runs unchanged in Claude Code, Codex CLI, Cursor Agents, and Gemini CLI. That standardization is what turned skills into the highest‑leverage extensibility primitive across all four major agents.

The reason Q8 separates a 2‑point setup from a 3‑point setup is that installing skills is table stakes by 2026; authoring them is the compound move. Marketplace skills are great for instant level‑ups in domains someone else mapped (Stripe, accessibility, shadcn, Sentry triage). But the highest‑value skills encode the lessons your future self keeps re‑learning — the migration steps for your specific Drizzle + D1 setup, the way your team writes Astro endpoints, the repro harness for that flaky E2E test. Nobody else can write those for you, and every time your agent figures them out from scratch it’s burning tokens it didn’t need to.

What “max score” actually looks like

A max‑score Q8 setup has both halves wired in. You have 10–30 marketplace skills installed — ideally via npx skills add <owner/repo> from the skills.sh registry, or browsed from LobeHub Skills / SkillsMP / SkillHub — covering universal stuff — code review, SEO audits, Stripe / Polar testing, Resend, shadcn UI, Sentry fix loops. They live in ~/.claude/skills/ (and a symlinked .cursor/skills/ and ~/.agents/skills/ so all three tools see them). You also have 3–10 of your own skills: at least one per active repo, at least one personal skill for a cross‑project workflow (e.g. “ship a PR and watch the review loop”), and at least one team skill for a non‑obvious in‑house pattern.

When a session needs a skill, you don’t summon it — the model invokes it on its own, because the description in your SKILL.md matched the request. You’ll see lines like Loading skill: stripe-best-practices or Reading skills/your-repo-conventions/SKILL.md in the agent transcript without typing anything. You revise skills as you learn: when a session reveals a new gotcha, you don’t just fix the immediate problem, you add a sentence to the relevant SKILL.md so the next session doesn’t trip on it. That feedback loop is the difference between “I have skills” (2 pts) and “skills are how I capture and reuse my expertise” (3 pts).

Current landscape (web‑search‑verified)

The 2026 skills ecosystem has three pillars: an open format (SKILL.md plus YAML frontmatter), a canonical registry plus a handful of public marketplaces, and Anthropic’s official skills repo as the reference implementation. All three tools (Claude Code, Codex CLI, Cursor Agents) read the same format from their respective skills directories — you no longer need separate plugin ecosystems per tool.

skills.sh and the one‑command install

The canonical, tool‑agnostic registry is skills.sh — it indexes tens of thousands of skills across the major source repos (anthropics/skills, vercel-labs/agent-skills, remotion-dev/skills, supabase/agent-skills, and more) and installs them with a single command:

npx skills add <owner/repo>          # e.g. npx skills add anthropics/skills
npx skills add vercel-labs/agent-skills

The skills CLI (from vercel-labs/skills) writes the skill into every agent’s skills directory it detects — Claude Code, Codex CLI, Cursor, OpenCode, Gemini, and 35+ others — so you skip the manual download‑and‑symlink dance entirely. This is the install method to reach for first; the marketplaces below are for discovery when you don’t yet know what to install.

Discovery marketplaces (LobeHub Skills, SkillsMP, SkillHub)

Beyond skills.sh, a few catalogs help you browse. LobeHub Skills is strong on curation quality — it explicitly targets Claude Code, Codex CLI, and ChatGPT, and every entry is a SKILL.md file (not a prompt, not an MCP server). Categories include workflow, design, marketing, dev tooling, and integrations; the homepage lists a “Top 20 All Skills” board that is a sensible starting point. SkillsMP is the highest‑volume catalog — tens of thousands of entries and growing fast — but the list mixes pure skills with prompts, agents, and MCP servers, so filter by “Skill” only. SkillHub sits in between, with 7,000+ AI‑evaluated skills explicitly tagged for Claude, Codex, Gemini, and OpenCode — its evaluation column is useful for filtering low‑quality entries. MCP Market’s Skills directory cross‑links each skill to related MCP servers, handy when you want the skill and the underlying integration.

Once you’ve found a skill, prefer npx skills add <owner/repo> over a manual git clone + copy — it lands the skill in all your agents’ skills dirs at once. The fallback manual flow still works if a skill isn’t in the registry: clone the folder, drop it into ~/.claude/skills/<name>/, then mirror it into .cursor/skills/<name>/ (Cursor, per‑project) and ~/.agents/skills/<name>/ (Codex CLI and other AGENTS.md tools), symlinking one canonical directory so you only maintain it once.

Anthropic’s official skills (anatomy of SKILL.md)

The anthropics/skills repo on GitHub is the canonical implementation reference and the place to look when you want to learn the patterns by example. It ships the skill-creator skill — yes, a meta‑skill that teaches Claude how to write SKILL.md files — plus dozens of production‑grade examples covering code review, design audits, frontend design, prompt authoring, and more.

The structure of a real SKILL.md is small and prescriptive. YAML frontmatter at the top — all fields are optional, but description is the one that really matters (Claude Code defaults name to the folder name when it’s omitted). Optional fields in Claude Code include allowed-tools, model, and argument-hint / disable-model-invocation / user-invocable. Then a markdown body with the actual instructions, optionally grouped under ## When to use, ## Steps, ## Examples, ## Gotchas. Optional sibling files (scripts, templates, JSON reference data) are referenced from the markdown via relative paths and loaded lazily — only when the body of the skill tells the agent to read them.

The description field is the single most important line in the entire skill, because it’s the only thing the model sees at startup. At session boot, the agent pre‑loads just the name and description of every installed skill — nothing else. It reads the SKILL.md body only when the description matches a user request, and reads any referenced sub‑files only when the body tells it to. This is called progressive disclosure and it’s the reason a setup with 50 skills doesn’t blow your context window: at boot you pay maybe 2 KB of metadata, not 200 KB of full skill content.

Authoring your own (directory structure, description for discovery, when triggered)

A custom skill is just a folder. Minimum viable example for a Claude Code user:

~/.claude/skills/my-repo-conventions/
├── SKILL.md          # the playbook (required)
├── examples/         # optional: code samples the skill references
│   └── astro-endpoint.ts
└── scripts/          # optional: helper scripts the skill can run
    └── run-tests.sh

For Cursor: mirror to .cursor/skills/my-repo-conventions/ (project) or ~/.cursor/skills/ (global). For Codex CLI / Gemini CLI / other AGENTS.md tools: ~/.agents/skills/my-repo-conventions/.

A working SKILL.md looks like this:

---
name: my-repo-conventions
description: Conventions for the developer-toolkit repo — Astro server endpoints on Cloudflare Workers with D1 + Drizzle, paywall in /public/paywall-inline.js, EN/PL content under src/content/docs/{en,pl}. Use whenever editing this repo's API routes, MDX docs, paywall, or DB schema.
---

# Developer Toolkit repo conventions

## When to use

Trigger this skill whenever the user is working in the `developer-toolkit` repo
(or any worktree under `.claude/worktrees/`). Specifically:

- Editing `src/pages/api/**.ts` (API routes)
- Editing `src/content/docs/{en,pl}/**.mdx` (Starlight docs)
- Editing `/public/paywall-inline.js` (paywall UI)
- Touching `src/lib/db/schema.ts` or `scripts/schema.sql` (DB schema)

## Steps

1. API routes go in `src/pages/api/`. Always pull bindings off
   `locals.runtime.env` (D1 = `DB`, KV = `KV`, session = `SESSION`).
2. Docs ship in pairs — EN at `src/content/docs/en/<section>/<slug>.mdx`
   and PL at `src/content/docs/pl/<section>/<slug>.mdx`. Don't ship one
   without the other.
3. Paywall changes are vanilla JS only in `/public/paywall-inline.js`.
   Do not introduce TypeScript or a framework into that file.
4. After any DB schema change, update both `src/lib/db/schema.ts` and
   `scripts/schema.sql`, then add a migration under
   `migrations/<timestamp>-<slug>.sql`.

## Gotchas

- `npm run deploy` is CI‑only — never run it locally except for
  `--dry-run`. CI deploys on push to master.
- Submodules under `src/content/docs/` are private — pull with
  `npm run submodule:pull`, not `git submodule update` directly.

What makes that description work: it’s specific (mentions the actual stack, paths, and file names), it lists explicit trigger conditions (“whenever editing this repo’s API routes, MDX docs, paywall, or DB schema”), and it leans slightly pushy — Anthropic’s own skill‑authoring guide explicitly warns that Claude tends to under‑trigger skills, so descriptions should err on the side of “yes invoke me” rather than “maybe consider me”. The body then keeps it short, uses progressive disclosure (referencing files only when needed), and explains why for the gotchas so the model can generalize beyond the literal list.

Step-by-step: building a skill

Audit what you keep re‑explaining. Open your last week of agent transcripts (Claude Code: ~/.claude/projects/<repo>/transcripts/; Codex CLI: ~/.codex/sessions/). Find the three things you typed more than twice. That’s your first skill backlog: each repeated explanation is a skill you should have written.
Install 5–10 marketplace skills before you write your first one. Use the one‑command installer rather than hand‑cloning: npx skills add anthropics/skills, npx skills add vercel-labs/agent-skills, and so on — each writes into all your agents’ skills dirs at once. Browse skills.sh (or LobeHub Skills / SkillHub / SkillsMP) to find them. Sensible starting set: a code-review skill, one stack‑specific skill (e.g. nextjs-best-practices or astro-best-practices), one design skill (refactoring-ui), one ops skill (sentry-fix-issues), and the skill-creator meta‑skill from anthropics/skills. Reading other people’s SKILL.md files is the fastest way to internalize the format.
Create the directory. mkdir -p ~/.claude/skills/<your-skill-name>/. For cross‑tool sharing, also create ~/.cursor/skills/ and ~/.agents/skills/ and symlink the same folder into both. (ln -s ~/.claude/skills/<name> ~/.cursor/skills/<name> etc.)
Write the YAML frontmatter first. Two fields are required: name (lowercase‑hyphen, must match folder name) and description (one sentence, specific, lists trigger conditions, slightly pushy). Spend more time on the description than on the body — it’s literally the only thing the model sees at startup. If your description is generic (“helps with code”), the skill will never trigger.
Write the body in three sections. ## When to use lists concrete trigger conditions, files, or task types. ## Steps is the actual playbook — numbered, executable, opinionated. ## Gotchas lists the traps with the reason for each (the why lets the model generalize). Keep the whole file under ~300 lines; if it gets longer, split into sub‑files and reference them from the body so they load lazily.
Test by inviting it. Open a new agent session in a relevant repo and describe a task that should trigger the skill. Watch the transcript: did the model load the skill on its own? If yes, you’re done with v1. If no, your description was too generic — add more specific trigger conditions and try again. Don’t rely on “tell the model to use the skill” — that defeats the model‑invoked design.
Iterate on every session. Every time a session reveals something the skill should have known but didn’t, add a sentence (or a Gotcha) to the SKILL.md. Commit the skill to a personal dotfiles repo or a team skills/ repo so it survives machine moves and gets shared. By month three you’ll have 5–10 skills that compound — each one cuts the same class of mistake to zero.

Common pitfalls

Overly generic description. “Helps with TypeScript” or “Code review skill” — these will never trigger because every task vaguely involves TypeScript or code review. The description must list specific trigger conditions (“whenever editing files under src/pages/api/”, “when the user mentions Stripe webhooks or PaymentIntent objects”). If you can’t articulate when it should fire, the model can’t either.
No trigger conditions, only steps. A SKILL.md that’s just a ## Steps section with no ## When to use block tells the model what to do but not when to do it. Result: the skill loads metadata at boot, then sits dormant forever because the description didn’t connect to any concrete signal.
Not testing whether the skill triggers. Authors write a skill, see it sitting in ~/.claude/skills/, and assume it’s working. It might not be. Open a fresh session, describe a relevant task without naming the skill, and confirm the transcript shows the model loaded it. If it didn’t, the description is broken — fix it before moving on.
One mega‑skill for everything. A 2,000‑line SKILL.md that covers your whole repo, your team conventions, your favorite libraries, and your debugging workflow is unusable. The model loads it once for “any task in this repo” and burns tokens on irrelevant sections. Split into focused skills (one for API routes, one for DB schema, one for docs) so the model loads only what’s relevant.
Skipping the marketplace step. Authors who write skills before installing any feel like they’re inventing the format from scratch. Install 5–10 marketplace skills first, read their SKILL.md files, then write your own. You’ll save hours on conventions and discover patterns (progressive disclosure, slightly‑pushy descriptions, the ## When to use block) that aren’t obvious from the spec alone.
Forgetting to mirror across tools. If you only put skills in ~/.claude/skills/, your Codex CLI and Cursor Agents sessions won’t see them. Either symlink the directory into all three tool‑specific locations (~/.cursor/skills/, ~/.agents/skills/) or keep one canonical ~/skills/ folder and symlink it everywhere. Without this, your custom skills only work in one tool, which kneecaps the whole point of the open format.

How to verify you’re there

You have 10+ marketplace skills installed in ~/.claude/skills/ (or the equivalent for your primary tool) — not zero, not three.
You have 3+ of your own skills authored, with at least one project‑specific and one personal/workflow skill.
Each of your skills has a description that lists specific trigger conditions, not a generic one‑liner.
Your skills are mirrored or symlinked across ~/.claude/skills/, .cursor/skills/, and ~/.agents/skills/ so all three tools see them.
In a recent transcript, you can point to at least one line where the model auto‑loaded a skill (Loading skill: <name> or Reading skills/<name>/SKILL.md) without you naming the skill in the prompt.
When a session reveals a gotcha or repeated explanation, you add it to the relevant SKILL.md before closing the loop — not “later”, not “in a doc somewhere”.
Your skills live in version control (personal dotfiles repo or a team skills/ repo), not as ephemeral files in ~/.claude/.