“Custom commands” is still a useful way to think about repeatable Claude Code workflows, but the current product model is broader: Anthropic has merged custom commands into skills. Existing Markdown files under .claude/commands/ continue to work, while new reusable workflows are generally better created as skills under .claude/skills/<name>/SKILL.md. Both can create slash-invoked behavior such as /deploy or /review-release.
This change matters because a skill is more than a saved prompt. It can include frontmatter that controls invocation, supporting files, dynamic context injection, tool permissions, and behavior that Claude can load automatically when a request matches the skill description. A command can therefore become a maintained piece of project automation rather than a block of text that developers copy between chats.
For teams building a wider Claude engineering environment, the important question is not how many slash commands exist. It is which recurring procedures deserve a versioned, reviewable workflow.
The current path is skills, with commands kept for compatibility
Anthropic’s current Claude Code documentation explicitly says that custom commands have been merged into skills. A file such as .claude/commands/deploy.md can still create /deploy, but a skill at .claude/skills/deploy/SKILL.md provides the same invocation while also supporting a directory of related files. The documentation recommends skills for new work.
This is a good migration path because existing repositories do not need to rewrite every command immediately. Teams can leave stable command files in place and use the skill format when a workflow needs examples, scripts, schemas, or other reference material. Over time, high-value commands can be migrated deliberately rather than through a disruptive bulk change.
The slash interface remains familiar to users. Typing /name can invoke a skill directly, while some skills can also be loaded automatically when Claude decides they are relevant.
A good skill starts with a narrow job description
The description is not marketing copy. It helps Claude decide when the skill applies, so it should name the task and the situations that should trigger it. “Helps with development” is too broad. “Summarizes uncommitted changes and flags risky edits before a commit” gives the runtime a useful decision boundary.
The body should then define the procedure. It can tell Claude what evidence to read, what checks to perform, what output format to return, and what conditions require escalation. The best skill captures a workflow the team already understands rather than inventing a complicated process simply because it can be automated.
This is the same distinction found in automation and orchestration: a reusable procedure is valuable when the steps and handoffs are explicit.
Project skills turn team practice into repository state
A project skill stored under the repository’s .claude/skills/ directory can be committed with the code. That gives the team one reviewed definition of the workflow. When the procedure changes, the skill changes in version control alongside the system it describes.
This is useful for tasks such as release checks, incident triage, API migration reviews, architecture-note generation, or repository-specific testing. The skill can reference the project’s conventions and supporting files without putting all of that detail into a global user prompt.
Personal skills under ~/.claude/skills/ serve a different purpose. They are useful for individual workflows that should follow a developer across projects. Enterprise or managed locations can distribute standardized skills more broadly. The scope should match ownership: repository procedure belongs with the repository, while personal productivity behavior usually does not.
Dynamic context makes a command react to the current repository
Claude Code skills can inject command output into the prompt before Claude sees it. Anthropic’s documentation shows this pattern with shell commands that collect live context such as a Git diff. That means a skill can arrive already grounded in the current working tree instead of asking Claude to remember to gather the same evidence every time.
Dynamic context should be small and purposeful. Dumping an entire repository or massive log into every invocation wastes context and can hide the signal. A release skill might inject the current branch, recent commits, and a targeted diff. A troubleshooting skill might inject the failing command and a bounded log excerpt.
The commands used for injection still need a trust model. If the repository can influence the executed command or its arguments, validate that input. Treat dynamic context as a tool boundary, not as free text substitution.
Tool permissions belong with the procedure
A repeatable workflow is easier to trust when its required tools are declared narrowly. A read-only review skill should not need write access. A commit skill may need specific Git commands but not arbitrary shell execution. A deployment procedure may need access to one approved deployment command while still blocking unrelated operations.
Skill frontmatter can pre-approve relevant tools in supported configurations, but the organization’s managed permission rules remain the higher boundary. This is healthy: a repository should not be able to grant itself authority that policy administrators intentionally prohibited.
The result is a layered permission model similar to a well-designed Claude Code CI workflow: the procedure states what it needs, while the environment decides what it is actually allowed to receive.
Arguments make skills reusable without making them vague
A command can accept parameters so the same workflow operates on different targets. A skill might take an issue number, service name, release tag, or path. The instructions should define what the argument means and what validation is required rather than treating the entire remaining command line as unstructured prose.
Where a small fixed set of options exists, document them. Where the argument is an identifier, tell Claude how to verify it before acting. The goal is to preserve the repeatable procedure while changing only the target.
Arguments should not become a back door for arbitrary shell. A skill that ultimately interpolates user text into a command needs the same validation that a normal application would apply to untrusted input.
Invocation control is especially useful for procedures with side effects. A skill that exists only to deploy, publish, delete, or mutate production state should not necessarily be auto-selected just because a request sounds related. Claude Code supports frontmatter such as disable-model-invocation: true, which keeps a skill out of automatic model invocation until the user calls it directly. That gives teams a clean distinction between reusable reference knowledge Claude may load when relevant and explicit operator commands that should run only when a person deliberately invokes them.
Name collisions and scope should be intentional
Claude Code can load skills from several locations, including personal, project, enterprise, additional-directory, plugin, and synced sources. Built-in commands and bundled skills also occupy names. Current documentation defines precedence behavior when names collide, so teams should avoid relying on accidental shadowing.
A repository should choose names that describe its workflow and are unlikely to conflict with common built-ins. Namespaces are useful when several related procedures exist. If a local skill intentionally replaces a bundled behavior, that decision should be obvious in code review rather than discovered by a developer after /name does something unexpected.
For monorepos, nested skills can be useful because the correct procedure may depend on the package being edited. The scope should be as narrow as the rules it encodes.
Skills should be evaluated like code
A skill can become infrastructure for important work, so it deserves tests and review. Try it on representative repositories and failure cases. Confirm that it gathers the intended evidence, uses the right tools, stops at the right point, and produces an output that another person can act on. If a workflow is costly, measure token and tool usage as part of the evaluation.
Version changes can also affect behavior. Claude Code evolves quickly, including bundled skills and skill-loading behavior. Keep project skills explicit enough that a future maintainer can tell which behavior comes from repository instructions and which comes from the product.
Most importantly, do not use a skill to hide a poorly understood process. If the team cannot explain when a deployment is safe or which evidence a review requires, encoding the ambiguity in Markdown will not make the workflow reliable.
Skills should also be distinguished from CLAUDE.md. Repository instructions in CLAUDE.md are useful for standing context that should shape many tasks, such as coding conventions or build commands. A skill is better for a named procedure that has a beginning, an expected sequence, and an output. Moving every repository rule into a slash-invoked skill would make ordinary work forget important defaults; putting every detailed workflow into always-loaded instructions would consume context and blur when the procedure should run.
Migration from older command files can therefore be selective. Keep a simple command if it is stable and needs only a short prompt. Move it to a skill when the workflow benefits from supporting files, explicit metadata, controlled invocation, dynamic context, or declared tool access. During migration, avoid keeping two independently maintained versions of the same procedure under the same or confusingly similar names.
A useful review question is whether the procedure can be understood without knowing who originally wrote it. The skill should explain its trigger, required evidence, permitted actions, stopping condition, and expected result clearly enough that another maintainer can audit it. That turns the file from a personal prompt shortcut into durable project knowledge.
The best custom command becomes a small piece of operating knowledge
Claude Code’s move from standalone custom commands toward skills reflects a useful idea: repeated instructions are more valuable when they are structured, scoped, versioned, and attached to the tools and references they need. The slash command remains a convenient way to invoke the workflow, but the reusable asset is the procedure behind it.
Start with recurring work that already has a clear definition of success. Capture the evidence it needs, grant only the tools it requires, make the scope obvious, and commit project-specific skills with the repository. The result is less prompt repetition and more consistent execution without turning every interaction into a rigid template.
