Slash Commands & Skills — Package Your Repeat Workflows

You're Already Repeating Yourself

By now you've probably noticed something: you type the same kinds of requests over and over. "Review this change for bugs." "Write a commit message." "Turn these notes into a blog post in my voice." Every time, you re-type the full instructions from memory — and sometimes you forget a step.

Claude Code lets you package these repeated requests so you can fire them off with a couple of words. There are two tools for this: slash commands (quick prompt shortcuts) and skills (smarter, reusable capabilities Claude reaches for on its own). This lesson covers both, and when to use which.

---

Custom Slash Commands: Saved Prompts You Trigger by Name

A slash command is a saved prompt you invoke by typing / plus a name. You've already used built-in ones like /init. The powerful part: you can write your own.

A custom command is just a Markdown file. The filename becomes the command name. Put it in one of two places:

Your first command

Say you constantly ask Claude to review your work. Create a file at .claude/commands/review.md:

Review the changes I just made. Look for:
- Bugs or logic errors
- Anything that could break existing features
- Security issues (exposed keys, missing validation)

Give me a short, prioritized list. Be direct — don't pad with praise.

Now, in any session for that project, you just type:

/review

…and Claude runs that full prompt. No re-typing. The file is the prompt — whatever you write in the Markdown body is what Claude receives.

---

Passing Arguments to Commands

Static prompts are useful, but the real power comes from commands that take input. You do this with $ARGUMENTS, a placeholder that gets replaced with whatever you type after the command name.

Create .claude/commands/explain.md:

Explain this in plain language for a non-technical person: $ARGUMENTS

Keep it under 100 words. Use an analogy if it helps.

Now you can call it with input:

/explain what is a database migration

Claude receives the full prompt with $ARGUMENTS swapped for "what is a database migration." One command, infinite uses.

You can also grab individual words by position with $1, $2, and so on:

Draft a polite email to $1 about $2. Keep it to three sentences.

/email the-client the delayed invoice

Here $1 becomes "the-client" and $2 becomes "the delayed invoice."

Adding a little polish (frontmatter)

You can put an optional frontmatter block at the top — a small section between --- lines — to describe the command. The most useful field is description:

---
description: Review my recent changes for bugs and security issues
argument-hint: (none)
---

Review the changes I just made...

The description shows up when you browse your commands, so future-you remembers what it does. argument-hint reminds you what to type after the command. Both are optional — a command works fine with just a body.

---

Skills: Capabilities Claude Reaches For On Its Own

Slash commands are great, but they have a limit: you have to remember to type them. A skill is the next step up. It's a packaged capability that Claude pulls in automatically when your request matches what the skill is for — no slash needed.

A skill lives in its own folder with a special file called SKILL.md:

.claude/skills/blog-post/SKILL.md

(Or in ~/.claude/skills/ to make it available everywhere.)

The SKILL.md file has frontmatter with a name and a description, then instructions in the body:

---
name: blog-post
description: Turn rough notes or a transcript into a finished blog post in David's voice. Use whenever the user wants to draft or write a blog post or article.
---

# Writing a blog post

When asked to write a blog post:

1. Read the user's notes and identify the single core idea.
2. Open with a concrete hook, not a definition.
3. Use short paragraphs and plain language. No corporate jargon.
4. End with one clear takeaway.

Voice: warm, direct, a little opinionated. Write like you're explaining
to a smart friend over coffee.

Here's the clever part, called progressive disclosure: Claude only loads the full instructions when they're relevant. Most of the time it just knows the skill's name and description sitting quietly in the background. The moment you say "help me write a blog post," Claude recognizes the match, pulls in the full SKILL.md, and follows it. You never had to type /blog-post — though you still can if you want.

That description is doing the heavy lifting. It's how Claude decides whether the skill applies, so write it clearly: say what the skill does and when to use it.

---

Skills Can Bundle More Than Instructions

A skill is a folder, so it can carry extra files alongside SKILL.md — reference documents, templates, even small scripts:

.claude/skills/blog-post/
  SKILL.md          ← instructions + frontmatter
  examples.md       ← three sample posts to match the style
  checklist.md      ← a pre-publish checklist

Claude reads these supporting files only when it needs them. This keeps the main instructions short while still giving Claude deep reference material to draw on. (We'll build one of these end-to-end in the next lesson.)

---

Command or Skill? How to Choose

They overlap, so here's the simple way to decide:

A good rule of thumb: start with a slash command. It's the lightest tool. If you find that command growing — more steps, more edge cases, supporting files, and you wish Claude would just know when to use it — graduate it into a skill.

---

Summary

• Custom slash commands are saved prompts in .claude/commands/*.md (project) or ~/.claude/commands/ (global), triggered by typing /name.
• Make them dynamic with $ARGUMENTS (everything you type after the command) or $1, $2 for individual words. Optional frontmatter description documents what each does.
• Skills are packaged capabilities — a SKILL.md with a name and description plus optional bundled files — that Claude loads automatically when your request matches, thanks to progressive disclosure.
• The description in a skill is what tells Claude when to use it, so write it precisely.
• Choose by weight: start with a slash command for quick prompts; graduate to a skill when the workflow grows or you want it triggered automatically.