Claude Code Automated Refactoring Workflow Setup Guide

Setting up an automated refactoring workflow in Claude Code means encoding your team's clean-code standards into a reusable custom slash command that reads a file, applies improvements, runs tests, and reports results — all from a single short invocation like /refactor src/auth/login.ts. This guide walks you through exactly how to build that workflow using Claude Code's slash command system.

What Are Slash Commands in Claude Code?

Slash commands are special directives typed directly into the Claude Code terminal interface, each prefixed with a forward slash (/). They give developers a fast, deterministic way to control session behavior — things like compressing context, switching models, clearing history, or running diagnostic checks — without needing to phrase requests in natural language.

Two categories matter for refactoring workflows:

• Built-in commands — bundled with Claude Code and cover common session management tasks (e.g., /compact, /clear, /help).
• Custom commands — Markdown files you author that Claude follows like a playbook, encoding repeatable workflows such as code reviews, security scans, and refactors.

How Do You Create a Custom Refactoring Command?

There are two approaches. The Skills approach is newer and more powerful; the legacy approach is simpler and still fully supported.

Option A: Skills Approach (Recommended for New Commands)

Skills live in a dedicated directory and use a SKILL.md file with YAML frontmatter. This approach supports extra features: bundled supporting files, automatic invocation by Claude when relevant, and the $ARGUMENTS placeholder for passing parameters at invocation time.

1. Install Claude Code and open a terminal session.
2. Create the skill directory: mkdir -p ~/.claude/skills/refactor
3. Create a SKILL.md file inside that directory.
4. Add YAML frontmatter with a name field (this becomes the slash command), a description, and an allowed-tools list (e.g., Read, Edit, Bash).
5. Below the frontmatter, write Markdown instructions describing your refactoring steps — what to check, how to apply changes, how to run tests, and what to report.
6. Use $ARGUMENTS in the body wherever you want the file path or other parameters to be substituted at invocation time.
7. Start or restart a Claude Code session: claude
8. Invoke the command: /refactor src/auth/login.ts

Option B: Legacy Approach (Simple, Always Works)

1. Create the personal commands directory: mkdir -p ~/.claude/commands
2. Create a Markdown file: touch ~/.claude/commands/refactor.md
3. Add YAML frontmatter and Markdown instructions specifying allowed tools and refactoring criteria.
4. Start a Claude Code session and invoke: /refactor src/auth/login.ts

With the legacy approach, the filename becomes the command name. These files still work reliably — use them if you already have them or if you don't need automatic invocation or argument passing.

What Should a Refactoring Command Actually Do?

A well-designed /refactor command encodes a repeatable multi-step workflow. Based on the source use case, a personal /refactor skill should:

• Read the target file passed via $ARGUMENTS
• Apply clean-code principles (e.g., extract magic strings, consolidate duplicated logic, add typed error handling)
• Run the test suite to verify nothing broke
• Report results — what changed and whether tests passed

Here is what a successful invocation looks like in practice:

/refactor src/auth/login.ts

Reading src/auth/login.ts...
Identified issues: magic strings, duplicated validation logic, missing error types.
Applying changes: extracted constants, consolidated validators, added typed error handling.
Running tests... 12/12 passed. Refactoring complete.

Encoding this workflow as a slash command saves time and ensures every refactor follows the same standards, regardless of who on the team runs it.

When Should You Use Project-Scoped vs. Personal Commands?

Scope determines who can access the command and where it lives on disk.

For a team refactoring standard, use a project-scoped command so every developer gets the same behavior automatically when they check out the repository.

How Do You Discover and Invoke Commands?

Typing / in a Claude Code session opens an autocomplete menu showing all available built-in and custom commands. You can select a command from the list or type its name directly. Commands are also accessible programmatically: the Agent SDK exposes available slash commands in the system initialization message, which is useful for building automated pipelines around your refactoring workflow.

What Are the Most Common Pitfalls When Setting Up This Workflow?

Command doesn't appear in autocomplete

Verify the file is in the correct directory. For Skills, confirm the directory contains a SKILL.md file with a valid name field in the frontmatter. Restart the Claude Code session (exit, then claude) after creating new files.

$ARGUMENTS appears literally in output

Confirm the placeholder is spelled exactly as $ARGUMENTS (all caps) in the SKILL.md body. Also ensure you are passing arguments when invoking the command — for example, /refactor src/auth/login.ts rather than /refactor with no arguments.

Skill description gets truncated

Each skill's combined name and description text is subject to a character budget. Front-load the most important keywords in the description field. Write descriptions as keyword-dense phrases rather than full sentences — burying keywords in long prose reduces match accuracy and wastes the character budget. To increase the budget, set the relevant environment variable before starting Claude Code. See the slash commands character budget documentation for details.

Getting trapped in a bad multi-file refactor

Before authorizing risky, wide-ranging changes, use /fork to create a named checkpoint. If the refactor corrupts the codebase, you can abandon the branch and resume from the clean checkpoint rather than trying to command Claude to undo its own broken output.

Losing accumulated context mid-refactor

Default to /compact for routine context management — it summarizes history and preserves key decisions. Reserve /clear only when pivoting to a completely unrelated task where prior context would actively mislead Claude.

Is the Skills Approach Worth the Extra Setup?

For a refactoring workflow specifically, yes. The Skills approach adds three meaningful capabilities over legacy commands:

• Automatic invocation — Claude can proactively invoke the skill when it detects relevant context, without you typing the command.
• Argument passing — The $ARGUMENTS placeholder lets you target any file path at invocation time, making the command genuinely reusable across your codebase.
• Bundled supporting files — You can include style guides, checklists, or example diffs alongside the SKILL.md for Claude to reference.

If you already have a working legacy refactor.md command, there is no urgent reason to migrate — it continues to work. But for new commands, Skills is the better foundation.

How Do Teams Share Refactoring Commands Across Machines?

Two options exist. The straightforward approach is committing project-scoped commands (.claude/skills/ or .claude/commands/) to version control — every developer gets them on checkout. The newer option is packaging commands as a plugin: a bundle of slash commands, subagents, MCP servers, and hooks that installs across all developer machines with a single /plugin install command inside Claude Code, eliminating manual filesystem setup for shared command collections.

Quick Reference: Building Your Refactoring Workflow

1. Decide on scope: personal (~/.claude/skills/refactor/) or project (.claude/skills/refactor/).
2. Create the directory and a SKILL.md file inside it.
3. Write YAML frontmatter: set name, description (keyword-dense), and allowed-tools.
4. Write Markdown instructions: read file via $ARGUMENTS, apply clean-code rules, run tests, report results.
5. Restart Claude Code and type / to confirm the command appears in autocomplete.
6. Invoke with a target: /refactor src/your/file.ts.
7. Commit project-scoped commands to version control so teammates get them automatically.