Claude Skills: What They Are, Why You Need Them, and How to Set Them Up

CLAUDE.md is great for project-specific context. It tells Claude about this codebase — the tech stack, the file structure, the conventions that are unique to this repo.

But some knowledge isn't project-specific. It's you-specific. Or team-specific.

You always want accessible HTML. You always want descriptive variable names. You always use a specific commit message format. You always check for security vulnerabilities before shipping. These aren't things that change between projects — they're your standards.

Without Skills, you have three options:

1. Copy-paste the same CLAUDE.md sections into every project
2. Re-explain your standards every session
3. Accept that Claude will forget and just wing it

None of these are good. Option 1 means maintaining multiple copies of the same instructions. Option 2 is tedious. Option 3 is how you ship inaccessible forms with div buttons.

Skills solve this: define your standards once, install them once, and they apply everywhere.

A Skill is a SKILL.md file with YAML frontmatter and markdown instructions.

That's it. It's not a plugin. It's not an extension. It's not executable code. It's structured knowledge that Claude reads and follows.

Here's the anatomy:

name: my-skill
description: What it does and when to use it

Your markdown instructions here. Claude follows these when the skill is active.

The `name` becomes a slash command (`/my-skill`). The `description` tells Claude when to load the skill automatically — if your task matches the description, Claude pulls in the instructions without you asking.

