repo-maintainer
审核杂乱的存储库并将其重组为干净、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.pyto generate a draft manifest. - Identify the "blood flow" (dependencies): Does
main.pyimport 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.pyto 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/)
- Core: Application logic (
- 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 mvto 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.mdto.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