pdf-organizer

PDF Organizer

Positioning

This skill handles the problem of "inconsistency between PDF files and legal document logic." It focuses not on ordinary file concatenation, but on organizing PDFs by document content into files that lawyers would actually use.

Core responsibilities:

1. Split an entire scanned/OCR PDF into multiple independent documents by content.
2. Merge the same document that has been split apart back into one PDF by content.
3. For PDFs that do not need splitting or merging, directly standardize naming based on content recognition results.
4. Generate standardized file names based on elements such as title, subject, opposing party, cause of action, and date.
5. Generate a page-level inspection index and manifest draft for AI/manual review.
6. Use page reference sets to uniformly express splitting, duplication, merging, and cross-source assembly, and audit page coverage (orphan pages/duplicate reference pages) before execution.
7. Generate downstream handoff.json, with page-level source references, for coordinated use by Skills such as case material organization, contract review, and litigation analysis.
8. Perform lightweight page orientation processing before and after organization, such as 90/180/270 degree rotation; skew correction is available as an optional preprocessing capability.
9. Standardize each PDF page to A4 size: landscape pages automatically fit A4 landscape (842×595 pt), portrait pages automatically fit A4 portrait (595×842 pt), scaled proportionally and centered.

This skill does not do OCR, does not compress PDFs, and does not replace overall case material classification. If the PDF does not yet have a searchable text layer, use an OCR tool first; if complex cropping, compression, batch OCR, or high-quality image preprocessing is needed, prefer PDF Processor.

Coordination with other skills

• Work such as OCR preprocessing, double-layer PDFs, compression, and complex cropping is left to PDF Processor.
• For complex layout recognition, PDF-to-Markdown conversion, or when structured OCR results are needed, use an OCR parsing tool first.
• The organized PDFs output by this skill can continue to be passed to material organization, case analysis, or document generation skills.

Dependencies

System dependencies

Dependency	Installation method
python3	macOS usually has it built in
ocrmypdf	Optional, only deskew required for skew correction; macOS: brew install ocrmypdf

Python packages

Package name	Purpose	Installation command
pypdf	Splitting, merging, duplication, page rotation	python3 -m pip install -r scripts/requirements.txt

Dependencies do not need to be installed when only doing checklist planning; when executing splitting, merging, or rotation, pypdfis required. Skew correction depends on the ocrmypdf command-line tool; if it is not installed, the user should be prompted to use PDF Processor instead or install it first.

Input/Output

Input

• Entire OCR'd PDF: for example, a 16-page scanned combined file.
• Multiple PDFs that have already been split apart: for example, the same complaint split into 第 1-2 页.pdf、第 3-4 页.pdf。
• Independent PDF file: the entire PDF is already a complete document, does not need splitting or merging, and only needs standardized naming based on content.
• Optional OCR Markdown or text fragments: used to assist in determining titles, boundaries, and merge relationships.
• Optional naming preferences: whether to retain the date, whether to include the cause of action, and whether to use abbreviations.

Output

• Organized PDF files. By default, only the final PDFs are placed in the delivery directory.
• Process files are uniformly archived to archive/YYYYMMDD_HHMMSS_{来源名}/。

The archive contains by default:

• organize_manifest.input.json: a copy of the input list for this run.
• organize_manifest.resolved.json: actual output paths, page numbers, status, and naming basis.
• organize_report.md: a summary report for manual review.
• handoff.json: a handoff file for downstream Skills.
• run_meta.json: run metadata.

Workflow

1. Inventory and preprocessing assessment

1. Confirm whether the input is a whole PDF, multiple fragment PDFs, a standalone PDF file (only needs renaming), or a mix of the above.
2. Read the page count and establish the correspondence between page numbers and files.
3. Perform text layer detection first to confirm whether the PDF is an OCR-generated double-layer PDF. If there is no searchable text layer, stop the content splitting/merging assessment and prompt the user to first run PDF Processor to generate a double-layer PDF.
4. Run page inspection to extract the text volume, suspected titles, page numbers, dates, subject candidates, and boundary signals for each page.
5. You may first generate a organize_manifest.json draft, and then have AI review it based on page evidence and naming rules.
6. Determine whether page orientation processing is needed first:
   • The overall page orientation is wrong: use 90/180/270 degree rotation.
   • Slight skew affects reading or OCR: you may use deskew, but complex image issues should preferably be handed to PDF Processor.
