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:

Git tracking - Tracked folders are more likely authoritative
Recency - Check last modification dates
Completeness - More complete configuration wins
Active use - Referenced in CI/CD, scripts, documentation
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:

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

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

# Migrate coordination data

# Remove old directories
rm -rf .coordination .session

Update .gitignore

Add these patterns after consolidation:

# Runtime and state (not tracked)
.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)
# .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 ==="

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

Always backup before deleting - Create a backup branch or copy
Use git rm for tracked folders - Preserves history
Check symlink targets before deleting - May need to update references
Update .gitignore first - Prevents accidental re-tracking
Test after consolidation - Ensure nothing broke
Commit in logical chunks - Separate migration from cleanup
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

hidden-folder-audit