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 from one of the registries (LobeHub Skills, SkillsMP, SkillHub, or mcpmarket.com/tools/skills), 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 handful of public marketplaces, and Anthropic’s official skills repo as the canonical 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.

Skill marketplaces (LobeHub Skills, SkillsMP, SkillHub) in 2026

Four marketplaces matter in practice. LobeHub Skills is the largest by 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 if you don’t know what to install. SkillsMP is the highest‑volume catalog, with roughly 30,000+ entries as of May 2026, but the list mixes pure skills with prompts, agents, and MCP servers, so you’ll want to 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 is the smallest but cross‑links each skill to related MCP servers, which is handy when you want the skill and the underlying integration in one install. A Claude Skills Marketplace Comparison 2026 writeup at openaitoolshub.org compares six platforms side by side and is worth a read before you commit.

The installation flow is the same across all four: download the skill folder (or git clone it), drop it into ~/.claude/skills/<name>/, and the next agent session sees it. For Cursor Agents, mirror it into .cursor/skills/<name>/ (per‑project) or ~/.cursor/skills/<name>/ (global, where supported). For Codex CLI and other AGENTS.md‑compatible tools, the convention is ~/.agents/skills/<name>/. Many users symlink one canonical directory to all three locations so they 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 with two required fields (name, description) and a few optional ones (version, tools, model). Then 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.
version: 1.0.0
---

# 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. Pick from LobeHub Skills, SkillHub, or SkillsMP. Sensible starting set: code-review, 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/.