Stats
Actions
Tags
From agent-almanac
Organizes project files into conventional directories, updates stale READMEs, cleans configuration drift, and archives deprecated items without changing code logic.
How this skill is triggered — by the user, by Claude, or both
Slash command
/agent-almanac:tidy-project-structureThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill when project organization has drifted from conventions:
Use this skill when project organization has drifted from conventions:
Do NOT use for code refactoring or dependency restructuring. This skill focuses on file organization and documentation hygiene.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_path | string | Yes | Absolute path to project root |
conventions | string | No | Path to style guide (e.g., docs/conventions.md) |
archive_mode | enum | No | move (default) or delete for deprecated files |
readme_update | boolean | No | Update stale READMEs (default: true) |
Compare current structure against project conventions or language best practices.
Common conventions by language:
JavaScript/TypeScript:
src/ # Source code
tests/ # Test files
dist/ # Build output (gitignored)
docs/ # Documentation
.github/ # CI/CD workflows
Python:
package_name/ # Package code
tests/ # Test suite
docs/ # Sphinx docs
scripts/ # Utility scripts
R:
R/ # R source
tests/testthat/ # Test suite
man/ # Documentation (generated)
vignettes/ # Long-form guides
inst/ # Installed files
data/ # Package data
Rust:
src/ # Source code
tests/ # Integration tests
benches/ # Benchmarks
examples/ # Usage examples
Expected: List of files/directories violating conventions saved to structure_audit.txt
On failure: If no conventions documented, use language-standard defaults
Relocate files to their conventional directories.
Common moves:
tests/ → move to tests/docs/ → move to docs/src/ → delete (should be gitignored)config/ or .config/For each move:
# Check if file is referenced anywhere
grep -r "filename" .
# If no references or only relative path references:
mkdir -p target_directory/
git mv source/file target_directory/file
# Update any imports/requires
# (language-specific — see repair-broken-references skill)
Expected: All files in conventional locations; git history preserved via git mv
On failure: If moving breaks imports, update import paths or escalate
Identify stale information in all README files.
Staleness indicators:
# Find all READMEs
find . -name "README.md" -o -name "readme.md"
# For each README:
# - Check last modified date
git log -1 --format="%ci" README.md
# - Check for broken links
markdown-link-check README.md
# - Verify example code still runs (sample first example)
Expected: List of stale READMEs in readme_freshness.txt with specific issues
On failure: If markdown-link-check unavailable, manually review external links
Fix broken links, update examples, add missing sections.
Standard fixes:
README template structure:
# Project Name
Brief description (1-2 sentences).
## Installation
```bash
# Language-specific install command
# Basic example
Link to full docs.
Link to CONTRIBUTING.md or inline guidelines.
LICENSE badge and link.
**Expected:** All READMEs updated; examples verified to run
**On failure:** If example code cannot be verified, mark with warning comment
### Step 5: Review Config Files
Identify configuration drift and consolidate duplicate settings.
**Common config issues**:
1. Multiple `.env` files (`.env`, `.env.local`, `.env.dev`, `.env.prod`)
2. Duplicate settings across config files
3. Hardcoded secrets (should use environment variables)
4. Outdated API endpoints or feature flags
```bash
# Find all config files
find . -name "*.config.*" -o -name ".env*" -o -name "*.yml" -o -name "*.yaml"
# For each config:
# - Check for duplicate keys
# - Grep for hardcoded secrets (API keys, tokens, passwords)
grep -E "(api[_-]?key|token|password|secret)" config_file
# - Compare dev vs prod settings
diff .env.dev .env.prod
Expected: Config drift documented in config_review.txt; secrets flagged for escalation
On failure: If diff shows major divergence, escalate to devops-engineer
Move or delete files no longer needed.
Candidates for archiving:
nginx.conf.old)file.bak, file~)Archive process:
# Create archive directory (if archive_mode=move)
mkdir -p archive/YYYY-MM-DD/
# For each deprecated file:
# 1. Verify not referenced anywhere
grep -r "filename" .
# 2. Check git history for last modification
git log -1 --format="%ci" filename
# 3. If not modified in >1 year and no references:
if [ "$archive_mode" = "move" ]; then
git mv filename archive/YYYY-MM-DD/
else
git rm filename
fi
# 4. Document in ARCHIVE_LOG.md
echo "- filename (reason, last modified: DATE)" >> ARCHIVE_LOG.md
Expected: Deprecated files archived; ARCHIVE_LOG.md updated
On failure: If uncertain whether file is deprecated, leave in place and document in report
Check for inconsistent file naming across project.
Common conventions:
my-file.js (common in JS/web projects)my_file.py (Python standard)MyComponent.tsx (React components)myUtility.js (JavaScript functions)# Find files violating conventions
# Example: Python project expecting snake_case
find . -name "*.py" | grep -v "__pycache__" | grep -E "[A-Z-]"
# For each violation, either:
# 1. Rename to match conventions
# 2. Document exception (e.g., Django settings.py convention)
Expected: All files follow naming conventions or exceptions documented
On failure: If renaming breaks imports, update references or escalate
Document all structural changes.
# Project Structure Tidying Report
**Date**: YYYY-MM-DD
**Project**: <project_name>
## Directory Changes
- Moved X files to conventional directories
- Created Y new directories
- Archived Z deprecated files
## README Updates
- Updated W stale READMEs
- Fixed X broken links
- Verified Y code examples
## Config Cleanup
- Consolidated X duplicate settings
- Flagged Y hardcoded secrets for removal
- Documented Z config drift issues
## Files Archived
See ARCHIVE_LOG.md for full list (Z files).
## Naming Convention Fixes
- Renamed X files to match conventions
- Documented Y exceptions
## Escalations
- [Config drift requiring devops review]
- [Hardcoded secrets requiring security audit]
Expected: Report saved to TIDYING_REPORT.md
On failure: (N/A — generate report regardless)
After tidying:
git mv, not mv)Breaking Relative Imports: Moving files breaks relative import paths. Update all references or use absolute imports.
Losing Git History: Using mv instead of git mv loses file history. Always use git commands for moves.
Over-Organizing: Creating too many nested directories makes navigation harder. Keep it flat until complexity requires structure.
Deleting Instead of Archiving: Direct deletion loses ability to recover. Always archive first unless certain.
Ignoring Language Conventions: Imposing personal preferences over language standards. Follow established conventions.
Not Updating Documentation: Moving files without updating README paths leaves docs broken.
npx claudepluginhub pjt222/agent-almanacDetects repository directory conventions, audits file placement, and moves files with import-path updates. Never changes code inside files.
Safely scans, previews, and reorganizes project structure with read-only analysis, dry-runs, user confirmations, and protections for git, node_modules, secrets, and builds.
Optimizes project structure, config files, and tools to make productive actions obvious and errors invisible. Use for project setup, codebase audits, or reducing dev workflow friction.