Why Skills Feel Harder Than They Are — and the One Choice That Trips People Up

If you've been putting off learning Claude Code skills because they sound like another integration project — another SDK, another config file, another thing to debug — here's the surprise: a skill is just a markdown file on disk. The whole format is filesystem-based and minimal, requiring a directory, one SKILL.md file with YAML frontmatter, and almost no technical knowledge. The install is genuinely the easy part.

Part of why skills feel heavier than they are is history. Anthropic introduced Skills in October 2025, then released the format as an open standard in December 2025. Today the Agent Skills specification is supported across Claude Code, Claude.ai, the Claude API, OpenAI Codex, Cursor, Gemini CLI, Antigravity, and Windsurf — meaning one skill you write travels across most of your toolchain.

The one real decision is where the file lives, and it comes down to two paths:

• Personal skills at `~/.claude/skills//SKILL.md` — available in all your projects on that machine
• Project skills at `.claude/skills//SKILL.md` — scoped to that repo, and committable so your whole team gets them
• Enterprise and plugin locations also exist, but most people start with one of the two above

Neither choice is wrong; it just depends on whether the skill is yours alone or shared work. Either way, the mechanics stay the same: one folder, one file.

And thanks to progressive disclosure, keeping skills installed is nearly free. Only each skill's name and description load at session start — roughly 100 tokens per skill — while the full body, typically under 5,000 tokens, loads only when relevant. A large library costs almost nothing until you actually use it.

The genuinely hard question isn't "how do I install a skill?" It's "where do I get one worth installing?" Community repositories list 1,000+ skills, but published research found that roughly 26% of skills carry at least one vulnerability, and official guidance stops at "review downloaded skills before enabling." That trust gap is why SkillzBench exists — an independent lab building a pipeline that discovers, verifies against commit SHAs, security-scans, and benchmarks every skill in a sandbox so you know which ones actually help before they touch your agent. The install takes five minutes. Knowing what to install is the part worth slowing down for.

The 3-Step Minimal Install: Directory, SKILL.md, Test

A full skill install is one directory, one file, and one slash command — the format is deliberately that minimal. Anthropic designed skills as "local, domain-specific instructions in markdown files... requiring minimal setup and almost no technical knowledge," according to LlamaIndex's technical writeup.

Run:

mkdir -p ~/.claude/skills/<skill-name>

That path — ~/.claude/skills/ — makes the skill available in all your projects on that machine, per the official Claude Code docs. If you want the skill scoped to a single repo and shared with your team, use .claude/skills/<skill-name>/ instead and commit it.

Inside that directory, create a SKILL.md file with YAML frontmatter followed by plain markdown instructions. The frontmatter has two required fields with hard limits, per Anthropic's support guide:

• name — 64 characters max, a display label for the skill.
• description — 200 characters max, and the single most important field: Claude uses it to decide when to invoke the skill.

The body should stay lean. Official best practices recommend keeping it under 500 lines, because Claude may be choosing from 100+ available skills based on descriptions alone.

Invoke the skill with /skill-name or just start a session and let Claude load it automatically when the task matches. If something misbehaves, run /doctor — Claude Code bundles it precisely to diagnose installation health, extensions, and permissions.

Skills use progressive disclosure: at session start, only each skill's name and description load — roughly 100 tokens per skill, per IntuitionLabs' analysis. The full body, typically under 5,000 tokens, loads only when the skill is actually used. As the docs put it, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it. You can install dozens of skills without bloating every session.

The invoke command comes from the directory name, not the frontmatter name field. A skill at .claude/skills/deploy-staging/SKILL.md gives you /deploy-staging even if its frontmatter says name: Staging Deploy. The name field is only a display label — a mismatch here is a common reason people think their install failed.

That cheap-to-keep architecture is also why skill libraries grow fast — and why vetting what you install matters. With community repositories listing 1000+ skills and published research finding roughly a quarter carry at least one vulnerability, SkillzBench is building a Discover, Verify, and Benchmark pipeline to test every skill in a sandbox with and without it, so you know which ones actually earn their ~100 tokens.

The Description Field: Why Most 'Broken' Skills Are Actually Description Problems

Your skill installed perfectly. The file is in the right directory, the frontmatter parses cleanly — and Claude never once invokes it. The culprit is almost never the installation: it's the description field.

Here's why. Thanks to progressive disclosure, only each skill's name and description load at session start — roughly 100 tokens per skill — while the full body loads only when Claude decides it's relevant. That decision rests entirely on the description. Per Anthropic's best-practices guidance, Claude may be choosing from 100+ available skills based on description alone, so a vague one simply never gets picked. As one in-depth technical guide puts it: the description is not metadata — it is the trigger.

The fix is concrete. Compare these two descriptions for the same deployment skill:

• Before: "Helps with deployments." — true, useless, never fires.
• After: "Deploys the staging environment to AWS ECS: runs migrations, validates health checks, rolls back on failure. Use when the user asks to deploy staging or push a staging release." — specific triggers, specific scope.

