Hidden Folder Audit Skill

Systematic audit and consolidation of hidden (dot) folders in a repository. Identifies duplicate configurations, dead symlinks, orphaned directories, and consolidation opportunities to establish a clean, maintainable folder structure.

Version Metadata

version: 1.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 multiple hidden folders over time
• Multiple AI/agent configuration directories exist (.agent-os/, .ai/, .claude/)
• Symlinks point to non-existent targets
• Unclear which configuration is authoritative
• Preparing for repository restructure or cleanup
• After inheriting or forking a repository
• Before establishing new folder standards

Audit Process

Step 1: Inventory All Hidden Folders

List all hidden directories at the repository root.

# List all hidden directories (excluding .git)
find . -maxdepth 1 -type d -name ".*" ! -name ".git" | sort

# With sizes
du -sh .*/ 2>/dev/null | grep -v "^0" | sort -hr

# Include symlinks
find . -maxdepth 1 \( -type d -o -type l \) -name ".*" ! -name ".git" | sort

Step 2: Check Git Tracking Status

Determine which hidden folders are tracked, ignored, or untracked.

# Check if folder is tracked
git ls-files --error-unmatch .folder/ 2>/dev/null && echo "TRACKED" || echo "NOT TRACKED"

# Check if folder is ignored
git check-ignore -v .folder/ 2>/dev/null && echo "IGNORED" || echo "NOT IGNORED"

# List all tracked hidden files
git ls-files | grep "^\." | cut -d'/' -f1 | sort -u

# List all gitignored hidden folders
git status --porcelain --ignored | grep "^!!" | grep "^\./\." | cut -d'/' -f2 | sort -u

Step 3: Analyze Content Overlap

Check for duplicate or overlapping content between hidden folders.

# Compare agent configurations
diff -rq .agent-os/agents/ .claude/agents/ 2>/dev/null

# Find duplicate files by name
find .agent-os .ai .claude -name "*.md" -type f 2>/dev/null | xargs -I {} basename {} | sort | uniq -d

# Find duplicate files by content (MD5)
find .agent-os .ai .claude -type f 2>/dev/null | xargs md5sum 2>/dev/null | sort | uniq -w32 -d

# Compare directory structures
diff <(find .agent-os -type f | sed 's|.agent-os/||' | sort) \
     <(find .claude -type f | sed 's|.claude/||' | sort) 2>/dev/null

Step 4: Identify Authoritative Source

Determine which folder should be the single source of truth.

Criteria for Authoritative Source:

1. Git tracking - Tracked folders are more likely authoritative
2. Recency - Check last modification dates
3. Completeness - More complete configuration wins
4. Active use - Referenced in CI/CD, scripts, documentation
5. Tool requirements - Some tools require specific folder names

# Check modification times
stat -c '%Y %n' .*/ 2>/dev/null | sort -rn | head -10

# Check for references in scripts and CI
grep -r "\.agent-os" --include="*.sh" --include="*.yml" --include="*.yaml" .
grep -r "\.claude" --include="*.sh" --include="*.yml" --include="*.yaml" .

# Check symlink targets
find . -maxdepth 2 -type l -exec ls -la {} \;

Step 5: Plan Consolidation

Create a migration plan based on analysis.

Migration Checklist:

• [ ] Identify target folder structure
• [ ] List files to migrate
• [ ] Identify files to delete
• [ ] Update references in code/scripts
• [ ] Update .gitignore
• [ ] Test after migration

Common Hidden Folders Reference

Based on actual cleanup sessions, this table provides verified recommendations.

