Claude Code Skills: The 2026 Guide to Writing and Using Them

The best Claude Code tip in circulation reduces to one sentence: if you do something more than once a day, turn it into a skill. Skills are Claude Code's most underrated feature. They replace the reflex of pasting the same multi-step procedure into chat, they keep your `CLAUDE.md` lean, and once you understand how they work, they become the primary way you extend what Claude can do.

Quer experimentar esta ferramenta? Try Claude Code

Despite this, most developers using Claude Code in 2026 have never written a skill. Part of the reason is that the existing documentation focuses on the frontmatter syntax instead of the mental model. The question everyone actually has — *when should something be a skill versus a line in `CLAUDE.md`?* — is left implicit. The killer features (`/batch`, `context: fork`, shell command injection) rarely surface in guides aimed at beginners.

This article fills that gap. You will leave with a clear rule for when to reach for a skill, a tour of the seven bundled skills that ship with Claude Code (including `/batch`, which is the single biggest productivity multiplier of 2026), and a custom skill you can drop into `~/.claude/skills/` today. By mid-2026, the community skill ecosystem has matured significantly — we cover the best places to find and share skills. If you already know the basics, skim to the bundled skills section — that is where the surprises are.

What is a Claude Code skill, exactly?

A skill is a directory with a `SKILL.md` file inside. The file has YAML frontmatter (metadata) and markdown content (the actual instructions). When the skill is invoked — either by you typing `/skill-name` or by Claude deciding to load it based on the `description` field — the markdown content enters your conversation as a single message and stays there for the rest of the session.

That one-sentence definition hides the most important distinction: a skill loads only when invoked. Content in `CLAUDE.md` is loaded at the start of every session, consuming context tokens permanently. A skill's body consumes zero tokens until you use it. This is what makes skills cheap — you can write long reference material, detailed playbooks, or multi-step procedures without paying for them unless you need them.

Skills follow the open Agent Skills standard. As of 2026, the same SKILL.md file runs without modification in Claude Code, Cursor, Windsurf, Gemini CLI, and Codex CLI. Claude Code extends the standard with additional features: controlled invocation, subagent execution, and dynamic context injection. We cover all three below.

Anatomy of a SKILL.md file

Here is the minimal skill, straight from the official docs. It teaches Claude to explain code with analogies and ASCII diagrams:

how does this work?

Save this as `~/.claude/skills/explain-code/SKILL.md`. You can now invoke it two ways. Type `/explain-code src/auth/login.ts` and Claude runs the skill explicitly. Or ask a question like "how does this code work?" — Claude reads the `description` field, sees it matches, and loads the skill automatically. Either path produces the same behavior. One naming note: Claude Code also watches `.claude/commands/` (the older convention). Files placed there use the same format and produce the same slash commands — the two locations are functionally identical since the 2025 merge. Prefer `.claude/skills/` for new work; `.claude/commands/` remains for backwards compatibility.

The frontmatter is where skills get interesting. Only `description` is truly recommended — everything else is optional. But the optional fields are where the power lives.

Dynamic arguments with $ARGUMENTS and named params

Skills accept arguments passed on invocation. The simplest pattern: put `$ARGUMENTS` in your skill content and it gets replaced with whatever the user typed after the skill name. `/fix-issue 123` makes `$ARGUMENTS` expand to `123`.

For positional arguments, use `$ARGUMENTS[N]` or the shorthand `$N`. For named arguments, declare them in the frontmatter `arguments:` list. Running `/migrate-component SearchBar React Vue` on the skill below expands `$0` to `SearchBar`, `$1` to `React`, `$2` to `Vue`:

Two built-in substitutions are especially useful. `${CLAUDE_SESSION_ID}` gives you the current session ID — perfect for logs that need to correlate with sessions. `${CLAUDE_SKILL_DIR}` returns the directory containing the SKILL.md, which you use to reference scripts bundled with your skill regardless of the current working directory.

The seven bundled skills everyone should know

Claude Code ships with a growing set of bundled skills. They are marked Skill in the commands reference. Unlike hardcoded commands like `/clear` or `/compact`, bundled skills use the same prompt-based mechanism as skills you write yourself — which means you can read their prompts, learn from them, and imitate the patterns.

/batch — the killer feature