The after version tells Claude exactly when to reach for the skill, which is the entire game. Keep the description under the 200-character limit, and name the situations where it applies.

Body length matters too. The official best practices recommend keeping SKILL.md under 500 lines, with a table of contents for any reference files longer than 100 lines. And apply a simple heuristic for what belongs where: always-true facts about your project go in CLAUDE.md, while on-demand procedures and specialized knowledge belong in skills. Multiple focused skills compose better than one large skill, so split rather than bloat.

This trigger problem is also why quality-judging third-party skills is hard: a skill can be well-written, secure, and still never fire because its author wrote a lazy description. It's one of the signals SkillzBench is building into its quality-judging pipeline as it constructs its Discover, Verify, and Benchmark stages — a skill that can't be triggered correctly can't demonstrate Lift, no matter how good its instructions are.

If your skill is installed but silent, rewrite the description first. Nine times out of ten, that's the whole problem.

Verify Your Install — and Vet What You Install

Your skill is installed — but "installed" and "working" are two different things. Before you trust it in a real session, spend thirty seconds confirming Claude Code actually sees it.

Claude Code ships a built-in diagnostic for exactly this: run /doctor to check your installation health, extensions, and permissions in one pass. If your skill doesn't appear, the fix is usually mechanical. Remember that the invoke command comes from the directory name, not the frontmatter — .claude/skills/deploy-staging/SKILL.md gives you /deploy-staging, regardless of what the name field says.

The subtler failure is a skill that loads but never fires. Claude may choose among 100+ available skills based on the description alone, and as one technical guide puts it, almost every "my skill isn't working" problem is a description problem. A quick sanity check:

• Run `/doctor` and confirm no installation or permission errors
• Invoke the skill directly with `/skill-name` to force a load
• If Claude ignores it, rewrite the description (200 characters max) so the trigger conditions are explicit

Here the verification story gets harder. /doctor checks your setup — but nothing checks the skill itself. Community repositories list 1000+ skills and plugins, and official guidance for vetting them amounts to "review downloaded skills before enabling." Published research has found that roughly 26% of skills carry at least one vulnerability. Reading a SKILL.md tells you what a skill says it does; it rarely tells you what it actually does to your agent's behavior.

There's also an effectiveness question that nobody's answering. LlamaIndex's own testing found skills were sometimes "rarely invoked" and didn't outperform other context approaches — a reminder that a skill being safe doesn't mean it helps.

This is the gap SkillzBench is being built to close. Its pipeline — version-pinned to a commit SHA, security-scanned, license-checked — publishes a Lift score measured in a sandbox: the same model, the same task, with and without the skill. Lift is always reported separately from trust ratings, and money never touches scores. At launch, instruction-only skills get full treatment; script-bearing skills are listed link-out only until they can be scanned safely.

Installation takes under five minutes. Knowing whether a skill actually earns its place in your context window is the part worth doing properly — and soon, you won't have to guess.

Skills, proven. Join the SkillzBench waitlist to see verified, benchmarked skill loadouts as they launch.

From One Skill to a Trusted Loadout

Installing your first skill takes minutes. Building a library you can actually trust is a different problem entirely.

The good news is that skills are cheap to keep around. Thanks to progressive disclosure, each skill costs only ~100 tokens of metadata at session start, with the full body loading on demand — so a large library costs almost nothing until you use it. That means the real constraint isn't context budget. It's confidence.

That confidence erodes fast at scale. Anthropic's own guidance is to "review downloaded skills before enabling," and with over 1,000 curated community skills already circulating, manual review doesn't hold up. Published research found that roughly 26% of skills carry at least one vulnerability. Upstream repositories change, maintainers push updates, and yesterday's safe install becomes today's unknown.

Focused skills also compose better than sprawling ones — official guidance recommends multiple narrow skills over one large one. Your loadout should follow the same logic:

• Curate per agent, not globally — Claude Code, Codex, Cursor, and Gemini CLI have different needs.
• Pin versions so you know exactly what you're running, not "whatever was on main last week."
• Re-verify on upstream changes, because a skill that was safe at install time may not stay that way.
• Measure actual Lift, not vibes — LlamaIndex's own testing found some skills were "rarely invoked" at all.

Doing all of that by hand doesn't scale. SkillzBench, an independent testing lab from AIQ Labs, is building exactly this pipeline: continuously discovering skills from GitHub, pinning every version to a commit SHA, security-scanning and license-checking each one, then benchmarking them in a sandbox — same model, with and without the skill — so you see the Lift in percentage points, always shown separately from ratings.

The plan is a single MCP server with per-agent toggles: your agent sees only the skills and tools you've enabled for it, each carrying a 0–100 trust score built from security, quality, license, maintenance, and community signals. Upstream changes trigger re-scans, re-benchmarks, and notifications, so your loadout stays current without you babysitting it.

SkillzBench is pre-launch and actively being built, but the waitlist is open now. Join it at skillzbench.com to get early access to verified, benchmarked skill loadouts for each of your agents.

Skills, proven.