7. Do not modify the original files. Final PDFs are written to the output directory, and the manifest, report, handoff file, and run record are written to the Skill archive.

2. Determine whether to split or merge

Splitting scenarios：

• One PDF contains multiple documents.
• A new document title appears at the top of a page.
• The page numbering restarts from "Page 1 of N" or 1/N .
• A new signature block, letter number, case number, receiving court, contract number, or signature page appears.
• The layout switches from a continuation page of the main text to a new form, cover page, or attachment.

Merging scenarios：

• Multiple PDFs are consecutive pages of the same document.
• The titles are the same and the page numbers are consecutive, for example Page 1 of 2, Page 2 of 2.
• The latter file is clearly a continuation page, signature page, payment page, or attachment page of the previous file.
• The filename is merely a mechanical page number and cannot represent an independent document.

Renaming scenarios：

• The whole PDF is one complete document, and neither splitting nor merging is needed.
• The current filename contains only a page number, date, or scanner default name and cannot reflect the document content.
• In the manifest, use input_file to specify the source, and use suggested_filename to provide the standardized filename.
• If rotation or skew correction is also needed, you can add rotate or deskew。

If the boundary is uncertain, do not force a merge or split; mark needs_review: truein the manifest, and retain a page number hint in the filename.

For detailed identification rules for common legal documents, see references/recognition-rules.md。

3. Naming rules

Default filename format:

文书名称 关键主体 补充区分.pdf

Rules:

1. By default, do not add sequence numbers; add sequence numbers only when the user explicitly requests sort numbering, or when files with the same name cannot be distinguished by content.
2. For the document name, prefer using the title on the first page; do not use temporary names such as "pages 1-2".
3. For key parties, prefer writing the client/principal, the opposing party, and the cause of action/legal relationship.
4. Our law firm, handling lawyer, and common issuing institutions are usually not written into the file name, because this information is already known and repetitive for the user.
5. When the date can be reliably identified, use YYYYMMDD; when the date is missing or OCR is questionable, omit it.
6. By default, file names are separated internally by spaces, not underscores.
7. Files with the same name are automatically appended by the script with 1、 2, without overwriting existing files.
8. Low-confidence files use 待确认 页码.pdf or 疑似文书名称 页码.pdf。

Example:

专项法律服务合同 北京青柏教育咨询有限公司.pdf
委托代理合同 张家宁与杭州叠影科技有限公司 著作权权属侵权纠纷.pdf
授权委托书 张家宁.pdf
律师事务所函 张家宁诉杭州叠影科技有限公司.pdf
民事起诉状 张家宁诉杭州叠影科技有限公司 普通版.pdf
民事起诉状 张家宁诉杭州叠影科技有限公司 要素式.pdf

Manifest

Before execution, first generate organize_manifest.json. For field descriptions, see references/organize-manifest-schema.md。

All segments are compiled before execution into a page reference set of "file + page number": splitting, copying, merging, and cross-source assembly are all just reference operations. The manifest is the reference table, and the physical PDF does not move a single byte before execution is confirmed. The executor only consumes the reference table; whole-file single-source segments retain byte-level copying.

Splitting example

{
  "source_pdf": "/path/to/ocr.pdf",
  "output_dir": "/path/to/output",
  "segments": [
    {
      "id": "D001",
      "pages": "1-2",
      "suggested_filename": "专项法律服务合同 北京青柏教育咨询有限公司.pdf",
      "title": "专项法律服务合同",
      "confidence": "high",
      "needs_review": false,
      "evidence": "第 1 页标题为专项法律服务合同，页脚显示第1页共2页。"
    }
  ]
}

Merging example

