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:

• 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

.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