Claude Skills vs Commands

Current answer, not the old mental model

Claude Code’s extension model has evolved. A command and a skill are no longer two completely separate systems where one is always a shortcut and the other always activates automatically.

The skill folder is the richer current format. It can contain metadata, detailed instructions, references, scripts, and assets. Skills may be discovered automatically from their description and can also support explicit invocation.

Legacy custom command files continue to work. They remain useful as explicit, lightweight prompts, but new workflows that need more structure generally belong under .claude/skills/.

Comparison table

Question	Skill	Legacy custom command
Project path	.claude/skills/<name>/SKILL.md	.claude/commands/<name>.md
Automatic discovery	Yes, based on skill metadata and task match	Usually invoked explicitly
Slash invocation	Supported when configured as invocable	Primary interaction model
Supporting files	Native folder structure for scripts, references, and assets	Possible only through paths the prompt manages itself
Metadata	YAML frontmatter describes name, activation, and behavior	Command frontmatter and prompt content
Best fit	Reusable workflow with context or resources	Small explicit action or existing compatible shortcut
Distribution	Copy/upload the folder or package it in a plugin	Copy the command file or include compatible files in a package

Use a skill for reusable behavior

Choose a skill when the workflow needs one or more of these:

• Claude should recognize the task without the user memorizing a command.
• Detailed instructions should load only when relevant.
• Scripts make part of the work deterministic.
• Reference documents, examples, or templates belong with the procedure.
• The workflow needs a clear activation description.
• The same package should work as both discovered knowledge and an explicit action.

A debugging method is a good example. The skill can require reproduction, evidence gathering, one hypothesis at a time, verification, and regression checks. It may include reference material without putting the whole procedure in every session.

Keep a command for a deliberate shortcut

An explicit command is still a sensible interface when:

• the action is small and unambiguous;
• automatic activation would be surprising;
• the user must choose the exact moment it runs;
• an existing team workflow already depends on the command name;
• no scripts, references, assets, or progressive loading are needed.

For example, a command that formats the current branch name into a release note heading may not need a full skill. The explicit trigger is part of its usefulness.

When to migrate a command

Migrate an existing command when it has become a miniature application hidden inside one Markdown file:

1. Create .claude/skills/<name>/SKILL.md.
2. Move the reusable workflow and metadata into the skill.
3. Put long references, templates, and scripts in adjacent files.
4. Write a precise description for automatic discovery.
5. Preserve explicit invocation when users still need it.
6. Test the task both by natural-language matching and direct invocation.

Do not migrate merely to use a newer folder name. The change should improve discoverability, maintainability, or resource organization.

Examples

Workflow	Better starting point	Why
Run a full pre-release verification process	Skill	Ordered checks, scripts, and references
Insert a standard issue template	Command	Small, explicit, predictable action
Diagnose a failing test suite	Skill	Reusable method and progressive evidence gathering
Rename the current terminal session	Command	Narrow shortcut with deliberate invocation
Generate a branded slide deck	Skill	Templates, assets, file-generation rules, and validation
Create another skill	Skill	Multi-step format and quality workflow

Browse Writing Skills, Systematic Debugging, and Verification Before Completion for public source profiles. They are not hands-on ratings.

Common mistakes

Treating every slash command as a separate architecture

Invocation syntax is an interface choice. First decide where the reusable instructions and resources belong, then decide whether the user should invoke them explicitly.

Giving an automatic skill a vague description

If the description says only “helps with code,” discovery will be noisy. Name the trigger, scope, expected input, and result.

Hiding a large workflow in one command file

Long prompts with embedded scripts and references are difficult to review. A skill folder separates the main procedure from supporting material.

Removing a working command without checking users

Legacy command files remain compatible. Preserve familiar entry points when migration would disrupt a team, then phase them out deliberately.

Decision rule

Use the skill format as the default for new reusable Claude Code workflows. Keep an explicit command when deliberate invocation is the feature, not a limitation. A skill can still expose a command, so you often do not need to choose between rich packaging and a fast trigger.

For folder and installation details, read Claude Code Skills. For distribution, compare Skills vs Plugins.

Primary sources

• Claude Code: Extend Claude with skills
• Claude Code: Plugins reference
• Anthropic: What are skills?