skills.rest
Asher-Plihal
Asher-PlihalCOMMUNITY
Explore all skills by this author →
GitHub

repo-hygiene

Reorganize files, rename vague code, and refresh CLAUDE.md without changing behavior.

Updated May 15, 2026
Search Tags:#refactoring#code organization#naming conventions#folder structure#repository cleanup#dead code removal#AI agent readiness
One-click install
npx skills add https://github.com/Asher-Plihal/claude-skills --skill repo-hygiene-asher-plihal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: repo-hygiene
Source: https://github.com/Asher-Plihal/claude-skills/tree/main/repo-hygiene
Command: npx skills add https://github.com/Asher-Plihal/claude-skills --skill repo-hygiene-asher-plihal

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Repo hygiene fixes messy codebases whose structure and naming have become unclear enough to slow humans down and cause AI agents to make the wrong assumptions, while keeping working behavior unchanged.

Core Features & Use Cases

  • Structure cleanup without behavioral change: reorganizes files and folders into a clear hierarchy (e.g., frontend/backend/shared separation, domain-based folders, and removal of junk drawers like /utils and /helpers) so contributors and agents can navigate quickly.
  • Explicit naming and cohesion improvements: renames vague code to be more descriptive, splits mixed-domain files when a split test fails, and collapses redundant/shallow folders to improve locality of behavior.
  • Safety-focused refactoring and documentation refresh: removes dead/duplicate code, rewrites comments to explain WHY, and refreshes CLAUDE.md while verifying moves/renames to avoid breaking working code.

Quick Start

Use repo-hygiene to audit and clean up a messy codebase by reorganizing folders, renaming vague files/functions, removing dead or duplicate code, and updating CLAUDE.md without changing program behavior.

Frequently Asked Questions about repo-hygiene

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I clean up a messy repository structure without changing code behavior?▼

Repository cleanup without behavior changes involves behavior-preserving file and folder restructuring, explicit renames, and dead code removal, followed by test verification after each refactoring phase to ensure working code stays intact.

What is the best way to reorganize folder structure for AI agent readability?▼

Reorganizing folder structure for AI agent readability requires removing junk drawers like utils and helpers, separating frontend backend and shared domains, and refreshing CLAUDE.md so agents can navigate and reason about the code correctly.

How do I safely remove dead code and duplicate functions during a refactor?▼

Safe dead code removal during a refactor uses a read-only audit to identify unused files and duplicate functions, then verifies moves and renames with test runs to avoid breaking working code before final deletion.

Why does my AI coding agent make mistakes when navigating my codebase?▼

AI coding agents make mistakes when repository structure and naming conventions are ambiguous, causing wrong assumptions about domain boundaries, which requires explicit renames and folder restructuring to resolve.

When should I use a behavior-preserving refactoring approach for my codebase?▼

Behavior-preserving refactoring is needed after major merges, during ongoing refactors, or when repeated AI mistakes suggest ambiguity in layout or naming, ensuring structure improvements do not alter program logic.

Related Skills

Explore More Software Engineering Skills→
terakoya76terakoya76

refactor-clean

Identify and remove dead code with test verification during refactors.

Community
Advanced
berkcangumusisikberkcangumusisik
11

inline-comments

Generate rationale-focused inline comments with before/after diffs for JavaScript, TypeScript, and Python code.

Community
Intermediate
roderikroderik
2

code-simplifier

Refactor recently modified code for clarity while preserving behavior.

Community
Basic
erichugyerichugy

file-naming

Enforce descriptive file and folder naming conventions in repositories.

Community
Intermediate