Tidy First — AI Code Refactoring Skill for Agents

What it is

Tidy First is an AI agent skill that encodes Kent Beck's refactoring methodology into a structured set of instructions for AI coding assistants. The core idea: before making a behavioral change to code, consider making small structural improvements first. These tidyings make the subsequent change easier, safer, and more readable.

The skill targets developers using AI coding agents like Claude Code or Cursor who want their agents to follow disciplined refactoring practices rather than making ad-hoc changes to messy code.

How it saves time or tokens

Without the Tidy First discipline, AI agents tend to make behavioral changes directly into tangled code, producing patches that are hard to review and prone to regressions. By training the agent to tidy first, each change becomes two small, reviewable commits: one structural (renaming, extracting, reordering) and one behavioral (the actual feature or fix).

This separation reduces code review time, makes git history more meaningful, and prevents the accumulation of technical debt that eventually slows down entire teams.

How to use

1. Save the Tidy First skill as ~/.claude/skills/tidy-first/SKILL.md in your AI agent's skill directory.
2. The skill activates automatically when the agent encounters code that would benefit from structural improvement before a behavioral change.
3. The agent will propose tidyings first (extract function, rename variable, reorder declarations), then make the behavioral change in a separate step.

Example

# Tidy First Skill

Before making behavioral changes, consider small structural tidyings.
Apply these patterns when code is messy:

Tidying patterns

• Guard clauses: replace nested if/else with early returns
• Extract helper: pull repeated logic into a named function
• Rename for clarity: make variable names reveal intent
• Reorder declarations: group related code together
• Remove dead code: delete unused functions and variables

Workflow

1. Read the code that needs changing
2. Identify structural issues that make the change harder
3. Apply 1-3 tidyings in a separate commit
4. Make the behavioral change in a clean commit

Related on TokRepo

• AI coding tools -- tools for AI-assisted development workflows
• Prompt library -- reusable prompts and skills for AI agents

Common pitfalls

• Over-tidying: the skill should apply 1-3 small tidyings before a change, not refactor the entire file. Scope discipline is critical.
• Tidying without tests: structural changes can introduce subtle bugs. Ensure tests pass after each tidying commit before proceeding to behavioral changes.
• Mixing tidying and behavior in one commit defeats the purpose. The value comes from separation -- one commit per concern.