Claude Code Skills: Automate Your Workflow with Custom Commands

Deploy steps, PR review checklists, security audits — explaining these procedures to Claude Code every time is tedious. With skills, you can save those instructions in a file and invoke them as slash commands like /deploy or /pr-check. Define them once, pass arguments as needed, and commit .claude/skills/ to your repo so the whole team shares the same workflows.

Extend Claude with skills - Claude Code Docs

Create, manage, and share skills to extend Claude's capabilities in Claude Code. Includes custom com...

code.claude.com

What Are Skills?

Skills are custom slash commands you can register in Claude Code. Create a .claude/skills/{skill-name}/SKILL.md file and it becomes available as /{skill-name}.

A skill file contains instructions written in Markdown. Claude Code reads the file and follows the instructions to carry out the task. Once defined, a skill can be reused as many times as you like, and committing it to your repository makes it available to everyone on your team.

Item	Details
Location (Project)	.claude/skills/{skill-name}/SKILL.md
Location (Personal)	~/.claude/skills/{skill-name}/SKILL.md
How to invoke	/{skill-name}
Arguments	Pass after the command, separated by spaces

Skills placed under .claude/skills/ can be committed to the repository and shared across the team. Skills placed under ~/.claude/skills/ apply only to you. Shared team workflows belong in the project directory; personal preferences and custom flows belong in your personal directory.

Creating a Skill File

A skill file is a Markdown file with a frontmatter section and a body. The frontmatter includes name and description.

---
name: deploy
description: Deploy to the staging environment
---

# Deploy Steps

Deploy to the staging environment using the following steps.

1. Run the test suite and confirm all tests pass
2. Push to remote with `git push origin main`
3. Run the deploy script
4. Verify the deployment

The description is used in the skill list and helps Claude Code understand when to use the skill. Write something that clearly describes what the skill does.

The body contains the instructions in plain language or Markdown. Claude Code receives this as a prompt and works through it step by step.

Invoking Skills and Passing Arguments

Type /{skill-name} in the Claude Code chat to run a skill. Add arguments after a space to pass them along.

/deploy staging

Inside the skill file, use the $ARGUMENTS placeholder to receive whatever was passed. Document how arguments are used in the instructions so Claude Code interprets them correctly.

You can also describe what to do when no arguments are provided — for example, "if no argument is given, ask the user" — so the skill handles missing input gracefully instead of stopping.

To pass multiple arguments, continue after the first with spaces. Documenting each argument's role in the skill file helps Claude Code process them correctly. For required arguments, add a note like "if the argument is missing, ask the user before proceeding" to prevent errors from incomplete input.

Automatic Skill Invocation

Claude Code always keeps an eye on each skill's description. When the conversation matches a skill's description, Claude Code loads that skill automatically, without you having to invoke it explicitly.

For example, if you write description: Review a pull request, Claude Code will automatically apply that skill's instructions when you say something like "review this branch." By defining different checklists or review criteria per skill, your project-specific workflows get applied naturally during conversation.

How you write the description affects how accurately auto-invocation triggers. A generic description like "edit files" may cause the skill to be loaded in unrelated conversations. Writing a specific description that captures the operation and context ensures the skill is only invoked when appropriate.

Disabling Automatic Invocation

For tasks like deployments or production operations where accidental execution would be a problem, add disable-model-invocation: true to the frontmatter. This prevents Claude Code from loading the skill automatically — it will only run when you type /deploy explicitly.

---
name: deploy
description: Deploy to the staging environment
disable-model-invocation: true
---

Any skill with side effects is a good candidate for this setting, keeping Claude Code from triggering it based on context alone.

Tips for Writing Skills

Whether a skill behaves as intended depends heavily on how its instructions are written. Keep the following in mind to build reliable skills.

For tasks where order matters, write steps as a numbered list — this helps Claude Code follow them in sequence. State any prerequisites (required tools, expected environment, etc.) at the top of the file to prevent the skill from running in an unintended context.

Document how $ARGUMENTS is used and what happens when no argument is provided. Including error-handling instructions — such as "if the command fails, check the error message and report the cause" — lets the skill cover troubleshooting as well.

It's also worth keeping each skill focused on a single purpose. Packing multiple unrelated tasks into one skill makes it harder for Claude Code to behave predictably. Designing with "one skill, one purpose" in mind keeps behavior easy to reason about.

Use Cases

Use case	Skill example	Description
Deployment	/deploy	Package deploy steps so the same procedure runs every time
PR review	/pr-check	Define security, performance, and style criteria for consistent reviews
Security audit	/security-check	Register a security checklist to avoid missing anything
Infrastructure	/launch-ec2	Save EC2 start/stop procedures and specify the environment via arguments
Commit messages	/commit	Define commit message conventions to generate consistent messages

Skills vs CLAUDE.md

Alongside skills, Claude Code supports CLAUDE.md — a project configuration file. CLAUDE.md is the right place for rules and background information that should always apply across the whole project. Skills are the right place for step-by-step procedures you only need when performing a specific task.

For example, "write commit messages in English" and "run tests before opening a PR" belong in CLAUDE.md. "The exact steps to create a commit" or "how to run a deployment" belong in a skill. Thinking of CLAUDE.md as "always-on rules" and skills as "on-demand procedure guides" keeps both easy to maintain.

If you're unsure whether something belongs in CLAUDE.md or a skill, ask yourself: "Do I need this information all the time, or only when performing a specific action?" If CLAUDE.md is growing unwieldy, it may be time to extract task-specific procedures into skills.

Example Skill

Here's a PR review skill to illustrate how to think through the design.

Start by deciding which perspectives to cover. Grouping them into categories helps Claude Code work through each one systematically, reducing the chance of missing something. This skill uses three categories: Security, Performance, and Coding Standards. Adjust the categories to match your project's priorities.

The target branch changes every time the skill is invoked, so it's passed in via $ARGUMENTS. Anything that varies per invocation should use a placeholder rather than being hardcoded — this keeps the skill reusable.

This skill doesn't include disable-model-invocation because it's fine for Claude Code to load it automatically when you say something like "review this branch." For skills with side effects — like a deployment — you'd add that setting to restrict execution to explicit invocations only. This kind of judgment call is worth thinking through when designing a skill.

Create .claude/skills/pr-check/SKILL.md as follows.

---
name: pr-check
description: Review a pull request
---

# PR Review

Review the pull request from the following perspectives.

## Security
- Check for SQL injection, XSS, and other vulnerabilities
- Verify that authentication and authorization are handled correctly
- Confirm no secrets or credentials are included in the code

## Performance
- Look for N+1 query issues
- Identify unnecessary loops or duplicate processing

## Coding Standards
- Check that naming follows the project conventions
- Confirm tests are written
- Verify that comments are appropriate

Branch to review: $ARGUMENTS

Pass a branch name as the argument and Claude Code expands $ARGUMENTS to that value, reviewing the changes against the criteria above.

/pr-check feature/add-login

Summary

• Skills are custom slash commands created by adding a skill file to a project or personal directory
• Write the name and description in frontmatter, and the instructions in the Markdown body
• Invoke manually with a slash command and pass arguments to make skills reusable
• Claude Code automatically loads a skill when the conversation matches its description
• Use the frontmatter setting to disable auto-invocation for skills with side effects
• Deployments, PR reviews, security audits, and infrastructure tasks are all good candidates for skills