Repo Maintenance

---
name: repo-maintenance
description: "Guide safe Docling repository edits across package layout, extras,
  CLI docs, examples, validation, tests, and maintenance scripts."
disable-model-invocation: true
metadata:
  disco-role: operating
license: MIT
---

# Repo Maintenance

Use this sub-skill when modifying the Docling repository itself: package metadata, extras, CLI entry points, generated docs/examples, tests, CI-aligned checks, AGENTS guidance, Makefile commands, Tach boundaries, or maintenance scripts.

Do not use this sub-skill for ordinary document conversion, output export, pipeline tuning, remote service usage, extraction, chunking, ASR, VLM, or end-user CLI recipes. Route those requests to the user-facing Docling sub-skills instead.

## Fast Routing

- Start from `AGENTS.md` guidance: keep edits scoped, public APIs typed for Python `>=3.10,<4`, prefer `Path`, avoid broad attribute probing, and add focused tests only for meaningful behavior changes.
- Treat `docling-slim` as the source package that ships the `docling/` module plus `docling` and `docling-tools` CLI entry points; treat `docling` as the full dependency meta-package that re-declares the same scripts for tool installation.
- Use `make check` for read-only local checks and `make validate` before completion; rerun `make validate` if hooks mutate files.
- Run `make docs-render` after CLI or example notebook changes, and `make docs-build` when docs site integration matters.
- Use targeted `uv run pytest ...` first, then broader checks as confidence increases; regenerate reference data only when output changes are intentional.

## References

- `references/package-layout.md`: package split, extras mapping, CLI entry point ownership, dependency drift checks, and collision hazards.
- `references/maintainer-workflows.md`: contributor workflows for CLI flag changes, backend edits, docs/examples generation, tests, validation, CI, and source-script inventory.
- `references/troubleshooting.md`: common repository maintenance failures and focused recovery steps.
- `scripts/check_max_lines.py`: bundled safe equivalent of the repository line-limit guard; run from a checkout root with `python scripts/check_max_lines.py` or pass explicit files.

## Contributor Safety

- Keep runtime skill content self-contained; do not require future agents to open local source paths.
- Do not add new optional dependencies without updating the relevant slim extras, full-package re-export extras when applicable, tests, and docs/CLI guidance.
- Avoid growing accepted long-file debt; split new code or update ignore patterns only with a deliberate reason.
- When changing conversion behavior, prefer focused tests such as backend-specific tests, CLI tests, service client tests, or API smoke tests rather than broad snapshot churn.