AgentSkillsCN

repo-cleanup

系统性清理仓库中的杂乱内容,包括构建产物、重复文件、临时文件,以及分散目录的整合与归并。适用于仓库维护、制品移除、目录整合,以及 .gitignore 文件的更新。

SKILL.md
--- frontmatter
name: repo-cleanup
description: 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.
version: 2.2.0
updated: 2026-01-20
category: meta
triggers:
- repository cleanup
- artifact removal
- temp file cleanup
- duplicate files
- build artifacts
- cache cleanup
- directory consolidation
- gitignore update
- log file cleanup
- untracked files

Repository Cleanup Skill

Quick cleanup of repository clutter including build artifacts, duplicates, temp files, and consolidation of scattered directories into standard locations.

Version Metadata

yaml
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.

PatternDescriptionLocation
*.egg-info/Python package metadatasrc/*/
__pycache__/Python bytecode cacheThroughout
.pytest_cache/Pytest cacheRoot and test dirs
build/Build output directoryRoot
dist/Distribution packagesRoot
*.pycCompiled Python filesThroughout
*.pyoOptimized Python filesThroughout

Cleanup commands:

bash
# 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.

PatternDescription
*.logGeneral log files
*LogFile.txtOrcaFlex log files
*.log.*Rotated log files
debug.logDebug output

Cleanup commands:

bash
# 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.

PatternDescription
*.tmpTemporary files
.temp/Temp directories
cache/Cache directories
*.bakBackup files
*.swpVim swap files
*~Editor backup files

Cleanup commands:

bash
# 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.

PatternDescription
htmlcov/HTML coverage reports
.coverageCoverage data file
.coverage.*Parallel coverage data
coverage.xmlXML coverage report

Cleanup commands:

bash
# Remove coverage artifacts
rm -rf htmlcov/
rm -f .coverage .coverage.* coverage.xml

5. IDE Artifacts

Editor and IDE generated files.

PatternDescription
.idea/PyCharm/IntelliJ
.vscode/VS Code (keep settings.json)
*.code-workspaceVS 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.

PatternDescriptionAction
benchmarks/reports/Timestamped HTML reportsAdd to .gitignore
benchmarks/results/Timestamped CSV/JSONAdd to .gitignore
benchmarks/legacy_projects/Reference test dataMove to tests/fixtures/
benchmarks/*.pyBenchmark scriptsKeep tracked

Cleanup commands:

bash
# 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:

code
root/
├── agents/
├── .agents/
├── agent_configs/
└── .agent-os/

After:

code
.claude/
└── agents/
    ├── core/
    ├── devops/
    └── specialized/

Commands:

bash
# 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:

bash
# 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:

bash
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:

bash
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:

bash
# 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

FolderDescriptionAction
.agent-os/Legacy agent OS frameworkConsolidate to .claude/
.ai/Legacy AI configurationConsolidate to .claude/
.agent-runtime/Runtime symlinks (often dead)Delete if dead links
.common/Orphaned utility scriptsDelete or relocate to scripts/
.specify/Stale specification templatesDelete if unused
.drcode/External tool config (Dr. Code)Keep if actively used
.slash-commands/Command registryKeep

Discovery Commands

bash
# 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

bash
# 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 TypeStrategyExample
Same filenameRename with suffixREADME.md -> README-legacy.md
Similar contentUse subdirectorycommands/ -> commands/legacy-scripts/
Unique contentPreserve in dedicated folderKeep implementation-history/
Clear duplicatesDelete after verificationRemove exact copies

Merge Commands

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
# 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

bash
# 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)

bash
# 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)

bash
# 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

bash
# 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:

gitignore
# 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/ and dist/ removed if present

Log Files

  • *.log files removed or archived
  • *LogFile.txt files removed
  • Rotated logs cleaned

Temp Files

  • *.tmp files removed
  • Editor backup files removed
  • Cache directories cleaned

Coverage Reports

  • htmlcov/ removed
  • .coverage files 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

  • .gitignore updated with new patterns
  • git status shows 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)

FolderReasonVerification
.drcode/Legacy AI config (Dr. Code)Not referenced in any scripts or CI
.benchmarks/Empty benchmark folderls .benchmarks/ returns empty or missing
.agent-runtime/Dead symlinks onlyfind .agent-runtime -type l ! -exec test -e {} \;
.common/Orphaned utilitiesNo imports reference this folder
.specify/Stale specification templatesSpecs moved to specs/templates/

Folders to CONSOLIDATE

SourceDestinationCommand
.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

FolderReason
.githooks/Standard location for git hooks
.github/GitHub workflows and templates
.claude/Authoritative AI configuration
.vscode/Team VS Code settings (if tracked)

Cleanup Commands

bash
# 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

markdown
## 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 to scripts/git/

Best Practices

  1. Always verify before deleting - Use find and ls before rm
  2. Use git rm for tracked files - Preserves history and staging
  3. Update .gitignore first - Prevents re-adding cleaned files
  4. Commit cleanup separately - Keep cleanup commits distinct from feature work
  5. Document what was removed - Use clear commit messages
  6. Check file sizes - Large files may need special handling (Git LFS)

Related Skills

References


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