← All posts

The Complete Guide to AI Agent Skills (and How to Pick Ones That Actually Work)

2026-09-10

A practical guide to the agent-skill ecosystem — what skills are, where to find them, and how to tell the great ones from the prompt-wrappers before you install.

AI coding agents have quietly gained a superpower most people haven't fully explored yet: skills.

A skill is a folder of instructions — usually a SKILL.md file plus optional scripts, references, and templates — that teaches your agent how to do a specific job well. Install a PDF skill and your agent suddenly knows how to extract, merge, and manipulate documents. Install a debugging skill and it stops guessing at bugs and starts isolating them systematically.

Claude Code ships with a handful of official skills. The community has built hundreds more. But there's a problem: the ecosystem has no quality floor. Some skills are meticulously engineered. Others are a single paragraph of vague instructions wrapped in a folder. And a few — including one with tens of thousands of GitHub stars — instruct your agent to do genuinely unsafe things.

This guide covers what you need to know: how skills work, where to find them, and the evaluation framework we built at Skill123 to separate the signal from the noise.

What is an agent skill, exactly?

Technically, a skill is just a directory containing a SKILL.md file with YAML frontmatter:

my-skill/
├── SKILL.md          ← the core: name, description, instructions
├── scripts/          ← optional executable code
├── references/       ← optional deep-dive docs
└── assets/           ← optional templates

The magic is in the description field. When you chat with your agent, it scans the descriptions of all installed skills and loads the relevant one into context. A well-written description fires at exactly the right moment; a lazy one either never triggers or triggers constantly.

The best skills follow a pattern Anthropic calls progressive disclosure: a lean SKILL.md (under 500 lines) with the essentials, plus references the agent loads only when needed. This keeps context usage low and accuracy high.

Where the skills live

The problem: stars ≠ quality

GitHub stars measure attention, not engineering. A skill can be popular because it was early, because it's funny, or because the README is charming — while its instructions are ambiguous, its scripts are broken, or its trigger description is so vague the agent never actually uses it.

Worse, skills run with your agent's full permissions. A skill that says "read the browser cookies and send them to this API" reads almost the same as one that says "read the browser history and summarize it." If you install skills the way you install npm packages — trust the stars, skim the README — you're doing security by vibes.

When we started evaluating skills for Skill123, we found exactly this: a widely-shared research skill whose scripts parse Safari's cookie store and decrypt Chromium credential databases. It had a five-figure star count. Nobody had flagged it, because nobody was reading the scripts.

The six-dimension evaluation framework

Every skill on Skill123 is scored on six dimensions, 100 points total, with written rationale for each score:

1. Trigger Quality (20 pts) — Does the description say what the skill does, when to use it, and when not to? Does it cover the phrases a user would actually type? The best descriptions read like they were written by someone who watched real users miss the skill ten times.

2. Structure (15 pts) — Is the content split correctly between SKILL.md, references/, scripts/, and assets/? A 900-line SKILL.md with no offloading burns context on every activation; a 40-line one that references files that don't exist is worse.

3. Workflow Design (25 pts) — The heavyweight dimension. Is the skill task-oriented (steps the agent executes) rather than topic-oriented (facts the agent reads)? Are high-risk steps constrained with low freedom (exact commands) while creative steps get high freedom? Is there a verification loop so the agent can check its own work?

4. Content Quality (10 pts) — Concise, imperative, executable. Commands with real arguments, not run the tool with the appropriate options.

5. Engineering (10 pts) — Valid frontmatter, runnable scripts, file paths that actually resolve in the shipped package. You'd be surprised how many published skills reference files they forgot to include.

6. Security (20 pts) — Static analysis of every script and document: no undeclared network calls, no obfuscated execution, no credential access, no prompt injection ("ignore previous instructions and..."). One confirmed violation of the hard rules caps the total score at 39/100 — an automatic fail.

That last rule isn't theoretical. We delisted a popular skill on day one of this policy.

What the data shows after evaluating 493 skills

A few patterns from our evaluation database:

Trigger descriptions are the weakest link. The most common failure across the ecosystem is a missing "when NOT to use this" clause. Skills without boundaries trigger on adjacent requests and pollute context.

Structure quality is bimodal. Skills from experienced authors (Anthropic's own, the superpowers methodology suite, well-maintained collections) consistently nail progressive disclosure. Everything else tends toward one extreme or the other: bloated single files or skeletal stubs pointing at missing references.

Security is mostly fine — until it isn't. The overwhelming majority of skills are benign document generators and API wrappers. But the violations we did find were serious (credential harvesting, prompt injection) and all of them came from skills with strong social proof. Popularity and safety are uncorrelated.

How to evaluate a skill yourself in five minutes

Even without a formal framework, you can filter out most of the noise:

  1. Read the description first. Does it tell you when not to use it? No → expect false triggers.
  2. Count the files. SKILL.md over ~500 lines with no references/ → context hog. References that don't exist in the repo → broken.
  3. Grep the scripts for curl, wget, eval, base64, and paths like ~/.ssh, ~/.aws, Cookies. Every hit should have an obvious, declared purpose.
  4. Look for a verification step. "After running, check that X is true" separates engineering from prompt-writing.
  5. Check the freedom gradient. Destructive or external-facing actions should have exact, low-discretion instructions. Creative output should have room.

    6. Installing skills

    Once you've picked a skill worth installing, there are three ways, all supported on Skill123:

    One-liner install (curl the installer and run it):

    curl -fsSL https://skill123.me/install/<skill-slug>.sh | bash

    Install via AI — copy a single prompt into Claude Code and it fetches the instructions and installs the skill itself:

    Install the "humanizer" skill by following the instructions at
https://skill123.me/install/humanizer.

    Manual — download the zip, extract to ~/.claude/skills/, restart your session.

    Yes, curl | bash deserves the standard caution: read the installer first (ours is ~30 readable lines), and prefer skills whose evaluation notes you've actually skimmed.

    Where to start

    If you're new to skills, these categories have the highest concentration of quality on Skill123 right now:

    • Documents — the official PDF/DOCX/XLSX/PPTX skills are the gold standard of the format
    • Developer Tools — debugging methodology, TDD, and constraint-driven development
    • Writing — translation, grammar, content auditing
    • Design & Creative — diagrams, infographics, and AI image generation
    • Data & Analytics — pandas, SQL, and experiment analysis

    Every skill page shows the full six-dimension scorecard with the reasoning behind each number — so you can disagree with us, which is the point. An evaluation you can inspect is worth ten you can't.

    Skill123 is a curated directory of AI agent skills, with every entry evaluated across six dimensions before listing. Browse the leaderboard or search all 493 skills.