`/batch` is the feature that most justifies Claude Code's existence. Give it a large-scale change and it orchestrates the work in parallel: it researches the codebase, decomposes the job into 5 to 30 independent units, presents a plan for your approval, then spawns one background agent per unit in an isolated git worktree. Each agent implements its unit, runs tests, and opens a pull request. You review the PRs, merge the good ones, reject or retry the broken ones.

Requirements: a git repository (otherwise there is nothing to worktree). The cost: significant — you are running dozens of parallel Claude Code sessions. Budget accordingly. On Pro, a single `/batch` run can consume a meaningful chunk of your monthly quota. If you plan to use `/batch` more than once a week, Max ($100/month) pays for itself.

Why this is the killer feature: the bottleneck in any large migration has always been human attention, not keyboard speed. `/batch` parallelizes the attention. You review a dozen PRs instead of writing a dozen migrations. For most engineering teams, this is the difference between 'we will do this next quarter' and 'we did this today.'

/simplify — parallel review and fix

`/simplify` spawns three review agents in parallel on your recently changed files, aggregates their findings, and applies fixes. You can focus the review with an argument: `/simplify focus on memory efficiency` or `/simplify focus on error handling`. Run it before opening a PR — it catches the things a self-review misses because you wrote the code.

/debug — structured troubleshooting

Debug logging in Claude Code is off by default unless you start with `claude --debug`. `/debug` enables it mid-session and walks through the session debug log to analyze an issue. Optionally pass a description: `/debug the deploy hook is firing twice`. It reads the log, identifies the anomaly, and proposes a fix.

/loop — self-paced repetition

`/loop [interval] [prompt]` runs a prompt repeatedly while the session stays open. With no interval, Claude self-paces between iterations. With no prompt, Claude runs an autonomous maintenance check (or the prompt in `.claude/loop.md` if present). Canonical use: `/loop 5m check if the deploy finished`. This is how you poll without leaving the session and without burning a subagent.

/goal — autonomous long-running tasks

`/goal [condition]` registers a session-level completion condition and then hands control back to Claude. Claude keeps working, turn after turn, until the condition holds. The active goal appears in the status line; a live overlay panel shows elapsed time, turn count, and token usage. Clear it with `/goal clear`. Example: `/goal all CI checks green and PR approved` — Claude runs, diagnoses failures, fixes them, and iterates until it reaches the condition or surfaces a blocker it cannot resolve alone.

This is qualitatively different from `/loop`. `/loop` repeats a fixed prompt on an interval; `/goal` drives toward a destination, adapting its approach each turn based on what it observes. Think of it as the difference between a cron job and an autonomous agent: `/loop` is the cron job, `/goal` is the agent. Use `/goal` when the path to the end state is uncertain and Claude needs to reason its way there. Use `/loop` when you already know the action and just need it repeated on schedule.

/claude-api — auto-active on anthropic imports

`/claude-api` loads Claude API reference material for your project's language (Python, TypeScript, Java, Go, Ruby, C#, PHP, or cURL), plus the Managed Agents reference. It covers tool use, streaming, batches, structured outputs, and common pitfalls. The notable part: it activates automatically when Claude detects your code imports `anthropic` or `@anthropic-ai/sdk`. You do not have to remember to invoke it.

/fewer-permission-prompts — auto-build your allowlist

Permission prompts are the tax you pay for Claude Code's safety model. `/fewer-permission-prompts` scans your transcripts for common read-only Bash and MCP tool calls you have approved, then adds a prioritized allowlist to your project's `.claude/settings.json`. After running it once, your daily sessions involve noticeably fewer approval dialogs. This is also a good template for understanding how skills can introspect session state.

Dynamic context injection with !command

Here is the feature that separates beginners from power users. You can run shell commands before the skill content is sent to Claude. The output replaces a placeholder. Claude receives the actual data, not the command.

The pattern uses a backtick-prefixed syntax in your SKILL.md. A skill that summarizes a pull request might look like this:

When you invoke `/pr-summary`, three `gh` commands run immediately. Their output gets inlined into the skill content. Claude receives a fully-rendered prompt with the actual diff, the actual comments, and the actual file list — no tool calls needed to go fetch them. This makes the skill fast and deterministic.

