Add Claude Code Skills as Slash Commands

If you find yourself pasting the same instructions into Claude Code—review this route, write a migration, prepare a release note—it is time to make a skill.

A skill is a small, focused instruction package. In Claude Code, it can be loaded automatically when it is relevant, or invoked directly as a slash command. A file at .claude/skills/review-route/SKILL.md becomes /review-route.

That makes skills a good home for repeatable work: they live with the repository, can be code-reviewed, and give every contributor the same starting point.

Skills are the current custom-command format

Claude Code has historically supported custom commands as Markdown files in .claude/commands/. That format still works, but custom commands have been merged into skills.

Use skills for new work:

your-project/
└── .claude/
    └── skills/
        └── review-route/
            └── SKILL.md

The directory name determines the command name, so the example above creates /review-route. The name field in the file's frontmatter changes the label Claude shows, not the command you type.

Skills can also include templates, examples, scripts, and reference files beside SKILL.md. That is the main advantage over the old one-file command format.

Create a project-local review command

Start with a skill that reviews a route or handler. Create the directory:

mkdir -p .claude/skills/review-route

Then add .claude/skills/review-route/SKILL.md:

---
description: Review an API route or request handler for correctness, security, and maintainability.
argument-hint: <file-or-directory>
disable-model-invocation: true
allowed-tools: Read Grep Glob
---

Review `$ARGUMENTS`.

1. Read the target and the code it calls.
2. Identify input-validation, authorization, error-handling, and data-exposure issues.
3. Check that status codes and response shapes follow nearby conventions.
4. Report findings first, ordered by severity. Include file paths and line numbers.
5. If there are no findings, say so and call out any remaining test gaps.

Do not edit files unless the user explicitly asks for a fix.

Now start Claude Code in the repository and run:

/review-route app/api/users/route.ts

Claude replaces $ARGUMENTS with everything after the command. In this case, it receives the path to review along with the instructions in the skill.

The frontmatter has two important jobs here:

• disable-model-invocation: true means only a person can start this workflow. That is a sensible default for deliberate actions such as review, release, deployment, or commit preparation.
• allowed-tools pre-approves the named tools for the turn that runs the skill. Keep this list narrow. It saves approval prompts without turning the command into a broad permission grant.

The command is immediately useful, but it also has a clear boundary: it reviews; it does not quietly change code.

Choose where a skill lives

The location sets the scope. Pick the smallest scope that makes the workflow useful.

For team workflows, commit project skills to the repository. A new teammate then gets the command with the codebase instead of discovering it from an onboarding document.

Claude Code also finds skills in nested directories. In a monorepo, apps/web/.claude/skills/deploy/SKILL.md can provide a deployment procedure specific to the web app without making it the default for every package.

Give commands useful inputs

$ARGUMENTS is the simplest way to accept input, but skills can name positional arguments when the structure matters.

Here is a command for drafting a release note from a range of commits:

.claude/skills/release-note/
└── SKILL.md

---
description: Draft a customer-facing release note from a Git revision range.
argument-hint: <from-ref> <to-ref>
arguments: [from_ref, to_ref]
disable-model-invocation: true
allowed-tools: Bash(git log:*) Bash(git show:*) Read
---

Create a release note from `$from_ref` through `$to_ref`.

1. Inspect the commits and changed files in that range.
2. Group user-visible changes into short sections.
3. Omit internal refactors unless they affect behavior, reliability, or performance.
4. Write plainly and do not claim an outcome the changes do not support.
5. Finish with a brief list of items that need product or engineering confirmation.

Run it with:

/release-note v2.3.0 HEAD

With arguments, $from_ref receives the first argument and $to_ref the second. You can also use $0, $1, and $ARGUMENTS[0] for positional values. Quote an argument with spaces just as you would in a shell:

/release-note "release/July fixes" HEAD

The argument-hint is not just decoration: it makes the slash-command picker clearer before someone runs the command.

Keep the prompt small and the procedure concrete

A skill is a prompt that stays available during its turn. Write it like an operating procedure, not a policy handbook.

Good skills tell Claude:

• when to use the command and what output it should produce;
• which files or facts it must inspect before making a claim;
• the order of work and any non-negotiable checks; and
• when it must stop and ask for confirmation.

Avoid repeating repository facts that already belong in CLAUDE.md. CLAUDE.md is for durable context such as the package manager, architecture, and coding conventions. A skill is for a task with a beginning and an end.

Keep longer material next to the skill instead of pasting it into SKILL.md:

.claude/skills/onboard-api/
├── SKILL.md
├── examples.md
├── api-conventions.md
└── scripts/
    └── verify-contracts.sh

Point to those files from SKILL.md and say when to read or run them. Claude can load the relevant reference only when it needs it, keeping the command's initial context focused.

Decide who may invoke the skill

By default, both you and Claude can invoke a skill. The description is what lets Claude recognize when it might help.

That is useful for background knowledge. For example, an api-conventions skill can describe how the project structures errors and pagination, and Claude can apply it automatically while it works.

For a command with side effects or a workflow that needs deliberate timing, add this:

disable-model-invocation: true

Claude can no longer start that skill on its own, but it remains available from the / menu. Use this for commands such as /deploy, /commit, /publish, or anything that can call an external service.

The inverse is also useful for pure reference material:

user-invocable: false

That hides the skill from the slash-command menu while allowing Claude to load it when relevant.

Test it in a real task

You do not need to restart Claude Code every time you edit an existing watched skills directory. Make a small change, invoke the command, and inspect what it actually does.

Test a skill with inputs that expose weak instructions:

• a path that does not exist;
• an ambiguous request;
• a repository with no changes; and
• an input containing spaces or punctuation.

If the result is too vague, add an explicit output format. If it reads too much code, state where to begin and what evidence is sufficient. If it takes an action you did not intend, remove the permission, add a confirmation step, or make it user-invocable only.

The strongest skills are modest. They encode one repeatable way of working, leave room for judgment, and make the safe choice easy.

Migrate an older command when it is worth it

An existing command like this continues to work:

.claude/commands/review-route.md

If it is only a short prompt, you can leave it alone. Move it to a skill directory when it needs supporting material, better discovery through a description, or invocation controls.

The migration is mostly a file move:

.claude/commands/review-route.md
        ↓
.claude/skills/review-route/SKILL.md

The command remains /review-route. Do not keep both with the same name: the skill takes precedence, which makes the old file confusing dead weight.

Further reading

• Claude Code skills documentation
• Agent Skills open standard