Skills and Custom Commands

Two names, one idea

Custom Commands and Agent Skills solve the same problem: reusable, shareable instructions you don’t want to retype every time. Current official docs lean toward Skills as the recommended mechanism, but Commands still work exactly as documented below — nothing has been deprecated. Use whichever fits your team’s existing habits; this page covers both.

Agent Skills

Think of what Claude knows and sees as a stack. At the bottom is its built-in training knowledge. On top of that is whatever context it’s been given for this task — files it’s read, MCP results, web search. A skill is an additional layer on top of both: extra instructions and examples for one specific kind of situation (“React best practices,” “Clean code,” “how we write commit messages here”), each one contributing guidance only when it’s actually relevant.

Skills activate lazily. Claude doesn’t load every installed skill’s full content into every prompt — it loads a skill’s content only when it decides the current task calls for it. That means a project can have a whole library of skills installed without bloating every single conversation with content most tasks don’t need.

Anatomy of a skill folder:

.claude/skills/my-skill/
  SKILL.md          # YAML front-matter (name + description drive discovery) + instructions
  references/       # optional supporting docs
  scripts/           # optional helper scripts
  assets/             # optional supporting files

Not triggering? Sharpen the description

If a skill isn’t activating when you expect it to, the fix is almost always the description field in its front-matter — that’s the only signal Claude uses to judge relevance. Adding an explicit cue helps a lot, e.g. “Gets triggered when writing ANY kind of CSS code” is far more effective than a vague summary of what the skill contains.

Skill front-matter fields

Field	Effect
disable-model-invocation: true	Command-only — never auto-invoked, must be called explicitly
user-invocable: false	Auto-discovery only — can’t be called manually
allowed-tools: Read	Restrict which tools this skill can use
$ARGUMENTS	Placeholder for whatever text follows the command when invoked manually

Third-party skills are installable from skills.sh, a public community repo, via npx skills add <owner/repo> (needs Node.js).

Custom Commands

Commands are the older mechanism, and they’re still fully supported. A custom command is a reusable prompt template you save once as a markdown file, then invoke with /your-command-name.

Command locations and scope

Location	Scope	Invoked as
.claude/commands/	Project (shared, commit to repo)	/code-review
~/.claude/commands/	Personal (all your projects)	/code-review
.claude/commands/frontend/	Sub-folder = namespace	/frontend:component

A command file has optional YAML front-matter (description, allowed-tools, argument-hint, model, disable-model-invocation) followed by the markdown prompt body itself.

Argument placeholders

Placeholder	Meaning
$ARGUMENTS	Everything typed after the command, as one string
$1, $2, …	Individual positional arguments
@path/to/file	Inject that file’s contents
!<shell command>	Run a shell command and include its output (needs tool permission)

A worked example

Here’s a command that branches its behavior based on an argument — a genuinely useful pattern for review-style commands:

---
allowed-tools: Read(*)
description: Perform a code-review
---
MODE: $ARGUMENTS

If Mode is one of the following, adjust the review as described:
- MODE == BUGS: Focus ONLY on logical or other bugs.
- MODE == SECURITY: Focus ONLY on security issues.
- MODE == PERFORMANCE: Focus ONLY on performance issues.

MODE can also be set to a combination like "BUGS,SECURITY" etc
=> Perform the combined review in that case.

If MODE is set to anything else or nothing at all, perform a
thorough, general code review.

Perform an in-depth code review of the entire codebase.
Carefully and thoroughly explore the codebase file-by-file to find
potential issues and improvements.
Don't rush it, instead make sure you fully understand the code
structure and architecture.
Create a detailed report of all your findings.

Saved at .claude/commands/code-review.md. Same file works whether you’re thinking of it as a “command” or, ported into SKILL.md form, as a “skill” — the mechanics above apply either way.

Invoking /code-review

Invocation	Effect
/code-review	Thorough general review
/code-review BUGS	Bugs only
/code-review SECURITY	Security only
/code-review BUGS,SECURITY	Combined review

Why allowed-tools: Read(*) matters here

Restricting this command to Read(*) keeps the reviewer strictly read-only. It reports findings instead of quietly “fixing” issues by editing files while it’s supposed to just be reviewing them — which is exactly what you want from a review command.

Good practices

Avoid

• Cramming unrelated tasks into one command
• Vague instructions that need a follow-up question every time
• Granting write/edit tools when read-only would do

Do

• Keep each command/skill focused on one job
• Spell out the expected output format
• Use argument-hint so teammates know what to pass
• Scope tools with allowed-tools

For a Flutter-flavored code-review command/skill idea, see Claude Code for Flutter Teams. And if what you actually need is a dedicated tool restriction plus its own persona rather than a one-off prompt template, see Subagents.

Check yourselfIf commands and skills do almost the same thing, when would you reach for a subagent instead of either?

Commands and skills are both ways of packaging a reusable prompt — they run inside your current session, using whatever tools that session already has. A subagent is a step further: its own restricted tool access and its own persona, invoked for a specific kind of task, often so it can run with a narrower or safer permission set than your main session (like a read-only reviewer) or be triggered proactively based on its description. Reach for a subagent when you need that isolation or proactive discovery — reach for a command/skill when you just want to save yourself retyping a prompt.