Custom Command and Skill Design in Claude Code: Automating Development Workflows

When introducing Claude Code into daily development workflows, repeatedly entering complex prompts causes a drop in work efficiency and leads to input errors. Manually instructing code reviews that comply with team standard rules or checking for specific security vulnerabilities every time is inefficient. By codifying these boilerplate prompts as version-controlled assets and registering them as slash commands (/commands) or autonomously executable “Skills,” you can automate the development process. This article explains how to implement and design these features.

1. Basics of Custom Slash Commands

The simplest automation method is to define custom slash commands using Markdown files. The file name is registered directly as the command name (e.g., /review-pr for review-pr.md). Custom commands can be placed in either a project-specific scope or a global scope across the user’s environment.

• Project-specific scope: Saved in .claude/commands/ directly under the project root.
• Global scope: Saved in ~/.claude/commands/ under the user’s home directory.

Implementation of a custom command to retrieve Pull Request diffs and perform a review:

---
description: PRの差分をレビューし、改善案を提示します
---
!git diff main...HEAD
上記の差分を確認し、以下の観点でレビューを行ってください：
1. パフォーマンス上の懸念点
2. セキュリティ脆弱性
3. コーディング規約の遵守

After saving this file, typing / in a Claude Code interactive session will display /review-pr in the completion suggestions. Execution with arguments:

/review-pr

This eliminates the hassle of manually retrieving diffs and pasting prompts.

2. Advanced Command Features: Arguments, Namespaces, and Frontmatter

To achieve more flexible automation, custom commands support dynamic arguments, organization via namespaces, and metadata configuration using YAML frontmatter.

Dynamic Arguments ($ARGUMENTS): The $ARGUMENTS placeholder captures any text entered after the slash command. For example, if you run /fix-issue 1234, you can define it to be processed internally as “Find and fix issue #1234”.

Namespaces (Subdirectories): When the number of commands increases, you can organize them by creating subdirectories. A file placed in .claude/commands/frontend/component.md is executed via the namespace path:

/frontend/component "Button"

Control via YAML Frontmatter: By adding YAML frontmatter to the beginning of a Markdown file, you can control the execution environment, the model used, and access permissions to tools.

---
description: コミットメッセージを自動生成します
argument-hint: 追加のコンテキスト（任意）
allowed-tools:
  - shell
model: claude-3-5-haiku-latest
---
<git_diff>
!git diff --cached
</git_diff>

上記の差分に基づき、Conventional Commits形式でコミットメッセージを生成してください。
$ARGUMENTS

The specifications of the main parameters are as follows. description indicates the purpose of the command, and allowed-tools restricts the tools permitted to run. In the model specification, specifying haiku for lightweight tasks such as commit message generation can improve response speed and suppress token consumption. The backtick syntax starting with an exclamation mark (!) executes a command in the local shell and directly injects its output into the prompt.

3. Extending to Skills

With updates to Claude Code, custom commands and “Skills” have been organized into an integrated execution framework. Both .claude/commands/review.md and .claude/skills/review/SKILL.md are registered as the /review command, but the Skill format is recommended for new implementations. If the same name exists, the Skill takes precedence.

Skills are managed as folder-level assets and have the structure .claude/skills/<name>/SKILL.md. They support Autonomous Triggering, allowing Claude to automatically launch a Skill based on context without the user explicitly executing a command. Additionally, because of the folder structure, they have the advantage of being able to bundle related documents and templates.

---
description: プロジェクトのセキュリティ脆弱性をスキャンし、修正案を提示します
disable-model-invocation: true
---
プロジェクト全体のソースコードを静的解析し、OWASP Top 10に該当する脆弱性がないか確認してください。

💡 Important Parameters: description is a semantic description that serves as a trigger for autonomous execution. Claude analyzes this description to determine the application scenario. disable-model-invocation: true is used to prevent autonomous execution and restrict it to manual execution only for processes with side effects, such as infrastructure changes or database operations.

4. Architectural Comparison: Distinguishing CLAUDE.md and Commands/Skills

5. Practical Example: Building a Pipeline from Review to Fix

Automating code reviews specialized for a specific technology stack is effective for maintaining quality. Implementation of a custom code review Skill for a Flutter project:

---
description: Flutterのベストプラクティスに基づきコードをレビューします
model: claude-3-5-sonnet-latest
---
以下のFlutter/Dartの観点でコードを精査してください：
- Widgetの肥大化（抽出の必要性）
- Riverpod等の状態管理の適切な利用
- const修飾子の不足
- 非同期処理の例外ハンドリング

As an execution flow, you can build a pipeline where you first run /flutter-review lib/src/features/ to retrieve issues, and then apply fixes using commands like /fix. This automates consistent quality control.

6. Considerations in Command and Skill Design

• Description Optimization: For Skills that allow autonomous execution, place clear trigger keywords at the beginning of the description to suppress model misjudgments.
• Thorough Safety Measures: ⚠️ If the process includes destructive operations that affect the system, always set disable-model-invocation: true to force manual execution.
• Leveraging Lightweight Models: 🛠️ For tasks that do not require complex reasoning, specify model: haiku to improve execution speed and reduce costs.
• Version Control: Include the .claude/ directory in your Git repository to share automation workflows across the entire team.
• Suppressing Token Consumption: Consolidating instructions into structured command files prevents the context window from becoming congested during sessions.

Key Takeaways

• Efficiency via Commands: Save frequently used prompts in .claude/commands/ to execute them instantly with arguments.
• Dynamic Context: You can leverage shell execution result injection via the ! syntax and dynamic processing via $ARGUMENTS.
• Autonomous Skills: You can define Skills that can be automatically launched based on context using .claude/skills/.
• Separation of Concerns: Maintain a clean configuration by defining persistent rules in CLAUDE.md and execution procedures in commands or Skills.