How to Build Custom Commands for Claude Code Using Agent Skills Standard

If you are using Claude Code, you might have noticed a major shift: custom commands have officially been merged into the open Agent Skills standard.

While legacy commands placed in .claude/commands/ will still work, the recommended approach is to build your custom tools as Skills. Why? Because this standard allows you to bundle supporting files, executable scripts, and use advanced configurations like pre-processing shell commands before the LLM even sees them.

Here is a definitive, step-by-step guide to building powerful custom commands (slash-commands like /deploy) using the new standard.

---

1. Choose a Location and Create the Directory

First, decide whether your command should be global (across all projects) or project-specific:

• Personal (Global): ~/.claude/skills/<skill-name>/
• Project-specific: .claude/skills/<skill-name>/

Let's create a deploy command. Open your terminal and run:

mkdir -p .claude/skills/deploy/

2. Create the SKILL.md File (The Brain)

Every command requires a SKILL.md file. The top of this file must include a YAML frontmatter block to define metadata.

Here is what you need to know about the fields:

• name: This dictates your console command. Setting name: deploy creates the /deploy command.
• description: Crucial for the AI to understand the tool's purpose.
• disable-model-invocation: true: Do not skip this. This prevents Claude from running the workflow on its own initiative, ensuring it only executes when you explicitly type the /slash-command.
• argument-hint: Shows up in the UI autocomplete (e.g., [branch-name]).

3. Write the Task Content & Handle Arguments

Below the frontmatter, write the Markdown instructions. For custom commands, these are usually step-by-step instructions.

You can dynamically handle user input using variables:

• $ARGUMENTS: Injects everything typed after the slash command. (e.g., If you run /deploy staging, $ARGUMENTS becomes staging).
• Index-based variables: Use $0, $1, etc., to grab specific words from the input.

4. 🤯 The Killer Feature: Dynamic Context (The ! syntax)

This is where the Agent Skills standard shines. If your command needs real-time data before Claude starts processing, you can use the ! command syntax.

When you include a shell command preceded by an exclamation mark (e.g., ! git log -1), Claude Code executes the command immediately in the background and substitutes the placeholder with the actual terminal output before sending the prompt to the model. This saves tokens, reduces latency, and prevents hallucinations.

5. Add Supporting Scripts (Optional)

Unlike legacy commands, Skills allow you to bundle multiple files. You can keep your SKILL.md clean and place complex logic in subdirectories like scripts/, references/, or assets/.

💡 Pro Tip for Scripts: Use the ${CLAUDE_SKILL_DIR} variable in your instructions. This ensures the path to your script is resolved correctly, regardless of which directory the user was in when they invoked the command.

---

Example: A Complete Deployment Command

Here is what a production-ready .claude/skills/deploy/SKILL.md file looks like:

---
name: deploy
description: Builds the project and deploys it to the specified environment.
disable-model-invocation: true
argument-hint: [environment-name]
allowed-tools: [Bash]
---

You are executing my custom deploy command.
Target environment: $ARGUMENTS

Step 1: Run the bundled build script.
Execute the following: `bash ${CLAUDE_SKILL_DIR}/scripts/build.sh $0`

Step 2: Read the latest commit to verify what we are deploying: 
`! git log -1 --oneline`

Step 3: Confirm the build was successful, analyze the git log, and summarize the deployment process for the user.

Once this file is saved, Claude Code automatically discovers it. You can immediately jump into your terminal and run /deploy production.

Are you migrating your legacy CLI scripts to Agent Skills yet? Let me know what custom commands you are building in the comments!