Agent skill
repo-cleanup
Systematic cleanup of repository clutter including build artifacts, duplicates, temp files, and consolidation of scattered directories. Use for repository maintenance, artifact removal, directory consolidation, and gitignore updates.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/repo-cleanup-vamseeachanta-workspace-hub
SKILL.md
Repository Cleanup Skill
Quick cleanup of repository clutter including build artifacts, duplicates, temp files, and consolidation of scattered directories into standard locations.
Version Metadata
version: 2.2.0
python_min_version: '3.10'
dependencies: []
compatibility:
tested_python:
- '3.10'
- '3.11'
- '3.12'
- '3.13'
os:
- Windows
- Linux
- macOS
When to Use
- Repository has accumulated build artifacts and temp files
- Multiple agent/coordination directories scattered in root
- Log files and coverage reports cluttering the workspace
- Need to consolidate prototype code and test outputs
- Preparing for a clean commit or release
- After major refactoring work
Cleanup Categories
1. Build Artifacts
Files generated during build/install processes that should not be tracked.
| Pattern | Description | Location |
|---|---|---|
*.egg-info/ |
Python package metadata | src/*/ |
__pycache__/ |
Python bytecode cache | Throughout |
.pytest_cache/ |
Pytest cache | Root and test dirs |
build/ |
Build output directory | Root |
dist/ |
Distribution packages | Root |
*.pyc |
Compiled Python files | Throughout |
*.pyo |
Optimized Python files | Throughout |
Cleanup commands:
# Find all build artifacts
find . -type d -name "__pycache__" -o -name "*.egg-info" -o -name ".pytest_cache"
# Remove Python cache (safe - regenerated automatically)
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null
find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null
2. Log Files
Generated log files that accumulate during development and testing.
| Pattern | Description |
|---|---|
*.log |
General log files |
*LogFile.txt |
OrcaFlex log files |
*.log.* |
Rotated log files |
debug.log |
Debug output |
Cleanup commands:
# Find log files
find . -name "*.log" -o -name "*LogFile.txt"
# Remove log files (verify first)
find . -name "*.log" -type f -delete
find . -name "*LogFile.txt" -type f -delete
3. Temp Files
Temporary files created during processing or editing.
| Pattern | Description |
|---|---|
*.tmp |
Temporary files |
.temp/ |
Temp directories |
cache/ |
Cache directories |
*.bak |
Backup files |
*.swp |
Vim swap files |
*~ |
Editor backup files |
Cleanup commands:
# Find temp files
find . -name "*.tmp" -o -name "*.bak" -o -name "*.swp" -o -name "*~"
# Remove temp files
find . \( -name "*.tmp" -o -name "*.bak" -o -name "*.swp" -o -name "*~" \) -type f -delete
4. Coverage Reports
Test coverage artifacts that can be regenerated.
| Pattern | Description |
|---|---|
htmlcov/ |
HTML coverage reports |
.coverage |
Coverage data file |
.coverage.* |
Parallel coverage data |
coverage.xml |
XML coverage report |
Cleanup commands:
# Remove coverage artifacts
rm -rf htmlcov/
rm -f .coverage .coverage.* coverage.xml
5. IDE Artifacts
Editor and IDE generated files.
| Pattern | Description |
|---|---|
.idea/ |
PyCharm/IntelliJ |
.vscode/ |
VS Code (keep settings.json) |
*.code-workspace |
VS Code workspaces |
.spyproject/ |
Spyder IDE |
Note: Some IDE settings may be intentionally tracked. Check .gitignore first.
6. Benchmark Artifacts
Benchmark directories often contain mixed content that needs separation.
| Pattern | Description | Action |
|---|---|---|
benchmarks/reports/ |
Timestamped HTML reports | Add to .gitignore |
benchmarks/results/ |
Timestamped CSV/JSON | Add to .gitignore |
benchmarks/legacy_projects/ |
Reference test data | Move to tests/fixtures/ |
benchmarks/*.py |
Benchmark scripts | Keep tracked |
Cleanup commands:
# Move test fixtures to proper location
mkdir -p tests/fixtures/orcaflex
git mv benchmarks/legacy_projects/* tests/fixtures/orcaflex/
# Untrack generated outputs
git rm -r --cached benchmarks/reports benchmarks/results
# Add to .gitignore
echo "benchmarks/reports/" >> .gitignore
echo "benchmarks/results/" >> .gitignore
Consolidation Patterns
Agent Directories
Multiple agent-related directories should consolidate to .claude/agents/.
Before:
root/
├── agents/
├── .agents/
├── agent_configs/
└── .agent-os/
After:
.claude/
└── agents/
├── core/
├── devops/
└── specialized/
Commands:
# Find scattered agent directories
find . -maxdepth 2 -type d -name "*agent*"
# Move to consolidated location
git mv agents/* .claude/agents/ 2>/dev/null
git mv .agents/* .claude/agents/ 2>/dev/null
rm -rf agents .agents agent_configs
Runtime/Coordination Data
Runtime data should go to .claude-flow/ (gitignored).
Move to .claude-flow/:
- Session state files
- Coordination lock files
- Runtime cache
- Worker state
Commands:
# Create runtime directory
mkdir -p .claude-flow/state
mkdir -p .claude-flow/cache
# Move runtime files (don't use git mv - these are untracked)
mv .coordination/* .claude-flow/state/ 2>/dev/null
mv .session/* .claude-flow/state/ 2>/dev/null
Prototype Code
Prototype and experimental code should go to examples/prototypes/.
Commands:
mkdir -p examples/prototypes
git mv prototype_*.py examples/prototypes/
git mv experimental/ examples/prototypes/
Test Outputs
Test output files should go to tests/outputs/ (gitignored).
Commands:
mkdir -p tests/outputs
mv tests/*.html tests/outputs/
mv tests/*.json tests/outputs/
mv tests/test_results/ tests/outputs/
Plan Files
Completed specification plans should be archived.
Pattern:
- Active plans:
specs/modules/<plan>.md - Completed plans:
specs/archive/<plan>.md
Commands:
# Archive completed plan (check status: completed in YAML frontmatter)
mkdir -p specs/archive
git mv specs/modules/<completed-plan>.md specs/archive/
Hidden Folder Cleanup
Legacy AI and agent hidden folders often accumulate during development. These need review and consolidation.
Common Hidden Folders
| Folder | Description | Action |
|---|---|---|
.agent-os/ |
Legacy agent OS framework | Consolidate to .claude/ |
.ai/ |
Legacy AI configuration | Consolidate to .claude/ |
.agent-runtime/ |
Runtime symlinks (often dead) | Delete if dead links |
.common/ |
Orphaned utility scripts | Delete or relocate to scripts/ |
.specify/ |
Stale specification templates | Delete if unused |
.drcode/ |
External tool config (Dr. Code) | Keep if actively used |
.slash-commands/ |
Command registry | Keep |
Discovery Commands
# List all hidden directories with sizes
du -sh .*/ 2>/dev/null | grep -v "^\./\.git"
# Find dead symlinks in hidden folders
find .agent-runtime -type l ! -exec test -e {} \; -print 2>/dev/null
# Count files in each hidden directory
for dir in .claude .agent-os .ai .common .specify; do
if [ -d "$dir" ]; then
count=$(find "$dir" -type f | wc -l)
echo "$dir: $count files"
fi
done
Cleanup Commands
# Remove dead symlink directories
rm -rf .agent-runtime/
# Remove stale template directories
rm -rf .specify/
# Remove orphaned utilities (after relocating useful scripts)
rm -rf .common/
# Consolidate .agent-os to .claude
git mv .agent-os/agents/* .claude/agents/ 2>/dev/null
git mv .agent-os/skills/* .claude/skills/ 2>/dev/null
git mv .agent-os/docs/* .claude/docs/ 2>/dev/null
rm -rf .agent-os/
# Consolidate .ai to .claude
git mv .ai/config/* .claude/config/ 2>/dev/null
git mv .ai/prompts/* .claude/prompts/ 2>/dev/null
rm -rf .ai/
Consolidation Merge Strategies
When merging folders, file conflicts are common. Use these strategies to preserve important content while eliminating duplicates.
Conflict Resolution Patterns
| Conflict Type | Strategy | Example |
|---|---|---|
| Same filename | Rename with suffix | README.md -> README-legacy.md |
| Similar content | Use subdirectory | commands/ -> commands/legacy-scripts/ |
| Unique content | Preserve in dedicated folder | Keep implementation-history/ |
| Clear duplicates | Delete after verification | Remove exact copies |
Merge Commands
# Rename conflicting files before merge
mv .agent-os/README.md .agent-os/README-legacy.md
# Create legacy subdirectory for scripts
mkdir -p .claude/commands/legacy-scripts
git mv .agent-os/commands/* .claude/commands/legacy-scripts/
# Preserve unique historical content
git mv .agent-os/implementation-history/ .claude/docs/implementation-history/
# Find and remove exact duplicates (verify first)
md5sum .claude/agents/*.md .agent-os/agents/*.md | sort | uniq -w32 -d
Pre-Merge Checklist
- Compare file lists between source and target
- Identify naming conflicts
- Decide rename vs. subdirectory strategy
- Document unique content to preserve
- Verify duplicates before deletion
File Count Verification
Track consolidation progress with file counts to ensure nothing is lost.
Progress Tracking Commands
# Count tracked files in each hidden folder
for dir in .claude .agent-os .ai; do
count=$(git ls-files "$dir" 2>/dev/null | wc -l)
echo "$dir: $count files"
done
# Count all files (tracked + untracked)
for dir in .claude .agent-os .ai .common .specify; do
if [ -d "$dir" ]; then
tracked=$(git ls-files "$dir" 2>/dev/null | wc -l)
total=$(find "$dir" -type f | wc -l)
echo "$dir: $tracked tracked, $total total"
fi
done
# Before/after comparison
echo "=== Before Consolidation ===" > consolidation-log.txt
for dir in .claude .agent-os .ai; do
count=$(git ls-files "$dir" 2>/dev/null | wc -l)
echo "$dir: $count files" >> consolidation-log.txt
done
Verification After Merge
# Verify no files were lost
expected_count=150 # Set to sum of source folders
actual_count=$(git ls-files .claude | wc -l)
echo "Expected: $expected_count, Actual: $actual_count"
# List any untracked files that might have been missed
git status --porcelain | grep "^??" | grep -E "^\?\? \.(claude|agent-os|ai)/"
Discovery Commands
List Untracked Files
# All untracked files
git status --porcelain | grep "^??"
# Untracked files with size
git status --porcelain | grep "^??" | cut -c4- | xargs -I {} sh -c 'du -h "{}" 2>/dev/null'
Find Large Files
# Files larger than 1MB
find . -type f -size +1M -exec ls -lh {} \;
# Files larger than 10MB
find . -type f -size +10M -exec ls -lh {} \;
# Largest files in repo
find . -type f -exec du -h {} + 2>/dev/null | sort -rh | head -20
Find Duplicates
# Find duplicate markdown files in agent directories
find . -name "*.md" -path "*/agents/*" -type f
# Find files with same name
find . -type f -name "*.py" | xargs -I {} basename {} | sort | uniq -d
# Find duplicate by content (requires md5sum)
find . -type f -exec md5sum {} + | sort | uniq -w32 -d
Find Hidden Directories
# List all hidden directories
find . -maxdepth 1 -type d -name ".*" | grep -v "^\./\.git$"
# Hidden directories with sizes
du -sh .*/
Safe Deletion Commands
For Tracked Files (Use git rm)
# Remove tracked file
git rm path/to/file
# Remove tracked directory
git rm -r path/to/directory
# Remove from git but keep local copy
git rm --cached path/to/file
For Untracked Files (Use rm)
# Remove untracked file
rm path/to/file
# Remove untracked directory
rm -rf path/to/directory
# Interactive removal (safer)
rm -i path/to/file
Dry Run First
# Preview what would be deleted
git clean -n -d
# Preview including ignored files
git clean -n -d -x
Gitignore Updates
Add these entries to .gitignore after cleanup:
# Build artifacts
__pycache__/
*.py[cod]
*$py.class
*.egg-info/
*.egg
build/
dist/
.eggs/
# Test artifacts
.pytest_cache/
.coverage
.coverage.*
htmlcov/
coverage.xml
*.cover
# IDE
.idea/
.vscode/
*.code-workspace
.spyproject/
# Logs
*.log
*LogFile.txt
# Temp files
*.tmp
*.bak
*.swp
*~
.temp/
cache/
# Runtime data (claude-flow)
.claude-flow/
.coordination/
.session/
# Benchmark generated outputs
benchmarks/reports/
benchmarks/results/
# Test outputs
tests/outputs/
tests/*.html
tests/*.json
# Large binary files
*.sim
*.dat
*.bin
Cleanup Checklist
Pre-Cleanup
- Git working directory status documented
- Important untracked files identified
- Backup created if needed
Build Artifacts
-
__pycache__/directories removed -
*.egg-info/directories removed -
.pytest_cache/removed -
build/anddist/removed if present
Log Files
-
*.logfiles removed or archived -
*LogFile.txtfiles removed - Rotated logs cleaned
Temp Files
-
*.tmpfiles removed - Editor backup files removed
- Cache directories cleaned
Coverage Reports
-
htmlcov/removed -
.coveragefiles removed
Consolidation
- Agent directories consolidated to
.claude/agents/ - Runtime data moved to
.claude-flow/ - Prototypes moved to
examples/prototypes/ - Test outputs moved to
tests/outputs/ - Benchmark test fixtures moved to
tests/fixtures/ - Benchmark generated outputs untracked and gitignored
- Completed plan files archived to
specs/archive/
Hidden Folder Review
-
.agent-os/reviewed and consolidated -
.ai/reviewed and consolidated -
.agent-runtime/deleted if dead symlinks -
.common/relocated or deleted -
.specify/deleted if stale
Post-Cleanup
-
.gitignoreupdated with new patterns -
git statusshows clean or expected state - Tests still pass after cleanup
Final Cleanup Checklist
Based on actual cleanup sessions, these folders have been verified for removal or consolidation.
Folders to DELETE (Confirmed Safe)
| Folder | Reason | Verification |
|---|---|---|
.drcode/ |
Legacy AI config (Dr. Code) | Not referenced in any scripts or CI |
.benchmarks/ |
Empty benchmark folder | ls .benchmarks/ returns empty or missing |
.agent-runtime/ |
Dead symlinks only | find .agent-runtime -type l ! -exec test -e {} \; |
.common/ |
Orphaned utilities | No imports reference this folder |
.specify/ |
Stale specification templates | Specs moved to specs/templates/ |
Folders to CONSOLIDATE
| Source | Destination | Command |
|---|---|---|
.slash-commands/ |
.claude/docs/commands/ |
git mv .slash-commands/* .claude/docs/commands/ |
.git-commands/ |
scripts/git/ |
git mv .git-commands/* scripts/git/ |
.agent-os/ |
.claude/ |
See module-based-refactor skill |
.ai/ |
.claude/ |
See module-based-refactor skill |
Folders to KEEP
| Folder | Reason |
|---|---|
.githooks/ |
Standard location for git hooks |
.github/ |
GitHub workflows and templates |
.claude/ |
Authoritative AI configuration |
.vscode/ |
Team VS Code settings (if tracked) |
Cleanup Commands
# Delete legacy config folders
rm -rf .drcode/
rm -rf .benchmarks/
# Consolidate slash-commands to docs
mkdir -p .claude/docs/commands
git mv .slash-commands/* .claude/docs/commands/ 2>/dev/null
rm -rf .slash-commands/
# Consolidate git-commands to scripts
mkdir -p scripts/git
git mv .git-commands/* scripts/git/ 2>/dev/null
rm -rf .git-commands/
# Verify cleanup
ls -la .* 2>/dev/null | grep "^d"
README Update Checklist
After cleanup, update the README to reflect the new structure.
Structure Section Updates
- Update directory tree to show new structure
- Remove references to deleted folders
- Add
.claude/folder description - Document
scripts/git/consolidation - Note module-based architecture in src/
Example README Structure Section
## Repository Structure
project/
├── .claude/ # AI configuration and documentation
│ ├── agents/ # Agent definitions
│ ├── docs/ # Reference documentation
│ ├── skills/ # Skill definitions
│ └── settings.json # Claude Code settings
├── .githooks/ # Git hooks
├── scripts/ # Utility scripts
│ └── git/ # Git-related scripts
├── src/<pkg>/modules/ # Source modules (5-layer architecture)
├── tests/modules/ # Test modules
├── specs/modules/ # Specification modules
├── docs/modules/ # Documentation modules
└── examples/modules/ # Example modules
References to Remove
-
.agent-os/- consolidated to.claude/ -
.ai/- consolidated to.claude/ -
.drcode/- deleted (legacy) -
.slash-commands/- consolidated to.claude/docs/commands/ -
.git-commands/- consolidated toscripts/git/
Best Practices
- Always verify before deleting - Use
findandlsbeforerm - Use git rm for tracked files - Preserves history and staging
- Update .gitignore first - Prevents re-adding cleaned files
- Commit cleanup separately - Keep cleanup commits distinct from feature work
- Document what was removed - Use clear commit messages
- Check file sizes - Large files may need special handling (Git LFS)
Related Skills
- module-based-refactor - For restructuring after cleanup
- session-start-routine - Session initialization
References
- Git clean documentation: https://git-scm.com/docs/git-clean
- Git rm documentation: https://git-scm.com/docs/git-rm
- Gitignore patterns: https://git-scm.com/docs/gitignore
Version History
- 2.2.0 (2026-01-20): Added Benchmark Cleanup and Plan File Archival patterns
- Added Benchmark Artifacts section for handling benchmark directories
- Added Plan Files section for archiving completed specifications
- Added benchmark patterns to .gitignore recommendations
- Updated checklist with benchmark and plan archival items
- 2.1.0 (2026-01-20): Added Final Cleanup Checklist and README Update Checklist
- Added Final Cleanup Checklist with verified DELETE/CONSOLIDATE/KEEP tables
- Confirmed .drcode/ as safe to delete (legacy AI config)
- Added .slash-commands/ consolidation to .claude/docs/commands/
- Added .git-commands/ consolidation to scripts/git/
- Added .benchmarks/ as safe to delete if empty
- Added README Update Checklist for structure documentation
- Added example README structure section template
- Added references to remove checklist
- 2.0.0 (2026-01-20): Major update with hidden folder cleanup learnings
- Added Hidden Folder Cleanup section with legacy AI folder patterns
- Added Consolidation Merge Strategies for conflict resolution
- Added File Count Verification for tracking consolidation progress
- Updated Cleanup Checklist with hidden folder review items
- Documented patterns for .agent-os, .ai, .agent-runtime, .common, .specify, .drcode, .slash-commands
- 1.0.0 (2025-01-20): Initial release based on digitalmodel repository cleanup session
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?