Add prek hook to enforce 500-line limit on AGENTS.md and SKILL.md files (#1849)

Copilot · nathanjmcdougall · web-flow · commit 38f466fbfa49 · 2026-04-07T20:24:32.000+12:00
* Initial plan * Add check-agent-file-sizes prek hook to enforce 500-line limit Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/1f0d7bd9-4f6e-4bd9-950a-a557a5082300 Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -68,6 +68,17 @@ repos:
         priority: 0
   - repo: local
     hooks:
+      - id: check-agent-file-sizes
+        name: check-agent-file-sizes
+        entry: uv run --frozen --offline hooks/check-agent-file-sizes.py
+        args:
+          - "--agents-file=AGENTS.md"
+          - "--skills-dir=.agents/skills"
+          - "--max-lines=500"
+        language: system
+        always_run: true
+        pass_filenames: false
+        priority: 0
       - id: check-skills-documented
         name: check-skills-documented
         entry: uv run --frozen --offline hooks/check-skills-documented.py
diff --git a/hooks/check-agent-file-sizes.py b/hooks/check-agent-file-sizes.py
@@ -0,0 +1,83 @@
+"""Check that AGENTS.md and all SKILL.md files do not exceed the line limit.
+
+Scans the AGENTS.md file and all SKILL.md files in the skills directory to
+ensure no file exceeds the maximum number of lines. When a violation is found,
+instructions are printed explaining how to reduce the file size.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Check that agent files do not exceed the line limit.",
+    )
+    parser.add_argument(
+        "--agents-file",
+        required=True,
+        help="Path to the AGENTS.md file.",
+    )
+    parser.add_argument(
+        "--skills-dir",
+        required=True,
+        help="Path to the skills directory containing subdirectories with SKILL.md files.",
+    )
+    parser.add_argument(
+        "--max-lines",
+        type=int,
+        default=500,
+        help="Maximum number of lines allowed per file (default: 500).",
+    )
+    args = parser.parse_args()
+
+    agents_file = Path(args.agents_file)
+    skills_dir = Path(args.skills_dir)
+    max_lines: int = args.max_lines
+
+    if not agents_file.is_file():
+        print(f"ERROR: {agents_file} not found.")
+        return 1
+
+    if not skills_dir.is_dir():
+        print(f"ERROR: {skills_dir} is not a directory.")
+        return 1
+
+    violations: list[tuple[Path, int]] = []
+
+    agents_line_count = _count_lines(agents_file)
+    if agents_line_count > max_lines:
+        violations.append((agents_file, agents_line_count))
+
+    for skill_file in sorted(skills_dir.glob("*/SKILL.md")):
+        line_count = _count_lines(skill_file)
+        if line_count > max_lines:
+            violations.append((skill_file, line_count))
+
+    if violations:
+        print(f"ERROR: The following agent files exceed the {max_lines}-line limit:")
+        for path, count in violations:
+            print(f"  {path}: {count} lines (limit: {max_lines})")
+        print()
+        print("To fix these violations:")
+        print(
+            "  - For SKILL.md files: split the skill into sub-skills, each in its own"
+            " subdirectory under .agents/skills/."
+        )
+        print(
+            "  - For AGENTS.md: move general instructions into separate files referenced"
+            " from AGENTS.md."
+        )
+        return 1
+
+    return 0
+
+
+def _count_lines(path: Path) -> int:
+    return len(path.read_text(encoding="utf-8").splitlines())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