| Folder | Purpose | Action | Notes | |--------|---------|--------|-------| | .claude/ | Claude Code configuration, agents, skills, docs | KEEP | Authoritative for AI tools | | .claude-flow/ | Runtime data, state, coordination | KEEP | Add to .gitignore | | .githooks/ | Git hooks | KEEP | Standard location | | .github/ | GitHub workflows, templates | KEEP | Required by GitHub | | .git/ | Git repository data | NEVER TOUCH | - | | .gitignore | Git ignore patterns | KEEP | Update as needed | | .vscode/ | VS Code settings | KEEP | Team settings if tracked | | .idea/ | JetBrains IDE settings | KEEP | Or add to .gitignore | | .env | Environment variables | KEEP | Must be in .gitignore | | .agent-os/ | Legacy agent OS configuration | CONSOLIDATE | Merge into .claude/ | | .ai/ | Legacy AI configuration | CONSOLIDATE | Merge into .claude/ | | .drcode/ | External tool (Dr. Code) config | DELETE | Legacy AI config, confirmed deletable | | .slash-commands/ | Command registry | CONSOLIDATE | Move to .claude/docs/commands/ | | .git-commands/ | Git helper scripts | CONSOLIDATE | Move to scripts/git/ | | .benchmarks/ | Benchmark data | DELETE | Usually empty, delete if so | | benchmarks/ | Benchmark data and reports | SPLIT | Move fixtures to tests/fixtures/, gitignore reports/results | | .agent-runtime/ | Dead symlinks, orphaned state | DELETE | After verifying dead links | | .common/ | Orphaned utilities | DELETE | Relocate useful scripts first | | .specify/ | Stale specification templates | DELETE | Migrate to specs/templates/ | | .pytest_cache/ | Pytest cache | DELETE | Regenerated automatically | | .ruff_cache/ | Ruff linter cache | DELETE | Regenerated automatically | | .mypy_cache/ | MyPy type checker cache | DELETE | Regenerated automatically | | .coordination/ | Multi-agent coordination | MIGRATE | Move to .claude-flow/ | | .session/ | Session state files | MIGRATE | Move to .claude-flow/ |

Related Directory Patterns

Some non-hidden directories follow similar cleanup/consolidation patterns.

specs/archive/

Standard location for completed specification plans.

# Archive completed plans (check YAML frontmatter for status: completed)
mkdir -p specs/archive
git mv specs/modules/<completed-plan>.md specs/archive/

benchmarks/

Benchmark directories typically contain mixed content requiring separation.

| Subdirectory | Content | Action | |--------------|---------|--------| | legacy_projects/ | Reference test data (*.dat, *.csv) | Move to tests/fixtures/ | | reports/ | Timestamped HTML reports | Add to .gitignore | | results/ | Timestamped CSV/JSON | Add to .gitignore | | Root *.py files | Benchmark scripts | Keep tracked |

# Separate fixtures from generated outputs
mkdir -p tests/fixtures/orcaflex
git mv benchmarks/legacy_projects/* tests/fixtures/orcaflex/
git rm -r --cached benchmarks/reports benchmarks/results
echo "benchmarks/reports/" >> .gitignore
echo "benchmarks/results/" >> .gitignore

Consolidation Commands

Migrate .agent-os to .claude

# Backup first
cp -r .agent-os .agent-os.backup

# Migrate agents
mkdir -p .claude/agents
cp -r .agent-os/agents/* .claude/agents/ 2>/dev/null

# Migrate standards (if applicable)
mkdir -p .claude/standards
cp -r .agent-os/standards/* .claude/standards/ 2>/dev/null

# Update git tracking
git rm -r --cached .agent-os/ 2>/dev/null
git add .claude/

# Remove old folder after verification
rm -rf .agent-os
rm -rf .agent-os.backup  # After confirming migration

Migrate .ai to .claude

# Backup first
cp -r .ai .ai.backup

# Migrate prompts to skills
mkdir -p .claude/skills/prompts
cp -r .ai/prompts/* .claude/skills/prompts/ 2>/dev/null

# Migrate config
cp .ai/config.* .claude/ 2>/dev/null

# Cleanup
git rm -r --cached .ai/ 2>/dev/null
rm -rf .ai

Clean Dead Symlinks

# Find broken symlinks
find . -maxdepth 2 -type l ! -exec test -e {} \; -print

# Remove broken symlinks
find . -maxdepth 2 -type l ! -exec test -e {} \; -delete

# Remove specific dead symlink folder
rm -rf .agent-runtime

Consolidate Runtime Directories

# Create standard runtime directory
mkdir -p .claude-flow/state
mkdir -p .claude-flow/cache
mkdir -p .claude-flow/logs

# Migrate coordination data
mv .coordination/* .claude-flow/state/ 2>/dev/null
mv .session/* .claude-flow/state/ 2>/dev/null

# Remove old directories
rm -rf .coordination .session

Update .gitignore

Add these patterns after consolidation:

# Runtime and state (not tracked)
.claude-flow/
.coordination/
.session/

# Legacy folders (prevent re-creation)
.agent-os/
.ai/
.agent-runtime/

# Cache directories
.pytest_cache/
.ruff_cache/
.mypy_cache/
__pycache__/

Audit Checklist

Pre-Audit

• [ ] Working directory is clean (git status)
• [ ] Create backup branch: git checkout -b backup/pre-hidden-audit
• [ ] Document current state: ls -la .*/ > hidden-folders-before.txt

