Claude Code Custom Slash Commands for Team Workflows

Claude Code custom slash commands are now best treated as Skills. Legacy .claude/commands/*.md files still work, but the recommended pattern for reusable team workflows is .claude/skills/<name>/SKILL.md. That distinction matters if you are trying to standardize engineering workflows without mixing prompt reuse, enforcement, memory, and agent delegation into one confusing bucket.

The practical rule is simple: use slash-style Skills for repeatable human workflows, hooks for actions that must always happen, subagents for isolated specialist work, plugins for distribution and governance, and CLAUDE.md only for facts and rules that should be loaded at the start of every session.

Where Claude Code custom slash commands fit now

Older Claude Code examples often show custom slash commands as Markdown files under .claude/commands/. That format is still supported. Current Anthropic documentation, however, says custom commands have been merged into Skills.

For a platform team, that means new shared workflows should usually live here:

.claude/skills/<workflow-name>/SKILL.md

A Skill can still be invoked directly as a slash command, such as /fix-issue or /release-prep. The advantage is that Skills add structure that legacy command files do not handle as well: frontmatter, supporting files, automatic invocation metadata, argument definitions, tool permissions, and optional forked context.

There is one migration detail to handle carefully. Legacy .claude/commands/ files still load, but a same-name Skill takes precedence. Before moving a command library into Skills, check for name collisions across enterprise, personal, project, and plugin-provided customizations.

When a slash-style Skill is the right tool

Create a slash-style Skill when engineers repeatedly paste the same instructions, checklist, or multi-step procedure into Claude Code. Good candidates are workflows that benefit from a known name and a consistent starting point, but still require judgment from the model and the engineer.

Examples from the brief fit this pattern well:

• /pr-review for a structured pull request review checklist.
• /release-prep for validating release notes, tests, version changes, and deployment readiness.
• /migration-plan for producing a staged code migration plan before edits begin.
• /incident-patch for narrowing the fix, risk, validation steps, and rollback plan.
• /dependency-update for reviewing package changes, compatibility notes, and test scope.

The value is discoverability. A command name gives engineers a shared handle. A Skill gives the platform team a maintainable home for the procedure.

What belongs in a Skill

A useful team Skill should explain when to use it, what inputs it accepts, what tools it may use, and what output the engineer should expect. Anthropic documents frontmatter fields such as description, when_to_use, argument-hint, arguments, allowed-tools, disallowed-tools, context: fork, and invocation controls.

For example, an issue-fixing workflow can accept an issue number:

/fix-issue 123

Skills support parameter substitution through $ARGUMENTS, positional values such as $0 and $1, and named arguments. That lets the workflow stay reusable without forcing engineers to edit the prompt every time.

Keep the Skill focused on the procedure. If the workflow says "review the diff, inspect comments, propose a patch, run tests, and summarize risk," that is a good Skill. If the workflow must block a merge unless tests pass, that is not a Skill by itself. That belongs in hooks, CI, or repository policy.

Use hooks when the action must be deterministic

Slash commands and Skills are still model-interpreted instructions. They make behavior easier to repeat, but they do not guarantee that a step will always run exactly the same way.

Hooks are the enforcement layer. The brief highlights Anthropic's guidance to use hooks when actions must always happen instead of relying on the model to choose them. For an engineering enablement team, this is the difference between a helpful prompt and a control point.

Use hooks for rules such as:

• Block or log user-typed skills and custom commands through UserPromptExpansion.
• Add required context before a workflow expands.
• Enforce project rules that should not depend on the model remembering them.

One specific trap is worth calling out: direct user slash-command invocations bypass PreToolUse. If your governance model assumes PreToolUse will catch every command invocation, it will miss this path. Use UserPromptExpansion for user-typed Skills and custom commands.

Keep CLAUDE.md small and always-on

CLAUDE.md is loaded at session start. That makes it useful for persistent project facts and standing rules, but expensive and noisy for long procedures.

Put stable facts in CLAUDE.md: repository conventions, test commands, architecture notes, or rules that should be present in every session. Move multi-step workflows into Skills. Move area-specific guidance into path-scoped rules where that is more appropriate.

This boundary prevents the common failure mode where CLAUDE.md becomes a pile of workflows, policies, examples, and one-off reminders. When that happens, every session pays the context cost, and engineers still struggle to find the one procedure they need.

Use subagents for isolated specialist work

Subagents are for isolated context and specialized execution. They are useful when the work is noisy, narrow, or benefits from a separate context window. Skills can also run in a forked subagent with context: fork.

In practice, that means a slash-style Skill can remain the user-facing entry point while a subagent handles part of the work. For example, /pr-review can define the review procedure, while a forked context handles a large diff analysis without filling the main conversation with every intermediate step.

Do not treat subagents as a replacement for Skills. A Skill names and structures the workflow. A subagent isolates execution when the workflow needs it.

Use plugins when the workflow becomes a product

Repo-local Skills are the simplest place to start. They work well when one repository needs one shared workflow.

Plugins become useful when the same workflow needs packaging, distribution, and stronger governance across teams. Anthropic documents plugins as a way to package and distribute skills, agents, hooks, MCP servers, and other customizations. Managed settings can also restrict teams to plugin or managed customizations through strictPluginOnlyCustomization.

Community examples show why this matters. One command library advertises 57 production-ready slash commands. Another advertises 216+ slash commands, 12 Claude Code Skills, and 54 AI agents. Whether or not those exact layouts match your standard, they prove the demand: teams want named, reusable workflows at scale.

Govern risky features explicitly

Skills can inject dynamic context with ! command substitution. That can pull in outputs from commands such as gh pr diff, gh pr view --comments, or git diff HEAD before Claude sees the prompt. It also executes shell commands during prompt expansion, so it needs explicit governance.

Set a policy before rolling this out broadly. The brief points to three practical options:

• Allow shell substitution only in managed Skills.
• Disable shell execution for user, project, plugin, and additional-directory Skills with disableSkillShellExecution.
• Require review for Skills that use shell substitution or broad allowed-tools.

Also mark risky human workflows as explicit-only. For side-effecting or timing-sensitive commands such as /commit, /deploy, or /send-slack-message, use disable-model-invocation: true. That prevents Claude from triggering the Skill automatically and keeps the engineer in control.

A practical team standard

If you are standardizing Claude Code custom slash commands for a team, start with a short decision table:

Then define naming and ownership rules. Keep names short and action-oriented. Check for collisions because enterprise, personal, project, and plugin sources can override by name. Set a minimum Claude Code version before relying on advanced Skill fields, shell substitution controls, or forked Skill behavior.

Finally, decide what "done" means for each workflow. A code review Skill can produce findings and test recommendations. A release Skill can prepare a checklist. A deploy command should not be model-invoked by surprise. A test requirement should be enforced outside the prompt.

Checklist for your first shared Skill

• Use .claude/skills/<name>/SKILL.md for new shared workflows.
• Keep legacy .claude/commands/ only where compatibility requires it.
• Add clear description and when_to_use metadata.
• Use arguments for issue numbers, PR numbers, package names, or release targets.
• Set allowed-tools and disallowed-tools deliberately.
• Use disable-model-invocation: true for side-effecting workflows.
• Govern ! shell substitution before teams copy it into local Skills.
• Use hooks for enforcement, especially UserPromptExpansion for user-typed commands.
• Move long procedures out of CLAUDE.md.
• Use plugins when the workflow needs organization-wide distribution.

The main decision is not whether slash commands are still useful. They are. The decision is where they belong in the current Claude Code model. For new team workflows, make the slash command a Skill, then use hooks, subagents, plugins, and CLAUDE.md for the parts they are actually designed to handle.