{
  "output_dir": "/path/to/output",
  "segments": [
    {
      "id": "D001",
      "source_items": [
        {"file": "/path/to/起诉状 第1-2页.pdf"},
        {"file": "/path/to/起诉状 第3-4页.pdf"}
      ],
      "suggested_filename": "民事起诉状 张家宁诉杭州叠影科技有限公司 普通版.pdf",
      "title": "民事起诉状",
      "confidence": "high",
      "needs_review": false,
      "evidence": "两份 PDF 标题一致且页码连续，第二份为同一份起诉状续页。"
    }
  ]
}

Cross-source page reference assembly example

To assemble a new material (such as a combined evidence volume) from several pages taken from multiple source PDFs, use the refs field:

{
  "output_dir": "/path/to/output",
  "segments": [
    {
      "id": "D001",
      "refs": [
        {"file": "/path/to/起诉状.pdf", "pages": "5"},
        {"file": "/path/to/证据卷.pdf", "pages": "1-3"},
        {"file": "/path/to/补充说明.pdf"}
      ],
      "suggested_filename": "证据组合 原告提交.pdf",
      "confidence": "medium",
      "needs_review": true,
      "evidence": "起诉状第5页列明的证据与证据卷第1-3页对应。"
    }
  ]
}

refs Assemble in array order; each item's pages may be omitted (defaults to the entire document). A segment's effective id must be unique; when omitted, generate D001、D002 , etc., and explicit numbering must not conflict with these defaults.

Direction handling example

{
  "output_dir": "/path/to/output",
  "segments": [
    {
      "id": "D001",
      "input_file": "/path/to/横向扫描.pdf",
      "rotate": 90,
      "suggested_filename": "授权委托书 张家宁.pdf",
      "confidence": "medium",
      "needs_review": true
    }
  ]
}

Renaming example

When no splitting or merging is needed, simply standardize the name based on the content recognition result:

{
  "output_dir": "/path/to/output",
  "segments": [
    {
      "id": "D001",
      "input_file": "/path/to/scan_20260531_001.pdf",
      "suggested_filename": "民事起诉状 张家宁诉杭州叠影科技有限公司 普通版.pdf",
      "title": "民事起诉状",
      "document_type": "民事起诉状",
      "confidence": "high",
      "needs_review": false,
      "evidence": "首页标题为民事起诉状，正文提及张家宁与杭州叠影科技有限公司著作权权属侵权纠纷。"
    },
    {
      "id": "D002",
      "input_file": "/path/to/scan_20260531_002.pdf",
      "suggested_filename": "授权委托书 张家宁.pdf",
      "title": "授权委托书",
      "document_type": "授权委托书",
      "confidence": "high",
      "needs_review": false,
      "evidence": "首页标题为授权委托书，委托人张家宁。"
    }
  ]
}

Execution script

When executing splitting, merging, or rotation for the first time, install dependencies first:

python3 -m pip install -r scripts/requirements.txt

Preview plan:

python3 scripts/pdf_organizer.py --manifest organize_manifest.json --dry-run

Only perform page reference compilation and coverage audit (without writing any PDF), checking whether files exist, out-of-range page numbers, orphan pages, and duplicate reference pages:

python3 scripts/pdf_organizer.py --validate-manifest organize_manifest.json

Coverage audit mode (off / warn / strict): default is warn(orphan page/duplicate reference page alerts do not block);strict when set, finding orphan pages or duplicate reference pages terminates directly, and not a single PDF is written. It can be specified via command line --coverage-check strict or manifest top-level "coverage_check": "strict" :

python3 scripts/pdf_organizer.py --manifest organize_manifest.json --coverage-check strict

When splitting an entire scanned document, strictis recommended: after the complete reference table is successfully compiled, it checks whether every page of the referenced sources is referenced exactly once, avoiding missing pages or over-splitting. Duplicate effective IDs, segment compilation failures, coverage anomalies, or audit anomalies are all blocked before writing PDFs; standalone validation also returns a non-zero exit code when it encounters an audit anomaly.