Discovery Phase

• [ ] List all hidden folders at root level
• [ ] Record size of each hidden folder
• [ ] Identify symlinks and their targets
• [ ] Check git tracking status for each

Analysis Phase

• [ ] Identify duplicate configurations
• [ ] Find broken symlinks
• [ ] Determine authoritative source for each config type
• [ ] Check for active usage in scripts/CI

Planning Phase

• [ ] Create target folder structure diagram
• [ ] List files to migrate with source/destination
• [ ] List files/folders to delete
• [ ] Identify scripts/references to update

Execution Phase

• [ ] Backup folders before migration
• [ ] Migrate content to authoritative locations
• [ ] Update git tracking (git rm --cached, git add)
• [ ] Remove legacy folders
• [ ] Update .gitignore

Verification Phase

• [ ] Run tests to ensure nothing broke
• [ ] Verify symlinks work (if any remain)
• [ ] Confirm scripts still function
• [ ] Check CI/CD pipelines
• [ ] Commit with descriptive message

Documentation Phase

• [ ] Update README if folder structure changed
• [ ] Document new standard in CLAUDE.md or equivalent
• [ ] Remove references to legacy folders in docs

Verification Commands

Use these commands to verify the final state after audit and cleanup.

Verify Hidden Folder State

# List remaining hidden folders (should be minimal)
echo "=== Remaining Hidden Folders ==="
find . -maxdepth 1 -type d -name ".*" ! -name ".git" | sort

# Expected remaining folders:
# .claude/       - AI configuration (authoritative)
# .claude-flow/  - Runtime data (gitignored)
# .github/       - GitHub workflows
# .githooks/     - Git hooks
# .vscode/       - VS Code settings (if tracked)

# Verify no legacy folders remain
echo "=== Checking for Legacy Folders ==="
for dir in .agent-os .ai .drcode .slash-commands .git-commands .benchmarks .agent-runtime .common .specify; do
  if [ -d "$dir" ]; then
    echo "WARNING: $dir still exists!"
  fi
done
echo "Check complete."

Verify Consolidation Targets

# Verify .claude/ structure
echo "=== .claude/ Structure ==="
ls -la .claude/

# Verify scripts/git/ exists if .git-commands was consolidated
echo "=== scripts/git/ ==="
ls -la scripts/git/ 2>/dev/null || echo "scripts/git/ does not exist"

# Verify .claude/docs/commands/ if .slash-commands was consolidated
echo "=== .claude/docs/commands/ ==="
ls -la .claude/docs/commands/ 2>/dev/null || echo ".claude/docs/commands/ does not exist"

# Verify specs/archive exists for completed plans
echo "=== specs/archive/ ==="
ls -la specs/archive/ 2>/dev/null || echo "specs/archive/ does not exist"

# Verify benchmark structure
echo "=== benchmarks/ Structure ==="
ls -la benchmarks/ 2>/dev/null || echo "benchmarks/ does not exist"

