Claude Code Skills: The Feature Nobody Talks About (But Should)

A casual deep-dive into Claude Code skills — what they are, how matching works, project vs personal skills, skill priority, agents, and all the things that make them click.

Jun 22, 2026

Claude CodeAIDeveloper Tools

I’ve been using Claude Code for a while now. And the feature I use most — the one that changed how I think about AI tooling — isn’t the model, isn’t the MCP servers, isn’t even the agent mode.

It’s skills.

Most people set them up once, use /review or /deploy a few times, and think that’s the whole story. It’s not. There’s a whole system underneath that, once you understand it, makes Claude genuinely feel like a teammate rather than a tool.

Let’s go through all of it. Casual, with examples.

So… what even is a skill?

A skill is a markdown file that teaches Claude how to handle a specific slash command.

When you type /code-review in your terminal, Claude doesn’t just know what to do because it’s smart. It knows because somewhere on your machine there’s a file that tells it exactly what that command means, what tools to use, and how to respond.

Here’s the simplest possible skill — a made-up one called /hi:

# hi

Greet the user warmly and ask what they'd like to work on today.

Save that as hi.md in the right place, and typing /hi in Claude Code will trigger it. That’s it. That’s the core of skills.

The more interesting question is: what’s “the right place” — and what happens when you have multiple files fighting over the same command?

Project skills vs personal skills

This is where it gets useful.

Project skills live inside your repo, usually at .claude/skills/. They’re committed to git, shared with your team, and scoped to that project. You’d put things here like:

/deploy — because your deploy process is specific to this project
/migrate — because your migration pattern is specific to this database
/test-e2e — because your E2E setup is weird and worth documenting

my-project/
  .claude/
    skills/
      deploy.md       ← /deploy
      migrate.md      ← /migrate
      test-e2e.md     ← /test-e2e

Personal skills live in ~/.claude/skills/. They follow you everywhere, across every project. Good candidates:

/code-review — your personal review style
/standup — how you like your standup summaries formatted
/explain — your preferred way to get explanations

~/.claude/
  skills/
    code-review.md    ← /code-review (everywhere)
    standup.md        ← /standup (everywhere)

The mental model: project skills are institutional knowledge, personal skills are your workflow preferences.

The skill file format

Skill files are markdown, but Claude reads them in a specific way. Let me show you what a real-ish skill looks like:

# deploy

Deploy the current branch to staging.

## When to use
When the user types `/deploy` or asks to "push to staging."

## Steps
1. Run `git status` to check for uncommitted changes
2. Run the project's build command (`npm run build` or `pnpm build`)
3. Run `./scripts/deploy-staging.sh` and stream the output
4. Report success or failure with a link to the deployment URL

## Notes
- Never deploy to production from this skill. If the user asks, explain the process requires a manual PR merge.
- The staging URL is always https://staging.myapp.com

Claude reads the whole file as context before responding. So you’re not writing code — you’re writing instructions for a colleague.

The format is flexible. You can use headers, bullet points, code blocks, whatever makes the instructions clear. Claude is good at following structured prose.

How skill matching actually works

When you type /something, Claude Code does the following:

Looks for something.md (or something.mdx) in your project’s skill directory
Falls back to your personal ~/.claude/skills/ directory
Falls back to built-in skills that ship with Claude Code

That’s the lookup chain. Project > Personal > Built-in.

But here’s the thing most people miss: it’s not just exact name matching.

Claude Code also uses a fuzzy trigger system. Some skills have a TRIGGER section in their description that tells the system when to auto-load the skill, even without an explicit slash command. Look at the claude-api skill for example — it auto-loads whenever you’re working with anything Anthropic-related.

You can use this too. If your skill’s description says “use when the user is working with Postgres migrations,” Claude will load it when that context is detected. You don’t always need an explicit /command.

Skill priority — who wins?

When you have skills in multiple places with the same name, project wins over personal.