Skills follow the [Agent Skills](https://agentskills.io) open standard. They work across Claude Code, Cursor, Windsurf, Codex, and other tools. You're not locked in.

Here's how Skills compare to what you're probably already doing:

| | CLAUDE.md | Skills |
|---|---|---|
| **Scope** | One project | Personal (all projects) or per-project |
| **Portability** | Copy-paste between repos | Install once, use everywhere |
| **Activation** | Always loaded | Auto (when relevant) or manual (`/skill-name`) |
| **Shareability** | Send someone a file | `npx skills add owner/repo@skill` |
| **Structure** | Freeform markdown | YAML frontmatter + markdown |

The key insight: **CLAUDE.md is for "what's different about this project." Skills are for "what I always want, everywhere."**

The Skills CLI is built by Vercel. It's the package manager for the agent skills ecosystem.

Search for skills:

npx skills find accessibility

This gives you a list of matching skills with install commands.

Install one:

npx skills add wshobson/agents@accessibility-compliance

See what you have installed:

npx skills list

That's it. The skill is now active. Next time you ask Claude to build a component, it'll automatically apply the skill's instructions if your task matches the description.

A few more commands you'll want:

# Check for updates to your installed skills
npx skills check
 
# Update everything
npx skills update
 
# Manually invoke a skill in Claude Code
# Just type: /accessibility-compliance

You can also install skills for specific agents if you use multiple:

npx skills add wshobson/agents@accessibility-compliance -a claude-code -a codex

Where you store a skill determines who can use it:

Personal skills travel with you. Your coding style, your preferences, your review checklist. These apply to every project you open.

Project skills are committed to the repo. Team conventions, project-specific architecture patterns, component templates. Everyone who clones the repo gets them.

Enterprise skills are for companies that want org-wide standards. Managed through admin settings.

You can have personal AND project skills active at the same time. They stack. If they conflict, personal takes priority over project.

The most useful skills are the ones you write yourself. And they're simple — 90% of skills are just a SKILL.md file with no supporting files.

Here's a practical example. Let's say you always want Claude to follow a specific PR review checklist:

Step 1: Create the directory

mkdir -p ~/.claude/skills/pr-review

Step 2: Write the SKILL.md

Create ~/.claude/skills/pr-review/SKILL.md:

name: pr-review
description: Use when reviewing pull requests, code changes, or when the user asks to review code

When reviewing code changes, always check:

Code Quality

• Are variable names descriptive?
• Are there any types that should be specific?
• Are there console.logs or debug statements that should be removed?
• Is there duplicated logic that should be extracted?

Security

• No hardcoded secrets or API keys
• Input validation on user-facing endpoints
• No SQL injection or XSS vectors

Accessibility

• Semantic HTML elements used correctly
• ARIA labels on interactive elements
• Color contrast meets WCAG AA (4.5:1)
• Keyboard navigable

Testing

• Are there tests for new functionality?
• Do existing tests still pass?

Provide feedback as a numbered list with file:line references.

**Step 3: Use it**

Now you can either:

- **Let Claude auto-invoke it** by asking: "Review these changes" (Claude matches the description)
- **Invoke it manually**: `/pr-review`

That's a personal skill — it'll apply across every project you work on.

For a **project skill**, same process but in the repo:

```bash
mkdir -p .claude/skills/component-patterns

Then commit .claude/skills/component-patterns/SKILL.md to your repo. Every team member who uses Claude Code on this project gets those instructions automatically.

Advanced Features (Brief)

Skills can do more than just static instructions. A few things worth knowing:

• Arguments: Use $ARGUMENTS or $0, $1 for positional args. /fix-issue 123 passes "123" into the skill.
• Dynamic context: Use !`command` to inject command output before Claude sees the skill. !`gh pr diff` injects the actual PR diff.
• Subagent execution: Add context: fork to run the skill in isolation with its own context window.
• Tool restrictions: Add allowed-tools: Read, Grep, Glob to make a skill read-only.
• Supporting files: Include reference docs, templates, or scripts alongside SKILL.md.

You don't need any of these for most skills. But they're there when you do. Full docs here.

I'll share what actually happened on this blog.

I wanted to bring the site up to WCAG 2.1 AA standards. Before Skills, that conversation with Claude looked like this:

"Hey Claude, make sure this component is accessible."

And Claude would do... some things. Add some aria-labels. Maybe fix some contrast. It was inconsistent — it didn't have a concrete definition of what "accessible" means in my context.

So I installed two accessibility skills:

npx skills add wshobson/agents@accessibility-compliance
npx skills add addyosmani/web-quality-skills@accessibility

The first one covers WCAG 2.2 standards and ARIA patterns. The second is a WCAG 2.1 audit checklist organized by the POUR principles (Perceivable, Operable, Understandable, Robust).

After installing them, I asked Claude to audit my site. The difference was immediate. Instead of vague "add some aria-labels" suggestions, it systematically checked:

• Touch targets (minimum 44x44px)
• prefers-reduced-motion support
• Screen reader announcements for dynamic content (aria-live)
• Semantic HTML elements (<nav>, <time>, <ol>)
• Focus indicators on all interactive elements
• External link announcements ("opens in new tab")
• Form input labels and autoComplete attributes

It found 35 issues across 15 components. We fixed all of them in one session.

The takeaway: The skills didn't make Claude smarter. They made it specific. Instead of guessing what "accessible" means, it had a concrete checklist to follow. That's what skills do — they replace vague intent with precise instructions.

skills.sh is the community marketplace for skills. Built by Vercel. You can browse online or search from the CLI.

Some categories worth exploring:

npx skills find react          # React best practices
npx skills find testing        # Testing patterns
npx skills find security       # Security auditing
npx skills find nextjs         # Next.js conventions
npx skills find code-review    # Code review checklists

Honest caveat: This ecosystem is still young. The marketplace has grown fast — some skills have thousands of installs — but the most useful skills will probably be the ones you write yourself. Community skills are a great starting point, but they're generic by definition. Your team's conventions, your project's architecture, your standards — those need custom skills.

Security note: Skills are just markdown instructions, not executable code. The supply chain risk is much lower than npm packages. That said, you should still read what you're installing. A malicious skill could instruct Claude to do things you don't want — exfiltrate data, introduce vulnerabilities, etc. Always review the SKILL.md before installing.

Yes, if you:

• Use Claude Code regularly
• Have coding standards you re-explain constantly
• Work across multiple projects with shared conventions
• Want to share your team's standards in a portable format
• Care about consistency (accessibility, security, testing)

Not yet, if you:

• Just started using Claude Code (get comfortable with CLAUDE.md first)
• Only work on one project (just put everything in CLAUDE.md)
• Want plug-and-play magic (skills require you to write good instructions)

The bottom line: Skills are CLAUDE.md that grew up. If you've been copying the same instructions between projects or re-explaining the same standards every session, this is the fix. It takes 10 minutes to set up your first one, and it pays off every session after that.

Start with one skill for your most-repeated standard. You'll immediately see the difference. More from the AI tools series:

• My Actual Dev Setup: Google Antigravity + Claude Code
• Cursor vs. Windsurf vs. Claude Code: The AI Coding Editor War
• MCP Tutorial: Build AI Agents That Actually Do Things