The problem: where does your "ritual" live?
If you use Claude Code for more than a week, you'll quickly hit a friction: there's a set of instructions you repeat every time. "Run the tests, if they pass commit with this format, if they fail open plan mode." "Before reviewing a PR, read CLAUDE.md, then pull the diff, then compare against the team conventions." "When writing a Supabase migration, check RLS before applying."
These rituals are knowledge you — or your team — own, which Claude does not know by default. You have two official ways to teach it: slash commands and skills. They solve the same problem from opposite directions. This article explains the difference, when to use each one, and how to organize both inside .claude/ without bloating the agent's context.
If you don't yet have the big-picture view of Claude Code, start with the definitive guide to Anthropic's CLI and come back — from here on I assume you know the seven pillars of the CLI.
Slash commands: explicit invocation
A slash command is a markdown file you invoke by name. .claude/commands/deploy.md becomes /deploy. When you type it, Claude Code injects the file's contents at the top of the prompt, as if you had pasted the text yourself.
Minimal anatomy:
---
description: Deploy the blog to Cloudflare Pages
argument-hint: [optional branch]
---
Run the deploy steps:
1. `cd blog && npm run build`
2. If it fails, stop and show me
3. If it passes, run `npm run deploy`
4. Paste the wrangler output at the end
Three important traits:
- Always explicit. The command only fires when you type
/deploy. The model never invokes it on its own. - Takes arguments.
/deploy mainmakesmainavailable as a variable inside the prompt. - Version-controlled. Because it's a file in the repo, it lives in git, becomes part of onboarding, and evolves with the project.
Slash commands are the right tool when you want full control over when the ritual runs. Deploys, opening a PR, generating a changelog, end-of-sprint routine — anything with a clear invocation moment.
For a step-by-step tutorial on your first command (including arguments, personal vs project scope, and debugging the file), read Creating custom Claude Code slash commands.
Skills: implicit invocation by the model
Skills solve the other side: the model decides when to activate. A skill lives at .claude/skills/<name>/SKILL.md and starts with a YAML block describing the trigger:
---
name: supabase-migration
description: |
Use when the user asks to create a Supabase migration, add a new table,
change a column type, or modify an RLS policy. Covers naming, rollback
plan and RLS-by-default.
---
# Writing Supabase migrations
When creating a new migration file, follow these rules:
...
The description is the trigger. Claude Code reads the description of every loaded skill at the start of the session, and when your prompt semantically matches one of them, the agent loads the SKILL.md contents (and its attached files) into context automatically.
Why this matters: you don't have to remember to invoke. If you describe "I need to add a status column to the posts table", the supabase-migration skill activates on its own. If your new teammate opens the repo and asks for the same thing, the skill activates for them too — without them knowing it exists.
The golden rule for writing a skill: the description must be a trigger, not a summary. Bad: "Supabase migrations." Good: "Use when the user asks to create a Supabase migration, add a new table, change a column type, or modify an RLS policy." The model needs to know when to activate, not what the skill does inside.
Slash commands vs skills: one decision, one criterion
There is exactly one criterion for choosing between them: who decides when the ritual runs?
| Who invokes | Tool | |---|---| | You, at a specific moment | Slash command | | The model, when it detects context | Skill |
If the answer is "always at a specific moment — after the commit, before the deploy, at the end of the sprint": slash command. If it's "every time anyone touches this part of the code, even if they don't know the pattern exists": skill.
Some hybrid cases fit both — and it's legitimate to have a skill that also exposes a slash command as a shortcut when you want to invoke it manually. But start from the criterion; it resolves 80% of the cases painlessly.
A common confusion early on is mixing skills with subagents. Skills give instructions + knowledge to the main agent. Subagents are separate processes with isolated context. I covered the detailed difference, including cases where each is the wrong choice, in Skills vs Subagents: when to use each one — worth reading before you unnecessarily bloat your .claude/skills/.
Scope: personal, project, global
Both slash commands and skills accept three scopes:
- Project —
.claude/commands/and.claude/skills/in the repo. Versioned, shared with the team. - Personal —
~/.claude/commands/and~/.claude/skills/. Only yours, available in any project. - Plugin — installed via
claude plugin. Public, maintained by third parties.
Practical rule: what is project knowledge goes in the project (deploy, schema, conventions). What is your way of working goes in personal (your favorite /commit, your skill for reviewing code with a critical eye). Resist mixing them — you'll want to share the first and keep the second private.
The hidden cost: context and attention
Skills have a cost that slash commands don't: every active skill consumes context window, even when the agent isn't going to use it. Each skill's description sits in the initial prompt, and if the skill activates, the whole SKILL.md is pulled in too.
In practice, this means: don't install 40 skills "just in case". Every skill in the folder competes for attention. Ten well-described skills produce better activation than fifty generic ones. For a minimum viable arsenal — the skills I install on day one in any new project — see 10 essential Skills for Claude Code productivity.
Slash commands don't carry this cost: they only enter the context when you type the command. Cost-benefit wise, prefer a slash command when you can, use a skill when you need automatic activation.
Next steps
Start by creating a slash command for your most annoying ritual — your /commit with its standard message, or /deploy. Then turn your most important pattern into a skill and watch the automatic activation work. The step-by-step guide lives at Creating custom Slash Commands, and when you want to level up and delegate parallel exploration, move on to Subagents in Claude Code. If you're planning large refactors with several chained shortcuts, turn on Plan Mode before execution — it pairs extremely well with well-written skills.
