repo-maintainer

majiayu000 的头像作者 majiayu000

审核杂乱的存储库并将其重组为干净、LLM 友好的结构。它使用非破坏性的“迁移清单”流程来安全地整合脚本、建立文档并创建 AI 上下文区域。

📖 中文导读:审核杂乱的存储库并将其重组为干净、LLM 友好的结构。它使用非破坏性的“迁移清单”流程来安全地整合脚本、建立文档并创建 AI 上下文区域。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: repo-maintainer description: 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.

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