Skills and Custom Commands
How to design reusable Claude Code commands for team workflows.
Current Model
Claude Code now treats custom commands and skills as one slash-command experience. Existing
.claude/commands/*.md files still work, but new workflows should usually use
.claude/skills/<name>/SKILL.md because skills support frontmatter controls, supporting files,
scripts, dynamic context injection, and better invocation behavior.
Recommended Shape
.claude/skills/
release-check/
SKILL.md
checklist.md
scripts/
collect-release-info.sh---
name: release-check
description: Check release risk, test coverage, and documentation gaps.
disable-model-invocation: true
allowed-tools: Read Grep Bash
---
Release target: $ARGUMENTS
Current effort: ${CLAUDE_EFFORT}
1. Summarize the changed area.
2. Check required tests and docs.
3. Return blockers first, then follow-up risks.Key Controls
| Control | Use it when |
|---|---|
description | Claude needs to decide whether the skill is relevant. |
disable-model-invocation: true | The workflow has side effects and should only run when the user types it. |
user-invocable: false | The skill is background knowledge, not a user command. |
allowed-tools | The skill needs pre-approved tools while still respecting global permissions. |
$ARGUMENTS, $0, $1 | The command needs user-supplied input. |
${CLAUDE_EFFORT} | The skill should adapt depth to current effort. |
When to Keep .claude/commands
Keep legacy command files when the prompt is short, has no supporting files, and is already widely used by the team. Move it to a skill when you need scripts, examples, references, or explicit invocation controls.
Validation
- Run
/skillsand search for the command name. - Invoke the command with a sample argument.
- Confirm whether Claude can invoke it automatically or only the user can.
- Keep
SKILL.mdconcise and move long references into separate files. - Review
allowed-toolsas a permission grant, not just documentation.
Related Commands
/skills: list and filter available skills./plugin: distribute shared skills and commands./reload-plugins: apply plugin changes without restarting./fewer-permission-prompts: generate allowlist suggestions from repeated safe calls.