repo-maintainer

majiayu000's avatarfrom majiayu000

Audits and reorganizes messy repositories into clean, LLM-friendly structures. It uses a non-destructive "Migration Manifest" process to safely consolidate scripts, establish documentation, and create AI context zones.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Developer Tools]

When & Why to Use This Skill

The Repository Maintainer skill is an automated solution designed to audit and reorganize disorganized codebases into clean, structured, and LLM-friendly repositories. By utilizing a non-destructive 'Migration Manifest' process, it safely relocates files, preserves Git history, and establishes dedicated AI context zones to enhance the performance of AI agents and developers working within the codebase.

Use Cases

  • Case 1: Cleaning up 'polluted' root directories by automatically categorizing and moving orphan scripts, configs, and assets into a standardized folder structure.
  • Case 2: Preparing legacy codebases for AI-assisted development by generating .ai/ context maps that help LLMs understand architecture and business logic.
  • Case 3: Safely refactoring repository structures using a reversible manifest-driven approach that ensures no files are lost and Git history remains intact.
  • Case 4: Standardizing documentation and knowledge management by consolidating scattered docs into a centralized, searchable directory.
namerepo-maintainer
descriptionAudits and reorganizes messy repositories into clean, LLM-friendly structures. It uses a non-destructive "Migration Manifest" process to safely consolidate scripts, establish documentation, and create AI context zones.

Repository Maintainer

Overview

This skill turns disorganized codebases ("polluted roots," "orphan scripts") into structured, readable repositories. It prioritizes LLM-Readability (creating explicit context maps) and Safety (using a reversible migration manifest).

Use this skill when:

  • A repository has too many files in the root directory.
  • Documentation is missing, outdated, or scattered.
  • An LLM struggles to find relevant context due to noise.
  • You need to "refactor" the file structure without breaking git history.

Workflow

1. The Audit (Discovery)

First, analyze the repository to understand "Hot" (frequently changed) vs "Cold" (stale) zones.

  • Run scripts/scaffold_manifest.py to generate a draft manifest.
  • Identify the "blood flow" (dependencies): Does main.py import that messy script?
  • Output: A mental model of the current chaos.

2. The Manifest (Planning)

Do not move files immediately. Create a migration_manifest.yaml that defines the desired state.

  • Run scripts/scaffold_manifest.py to generate a draft manifest if you haven't already.
  • Categorize files into:
    • Core: Application logic (src/)
    • Scaffolding: Configs (.env, docker-compose)
    • Artifacts: One-off scripts (Move to archive/)
    • Knowledge: Docs (Move to docs/)
  • Review the YAML file. It is the "Contract of Changes."

3. Execution (Safe Move)

Apply the changes using the manifest.

  • Run scripts/apply_migration.py.
  • Safety Rule: This script uses git mv to preserve history.
  • Quarantine: Unknown scripts go to archive/quarantine/ rather than being deleted.

4. LLM Optimization (Contextualizing)

Once files are moved, establish the .ai/ directory.

  • Copy assets/CONTEXT_TEMPLATE.md to .ai/CONTEXT.md.
  • Fill it with a high-level summary of the architecture.
  • This ensures future agents understand why the code exists, not just what it does.

Directory Structure Standards

When planning the migration, aim for this specific structure (The "LLM-First" Architecture):

/ (Root)
├── .ai/                 # Context specifically for LLMs
│   ├── CONTEXT.md       # Architecture & Business Logic
│   └── GUIDELINES.md    # Coding standards
├── src/                 # Source code
├── scripts/             # DevOps/Maintenance scripts
├── docs/                # Human documentation
├── archive/             # Deprecated/Quarantine
└── README.md            # The Map