Custom Commands vs Skills

Once a Claude Code workflow stabilizes, you stop typing the same multi-step prompt over and over. You capture it once and invoke it by name. That is what custom commands and skills are for: reusable, named units of behavior that live in your project or your home directory.

Two axes define everything in this lesson. First, the mechanism: .claude/commands/ is the legacy approach, .claude/skills/ is the current one. Second, the scope: project (shared via VCS) versus user (personal, in ~/.claude/). Get both axes right and your team gets consistent, portable workflows.

A custom command is a markdown file in .claude/commands/. The filename becomes the command name, and the body is the prompt that runs when you invoke it. It is essentially a saved prompt template you trigger by name instead of retyping.

Commands are simple and still work, but they are the legacy approach. They carry no structured metadata for isolating output or restricting tools. For new work, prefer skills, which add exactly those controls.

A skill lives in .claude/skills/ and is the current, richer replacement for commands. Beyond the prompt body, a skill supports frontmatter that controls how it executes. Three fields matter for the exam:

• context: fork — run the skill in an isolated context so its verbose output does not pollute the main conversation.
• allowed-tools — restrict which tools the skill may call (least privilege).
• argument-hint — document the arguments the skill expects.

These controls are exactly what a legacy command lacks.

Here is a skill that runs a code review. The frontmatter is delimited by ---; the body below it is the instruction Claude follows when the skill is invoked.

Notice context: fork isolates the review's discovery output, allowed-tools caps it to read and search tools (no Write, no Bash), and argument-hint tells the user what to pass.

Skills often produce a lot of intermediate noise: file dumps, search hits, exploration steps. If that all lands in your main conversation, it crowds the context window and triggers lost-in-the-middle, where the model attends less to content buried between the start and end.

context: fork runs the skill in an isolated context, like an explore subagent during discovery. The verbose work happens elsewhere and only the distilled result returns. This keeps the main session lean and your attention focused on what matters.

The allowed-tools field restricts a skill to only the tools it genuinely needs. A review skill should read and search but never write or run shell commands; scoping it that way removes a whole class of accidental mutations.

This mirrors least-privilege agent design elsewhere in the certification: scope tools to the role, and remember that 4-5 tools is the sweet spot while 18+ degrades selection reliability. A focused, well-scoped skill is both safer and more reliable.

Independent of commands-versus-skills, every command or skill has a scope determined by where the file lives:

• Project scope: .claude/commands/ or .claude/skills/ inside the repo. Committed to VCS, so the whole team gets it automatically.
• User scope: the same folders under ~/.claude/. Personal to your machine, NOT shared via VCS.

This is the exact same project-versus-user distinction as the CLAUDE.md hierarchy and .mcp.json versus ~/.claude.json. The rule is consistent across Claude Code config.

Use project scope whenever a workflow should be standard for everyone touching the repo. A shared /review-pr skill means every engineer reviews diffs the same way; a shared /migrate skill encodes your migration rules once.

Because it is committed to VCS, a new teammate cloning the repo gets these immediately, with zero setup. If you ever think "the team should all do this the same way," the answer is project scope.

Use user scope (~/.claude/) for personal conveniences that are not part of the team's contract: your own scratch helpers, a personal note-taking command, shortcuts tied to your local setup.

The trade-off is the same as user-level CLAUDE.md: it follows you across all projects but is NOT shared via VCS, so teammates never see it. If a workflow needs to be reproducible for the whole team, user scope is the wrong choice precisely because it is invisible to everyone else.

Mechanism and scope are independent, so you have a full grid to design against:

• Project skill — shared, current, with fork/allowed-tools controls. The default for team workflows.
• User skill — personal, current, still gets the rich frontmatter.
• Project command — shared but legacy; fine if it already exists, but migrate when you need isolation or tool restriction.
• User command — personal and legacy.

For anything new and team-facing, the strong default is a project-scoped skill.

Migration is usually mechanical: move the file from .claude/commands/ to .claude/skills/, then add frontmatter to gain the controls you were missing. A pure prompt becomes a governed workflow.

The payoff is concrete: context: fork stops verbose review output from polluting your session, and allowed-tools guarantees the skill cannot write or run shell commands. Same intent, but now isolated and scoped.

Your team keeps running an ad-hoc multi-step PR-review prompt by hand. You want it standardized for everyone on the repo, runnable by name, and you want its noisy file-dump and search output kept OUT of the main conversation while ensuring it can never edit files. What should you build?

Key takeaways:

• Two mechanisms: .claude/commands/ is legacy, .claude/skills/ is current. Prefer skills for new work.
• Skills add frontmatter commands lack: context: fork (isolate verbose output), allowed-tools (restrict tools, least privilege), argument-hint (document args).
• Two scopes: project (.claude/, shared via VCS) vs user (~/.claude/, personal, NOT shared) — the same axis as CLAUDE.md and MCP config.
• Team workflow that must be reproducible → project-scoped skill. Personal convenience → user scope.
• Migrate a command to a skill by moving the file and adding frontmatter; never substitute a prose CLAUDE.md note for a deterministic allowed-tools restriction.