latex-layout-issue-bundler
GitHub从PDF页面生成可复现的LaTeX布局问题包，包含截图、源码片段和编译日志。用于避免手动截图，为AI助手提供精确的排版调试上下文。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill latex-layout-issue-bundler -g -y
SKILL.md
Frontmatter
{
"name": "latex-layout-issue-bundler",
"description": "Create repo-local LaTeX layout issue bundles from a PDF page, crop, source snippet, and compile log. Use when the user wants to avoid manual PDF screenshots, capture page-specific layout problems, or hand Codex\/Claude Code a reproducible paper layout debugging artifact.",
"allowed-tools": "Read, Write, Edit, Bash, Glob"
}
LaTeX Layout Issue Bundler
Create a reproducible layout issue bundle instead of relying on one-off manual screenshots.
Use this skill when:
- the user has a rendered PDF page with a layout problem
- a screenshot would normally be sent to the agent
- the issue is page/object specific: float gaps, awkward page breaks, algorithm/table/figure placement, overfull/underfull lines, short lines, or local spacing
- the agent needs enough artifact context to debug layout without seeing the full conversation
This skill produces evidence for another skill to consume; it does not directly fix the paper.
Output Shape
Bundles live under the paper repo:
.agent/layout-issues/<issue-id>/
├── prompt.md
├── manifest.json
├── page-<NN>.png # when a PDF renderer is available
├── crop.png # when rendering and crop tools are available
├── page-<NN>.txt # when pdftotext is available
├── source-snippet.tex # when a source file and line range are provided
└── compile-log-excerpt.txt # when a log path is provided or detected
These are agent-private artifacts by default. Do not commit them to author-visible, anonymous-submission, arXiv, camera-ready, or publisher-visible paper source unless the user explicitly wants a sanitized debug artifact published.
Quick Command
Resolve the installed skill directory, then run:
python3 <latex-layout-issue-bundler-skill-dir>/scripts/create_layout_issue_bundle.py \
--paper-dir "$PAPER_DIR" \
--pdf "$PAPER_DIR/main.pdf" \
--page 7 \
--title "Algorithm 2 bottom gap" \
--problem "Large blank space after Algorithm 2 before the following paragraph." \
--object "Algorithm 2 and lines 247-255" \
--source "$PAPER_DIR/sections/method.tex:247-255" \
--crop bottom
The script prints the bundle path.
Inputs
--paper-dir: paper repo root or paper worktree root.--pdf: rendered PDF path.--page: 1-indexed PDF page number.--title: short issue title used for the issue id when--issue-idis omitted.--problem: what looks wrong visually.--object: affected object or paragraph, such asAlgorithm 2,Table 1, orlines 247-255.--source: optionalpath:start-endsource pointer.--crop: optional crop preset or rectangle:top,bottom,left,right,centerx,y,w,hin pixels
--log: optional compile log path. If omitted, the script tries<pdf-stem>.log.
Workflow
- Identify the page and local object from the PDF viewer, Overleaf preview, Skim, or SyncTeX.
- Run the bundler with the page, problem, object, optional source line range, and optional crop.
- Inspect
.agent/layout-issues/<issue-id>/prompt.md. - Give that bundle path to
submit-paper,paper-writing-assistant, or a fresh reviewer/sidecar session. - The fixing agent should make one small local change, compile through the configured backend, and compare the same page again.
Tool Behavior
The script uses tools only when available:
pdftoppmrenders a PDF page to PNG.pdftotextextracts page text.- ImageMagick
magickorconvertcrops the rendered PNG.
Missing tools are recorded in manifest.json; they are not treated as fatal if the bundle still has useful context.
Do not record local absolute tool paths or machine-specific TeX installation facts in the paper repo. Tool availability is runtime state.
Fixing Policy For Consumers
When consuming a bundle, follow the submit-paper layout debugging policy:
- localize the page and object first
- prefer prose and local float/page-break fixes over global layout settings
- change one object at a time
- avoid broad
\sloppy,\emergencystretch, global paragraph, or global float-spacing changes unless the whole paper has a documented style issue - verify the same page visually after each change
Version History
- e0220ca Current 2026-07-05 21:35