For multi-line commands, use a fenced code block opened with the backtick-bang-backtick pattern. The commands run sequentially and their combined output replaces the block. Organizations can disable shell injection via `"disableSkillShellExecution": true` in managed settings — useful for security-sensitive deployments.

context: fork — turn a skill into a subagent

Set `context: fork` in the frontmatter and your skill stops running in your main conversation. It spawns a fresh subagent with an isolated context window, gets the skill body as its prompt, and returns a summary to your main session. The `agent` field picks which subagent configuration drives it — `Explore` for read-only research, `Plan` for plan mode, `general-purpose` for everything else, or any custom subagent from `.claude/agents/`.

Why this matters: your main conversation's context window stays clean. The skill does the grepping, reading, and analyzing in its own session. You only see the summary. For research-heavy tasks, `context: fork` dramatically reduces the noise in your main conversation.

Where skills live — the four scopes

Skills live in one of four locations, each with a different scope. Higher-priority locations win when skills share the same name.

Claude Code watches these directories for changes. Adding, editing, or removing a skill takes effect within the current session without restart. The one exception: creating a top-level `skills/` directory that did not exist at session start requires a restart so the directory can be watched. A historical alias: `.claude/commands/*.md` (without a subdirectory) is also discovered and behaves identically to `.claude/skills/`. If you are migrating an older setup, you can leave files in place — or move them to `.claude/skills//SKILL.md` for clarity.

Best public skills to install today

The Claude Code skill ecosystem matured quickly. The canonical starting point is hesreallyhim/awesome-claude-code — a curated list of skills, hooks, slash commands, agent orchestrators, and plugins maintained by the community. Anthropic also ships a growing set of official skills at anthropics/claude-code-skills, covering common workflows out of the box. Clone a few, read their SKILL.md files, adapt them to your workflow.

A second valuable resource is FlorianBruniaux/claude-code-ultimate-guide, which ships production-ready templates along with a cheatsheet and quizzes. For an opinionated daily-driver setup, shanraisshan/claude-code-best-practice is worth a read. Once you have the basics, the claudeskills.info directory indexes community skills by category — useful for discovering domain-specific skills (security review, database migrations, i18n, etc.).

A custom skill you can install in 60 seconds

To make this article practical, here is a skill we actually use. It enforces a 'verify before shipping' pattern — giving Claude a checklist to run through before declaring a task done. Drop it into `~/.claude/skills/verify-done/SKILL.md`:

Invoke it with `/verify-done` at the end of any task. Claude runs the full checklist, surfaces failures, and either clears you to ship or tells you what needs fixing. This is the simplest possible implementation of the single most impactful tip in Claude Code usage: *give Claude a way to verify its own output*.

The anti-patterns to avoid

Skills fail in predictable ways. These are the five mistakes we see most often.

FAQ

What is the difference between CLAUDE.md and a skill? CLAUDE.md loads at the start of every session and costs tokens permanently. Skills load only when invoked and cost zero tokens until used. Rule: facts and conventions go in CLAUDE.md, procedures and playbooks go in skills.

Can I share a skill with my team? Yes. Put it in `.claude/skills//SKILL.md`, commit to git, and every teammate gets it in their next session. For personal skills only you want, use `~/.claude/skills/`.

Do skills consume context after invocation? Yes. The rendered content enters the conversation and stays. Post-compaction, Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each with a combined budget of 25,000 tokens. Older skills can be dropped if you invoke many.

Can I use a skill for deployment or other destructive actions? Yes, but always set `disable-model-invocation: true` so only you can trigger it. You do not want Claude deciding the conversation looks ready to ship.

Skills versus subagents versus /goal — which should I use? Three different primitives. A skill is a prompt injected into your current conversation. A subagent (via `context: fork`) runs in a separate context window with its own tools. `/goal` is an autonomous loop that keeps the main session running until a completion condition holds — no subagent overhead, but Claude drives itself rather than waiting for you. Use skills for repeatable tasks, subagents for parallelism, `/goal` for autonomous long-running work within a single session.

Where do I go from here? If you have not already, read our Claude Code hub guide for orientation across the whole product. If you want to master the `CLAUDE.md` side, see the anatomy of a great CLAUDE.md file. To evaluate whether Claude Code fits your workflow, our Claude Code review has the benchmarks and honest pros and cons.