This is a pre-execution check, not a whole-batch transaction:warn / off mode retains per-segment processing; when a segment fails, previously successful files may already have been written out; in all modes, files may also be left behind when subsequent writing, rotation, or skew correction fails, and a non-zero exit code does not mean the output directory is empty. Before delivery, you must verify the resolved manifest's per-segment status, the actual files, and the report; failed segments must not be treated as completed. For details, see Checklist contract and regression boundaries。

Only detect whether a PDF has a searchable text layer:

python3 scripts/pdf_organizer.py --check-text-layer "/path/to/file.pdf"

Generate a page inspection index:

python3 scripts/pdf_organizer.py \
  --inspect "/path/to/ocr.pdf" \
  --inspect-output "/path/to/page_inspection.json"

Generate a manifest draft:

python3 scripts/pdf_organizer.py \
  --suggest-manifest "/path/to/ocr.pdf" \
  --output-dir "/path/to/organized" \
  --manifest-output "/path/to/organize_manifest.json"

A4 standardization

Standardize each page of one or more PDFs to A4 size: landscape pages -> A4 landscape, portrait pages -> A4 portrait:

# 原地覆盖
python3 scripts/pdf_organizer.py --normalize-a4 file1.pdf file2.pdf

# 输出到指定目录
python3 scripts/pdf_organizer.py --normalize-a4 file1.pdf file2.pdf --normalize-output-dir /path/to/output

The draft serves only as a starting point for review. The script conservatively uses 待确认; do not skip manual/AI review and execute directly.

Execute after confirmation:

python3 scripts/pdf_organizer.py --manifest organize_manifest.json

Common override parameters:

python3 scripts/pdf_organizer.py \
  --manifest organize_manifest.json \
  --source "/path/to/ocr.pdf" \
  --output-dir "/path/to/organized" \
  --archive-root "/path/to/archive-root"

The script detects the source PDF's text layer in strict mode by default; when no searchable text layer is detected, it stops execution. Only in scenarios that do not depend on content judgment, such as pure rotation or copying, may you set "text_check": "off" in the manifest or use it on the command line --text-check off。

The script only writes the final PDF to the output directory and does not modify the source PDF; the manifest, resolved JSON, report,handoff.json and metadata are written to the archive.

Downstream handoff

Each formal execution generates in the archive handoff.json. Downstream Skills should preferentially read this file rather than guessing the filename and document type again.

The source array is ordered by output page order, merging only consecutive groups of same-source pages; the same file may appear repeatedly in the list, and downstream must not regroup, reorder, or deduplicate by filename.pages remains an integer array type, containing the original order and duplicate pages.

Each output document carries page-level provenance:source_refs(normalized page reference [{file, pages}]) and source_refs_label(human-readable labels such as 起诉状.pdf P5 + 证据卷.pdf P1-3), so downstream can trace any key information back to the specific source page.

suggested_downstream routing labels are given by document category, not bound to specific Skill names:

• Contracts, agreements → 合同审查。
• Complaints, judgments, rulings, statements of defense, applications, evidence lists, court hearing transcripts → 诉讼分析。
• Powers of attorney, law firm letters, and other auxiliary materials → 材料整理。
• Low confidence or requiring review → return to this Skill for review.
• Those not matching the above categories → 材料整理。

Which Skill specifically consumes it is decided by downstream based on the currently available Skills and case context.

Delivery check

After completion, check:

1. The number of output PDFs matches the number of manifest segments.
2. The page count of split files corresponds to pages ; the page count of merged files equals the sum of source pages.
3. The coverage audit has no unexplained orphan pages or duplicate reference pages; if there are any, explain missing pages, over-splitting, or intentional reuse to the user.
4. In the archive, organize_report.md has no low and no unprocessed items of needs_review: true ; if there are any, clearly prompt the user for manual review.
5. The original PDF and original fragment PDFs have not been overwritten or moved.
6. The naming basis can be traced back to OCR text or page content, without speculated dates, case numbers, or parties.