Claude Code Skills: Teaching Your AI Agent New Tricks

The most expensive thing about using an AI coding assistant is explaining the same context over and over.

Your codebase has conventions. Your CI pipeline has quirks. Your deployment process has steps that aren't obvious from the code. Every session, you explain a piece of this. Every session, the agent starts without it. Because the agent starts fresh each session, whatever you explained last time is gone.

Claude Code's skills system is the fix for this. Write down what the agent should know, once, and it applies automatically from then on.

A Skill Is a File, Not a Feature

A skill is a directory with one required file: SKILL.md. The file has two sections. The YAML frontmatter tells Claude what the skill is called, when to use it, and who can invoke it. The markdown body contains the actual instructions.

Minimal example:

---
name: fix-issue
description: Fix a GitHub issue. Use when asked to fix a bug or implement a feature from an issue tracker.
---

Fix GitHub issue $ARGUMENTS following our coding standards.

1. Read the issue description carefully before touching any code
2. Find the relevant files. Check the tests first to understand expected behavior
3. Implement the fix in the smallest diff that solves the problem
4. Write a test that would have caught this bug
5. Commit with a message following conventional commit format

Save that at ~/.claude/skills/fix-issue/SKILL.md. Done. Now when you say "fix issue 247," Claude considers this skill. You can also call it directly with /fix-issue 247.

The instruction set becomes part of every relevant conversation, without you having to paste it again.

You Control When and How Skills Activate

The default is that Claude decides. If your skill's description says "use when asked to deploy," Claude will invoke the skill when a deployment conversation starts. This works well for background knowledge: your API conventions, your test writing standards, where you want the guidance applied automatically.

But some skills should only run when you decide: deployments, commits, operations with real side effects. For those, set disable-model-invocation: true in the frontmatter. Now the skill is invisible to Claude's automatic detection and only activates when you type /skill-name explicitly.

The third case: user-invocable: false makes a skill available for Claude to invoke automatically but removes it from the slash command menu. Use this for context that should always inform Claude's behavior (like a style guide) but that you'd never explicitly call.

These three modes cover most real-world cases. When writing a skill, the decision is: automatic, on-demand only, or always-on in the background?

Skills Enable Multi-Agent Workflows

Skills can include context: fork in their frontmatter. When set, the skill doesn't run in your current session; it launches a separate subagent with the skill content as its task. Your conversation continues uninterrupted while the subagent handles the work in parallel.

Claude Code ships three built-in skills that show how this works:

/simplify reviews your recent changes and cleans them up. It spawns three review agents in parallel: one checking for code reuse, one checking quality, one checking performance. Each runs independently and returns findings; Claude synthesizes them and applies the changes.

/batch takes a large task description and breaks it into independent units. Each unit gets its own agent running in a separate git worktree, everything happens in parallel, and each unit produces a separate PR. What would be one giant sequential change becomes multiple parallel changes reviewed independently.

/loop runs a prompt on a schedule while your session is open. Useful for monitoring: check a deployment every five minutes, watch for a test to turn green, poll an API for a status change.

These aren't hardcoded into Claude Code; they're skills, written exactly the way you'd write your own. You can look at the source, fork them, modify them, and build similar patterns.

Dynamic Context Injection

Skills can pull in live data before Claude sees the instructions.

Using the !command syntax inside a skill file, shell commands run before the content is passed to Claude. The output is substituted into the prompt. Claude receives real current data rather than instructions to go fetch something.

A PR review skill can inject the actual diff, so the instructions and the code being reviewed arrive together. A deployment skill can inject the current environment state. A debugging skill can inject recent log lines. The agent starts with real information instead of having to acquire it as a first step.

Where Skills Live and Who Has Access

Personal skills at ~/.claude/skills/ apply everywhere. Project skills at .claude/skills/ inside a repo apply only to that project. Enterprise deployments can push skills to all users through managed configuration.

Higher-priority levels override lower ones when names conflict. Project skills beat personal skills. Enterprise skills beat both.

In monorepos, Claude Code discovers skills walking up the directory tree. If you're editing a file in packages/api/src/, it looks for skills in packages/api/.claude/skills/, packages/.claude/skills/, and the root .claude/skills/. You can scope skills to sub-packages without a global configuration change.

Skills Are Knowledge Assets

When you write a skill encoding how to handle deployments in your project, you're capturing knowledge that otherwise lives in someone's head or in an onboarding doc nobody reads.

New team members clone the repo and get that knowledge applied automatically. The agent working in the codebase makes the same decisions a senior developer would, without needing to be told. The skill library grows as the project does, and it's version-controlled alongside the code.

Most developers treat AI assistants as tools they're always explaining things to. Skills change that relationship. You explain once, well, and the agent works from it reliably going forward; knowledge compounds instead of evaporating.