~/.claude/skills/deploy.md          ← your general deploy skill
my-project/.claude/skills/deploy.md ← this project's deploy skill  ← WINS

This is intentional and useful. You can have a general /deploy that works for most of your projects, and then override it for the one project with a weird deploy pipeline.

The priority ladder, from lowest to highest:

Source	Location	Wins against
Built-in	Ships with Claude Code	Nothing
Personal	`~/.claude/skills/`	Built-in
Project	`.claude/skills/`	Personal + Built-in

So if you want to completely replace a built-in skill like /code-review for a specific project, just create .claude/skills/code-review.md in that project. Done.

Multiple file skills and progressive disclosure

Here’s a feature that took me a while to discover: a skill can be a directory, not just a file.

.claude/skills/
  review/
    index.md       ← the main skill definition
    checklist.md   ← security checklist it references
    examples.md    ← example outputs Claude should match

The index.md is the entry point. Inside it, you can reference the other files:

# review

Review the current diff for bugs, security issues, and code quality.

## Checklist
Follow the checklist in `checklist.md`.

## Output format
Match the examples in `examples.md`. Always use this exact structure.

This is progressive disclosure — you keep the main skill simple and readable, but let Claude load more detail when it needs it. Complex skills that would be a wall of text in a single file become navigable when split across files.

The practical limit: don’t go more than 2 levels deep. Skill directories are powerful but they’re not a full knowledge base.

Agents — the next level

Skills run Claude inline. Agents are different: they’re subprocesses that can work in parallel, in isolation, with their own tools and context.

You trigger an agent from inside a skill:

# audit

Audit the entire codebase for security vulnerabilities.

Use the Agent tool to spawn three independent agents:
- One scans for SQL injection patterns
- One checks for exposed secrets and API keys  
- One reviews authentication flows

Synthesize all findings into a single prioritized report.

Claude will literally spin up three subagents, run them concurrently, and stitch the results together.

This unlocks a pattern that’s hard to replicate any other way: fan-out + synthesize. You spread work across multiple focused agents, then bring it back together. Each agent stays in its lane, doesn’t get distracted by the other work, and you get better coverage than a single broad pass.

Agent skills are slower (more API calls) but dramatically more thorough. I use them for things like:

Comprehensive security reviews before a release
Analyzing a big refactor across multiple subsystems
Research tasks where I want multiple angles checked independently

Tips that actually matter

A few things I’ve learned the hard way:

Write skills like you’re briefing a smart colleague, not programming a computer. “Review this code for bugs” is worse than “Review this code. Focus on: null dereferences, missing error handling, and any place we return user input directly to the client. Be concise — one sentence per finding unless it’s critical.”

Keep skills focused on the what, not the how. Claude already knows how to run shell commands, read files, and call tools. Your skill should say “deploy to staging” not “run these 7 commands in this exact order.” Unless the exact order genuinely matters.

Use the TRIGGER pattern for skills you always want active. If you have a skill that should load any time you’re working on a Rails app, put that condition in the skill’s description. You shouldn’t need to type /rails-conventions every time.

Test your skills by just typing the command. There’s no compile step, no syntax to validate. You change the .md file, type the slash command, done. Iteration is instant.

Don’t over-specify. A skill that’s 400 lines of detailed instructions often performs worse than a 40-line skill with clear intent. Claude fills in reasonable gaps. Trust it.

The mental shift

Here’s what clicked for me after a few months: skills are not a way to automate Claude. They’re a way to align it.

Every team has implicit knowledge — deploy processes, review standards, test patterns, architectural preferences. That knowledge usually lives in someone’s head, or buried in a Notion doc nobody reads.

Skills let you make that knowledge explicit and executable. Your junior devs get a /code-review that matches what your seniors actually care about. Your /deploy doesn’t forget the step everyone always forgets. Your /explain always uses the analogies your team finds useful.

That’s the real win. Not automation. Alignment.

Part 2 is about getting 100% out of this system — building your own agents, composing skills together, and the patterns that separate “skills user” from “skills power user.”