# Check for legacy_projects in benchmarks (should be moved)
if [ -d "benchmarks/legacy_projects" ]; then
  echo "[WARN] benchmarks/legacy_projects/ should be moved to tests/fixtures/"
fi

Verify Git Status

# Check for untracked hidden folders
echo "=== Untracked Hidden Folders ==="
git status --porcelain | grep "^??" | grep "^\./\." || echo "None found"

# Verify .gitignore includes runtime folders
echo "=== .gitignore Hidden Folder Entries ==="
grep -E "^\.(claude-flow|coordination|session)" .gitignore || echo "No runtime folders in .gitignore"

# Count tracked files in .claude/
echo "=== .claude/ Tracked Files ==="
git ls-files .claude/ | wc -l

Final State Checklist

# Run all verification checks
echo "=== Final State Verification ==="

# 1. Only expected hidden folders exist
hidden_count=$(find . -maxdepth 1 -type d -name ".*" ! -name ".git" ! -name ".claude" ! -name ".claude-flow" ! -name ".github" ! -name ".githooks" ! -name ".vscode" | wc -l)
if [ "$hidden_count" -eq 0 ]; then
  echo "[OK] No unexpected hidden folders"
else
  echo "[WARN] $hidden_count unexpected hidden folders found"
fi

# 2. Legacy folders are gone
legacy_count=0
for dir in .agent-os .ai .drcode .slash-commands .git-commands .benchmarks; do
  [ -d "$dir" ] && legacy_count=$((legacy_count + 1))
done
if [ "$legacy_count" -eq 0 ]; then
  echo "[OK] All legacy folders removed"
else
  echo "[WARN] $legacy_count legacy folders remain"
fi

# 3. .claude/ has expected subdirectories
for subdir in agents docs skills; do
  if [ -d ".claude/$subdir" ]; then
    echo "[OK] .claude/$subdir exists"
  else
    echo "[WARN] .claude/$subdir missing"
  fi
done

# 4. Git working directory is clean
if git diff --quiet 2>/dev/null; then
  echo "[OK] Git working directory is clean"
else
  echo "[INFO] Git has uncommitted changes"
fi

Best Practices

1. Always backup before deleting - Create a backup branch or copy
2. Use git rm for tracked folders - Preserves history
3. Check symlink targets before deleting - May need to update references
4. Update .gitignore first - Prevents accidental re-tracking
5. Test after consolidation - Ensure nothing broke
6. Commit in logical chunks - Separate migration from cleanup
7. Document the changes - Future maintainers will thank you

Related Skills

• repo-cleanup - General repository cleanup
• module-based-refactor - For source code restructuring
• session-start-routine - Session initialization

References

• Git ls-files documentation: https://git-scm.com/docs/git-ls-files
• Git check-ignore documentation: https://git-scm.com/docs/git-check-ignore
• Symbolic links in Git: https://git-scm.com/book/en/v2/Git-Internals-Git-References

---

Version History

• 1.2.0 (2026-01-20): Added Related Directory Patterns section
  • Added benchmarks/ entry to reference table (SPLIT action)
  • Added Related Directory Patterns section for non-hidden directories
  • Added specs/archive/ as standard location for completed plans
  • Added benchmarks/ separation pattern (fixtures vs generated outputs)
  • Updated verification commands for new patterns
• 1.1.0 (2026-01-20): Updated reference table and added verification commands
  • Updated Common Hidden Folders Reference table with verified recommendations
  • Added .drcode/ as DELETE (confirmed legacy AI config)
  • Added .slash-commands/ as CONSOLIDATE to .claude/docs/commands/
  • Added .git-commands/ as CONSOLIDATE to scripts/git/
  • Added .benchmarks/ as DELETE (usually empty)
  • Added .githooks/ as KEEP (standard location)
  • Added Verification Commands section with:
    • Verify Hidden Folder State commands
    • Verify Consolidation Targets commands
    • Verify Git Status commands
    • Final State Checklist script
  • Added Notes column to reference table for additional context
• 1.0.0 (2025-01-20): Initial release based on digitalmodel repository hidden folder audit session