LaTeX Typesetting Advisor

Language: English | 中文

Read mode: Quick Overview | Full Guide

A Codex skill for advanced LaTeX presentation design. It helps users choose a visual direction first, then generates reusable package stacks, preamble definitions, body examples, and compilation notes for papers, reports, course notes, Chinese documents, code handouts, and other long-form writing.

This skill is not a full .tex project repair tool. It is a typesetting advisor and snippet generator.

Quick Overview

What It Helps With

Need	What the skill provides
Better visual style	Concrete design options such as academic calm, modern technical report, teaching notes, code showcase, and Chinese formal report.
Reusable LaTeX snippets	Packages, preamble code, minimal body usage, and notes for common conflicts.
Academic readability	Safer layouts for theorem boxes, tables, figures, headings, references, code blocks, and page styles.
Chinese documents	ctex, XeLaTeX/LuaLaTeX, Chinese headings, Chinese reference names, and CJK typography notes.
Source awareness	Local source categories and public CTAN/GitHub reference links in references/source-map.md.

Install

git clone https://github.com/<your-name>/latex-typesetting-advisor.git "$HOME/.codex/skills/latex-typesetting-advisor"

Windows PowerShell:

git clone https://github.com/<your-name>/latex-typesetting-advisor.git "$env:USERPROFILE/.codex/skills/latex-typesetting-advisor"

Replace <your-name> with the actual GitHub user or organization.

Use

Use $latex-typesetting-advisor to improve the visual presentation of my LaTeX document.

Chinese prompt:

使用 $latex-typesetting-advisor，帮我的中文课程论文设计更高级但适合学术场景的排版方案。

Safe Defaults

• Chinese documents default to XeLaTeX.
• Code listings default to listings when shell escape is unavailable or unsafe.
• minted is treated as an advanced option because it usually needs -shell-escape plus helper tools.
• Links in references/source-map.md are source pointers, not automatic download steps.

Project Status

• Status: early public-ready source release.
• Primary host: Codex skills.
• Main explanation language inside the skill: Chinese, with LaTeX package names and commands preserved in English.
• Other agent hosts may still use the Markdown references, but compatibility is not guaranteed.

Back to read mode

Full Guide

Design Goal

The skill supports a decision-first workflow:

1. Understand the document type and constraints.
2. Offer 2-4 concrete visual directions when the user has not chosen one.
3. Generate a small, composable LaTeX pattern rather than a heavy full template.
4. Explain dependencies, compiler requirements, conflicts, and safer alternatives.
5. Preserve strict journal or university class requirements when they exist.

Typical output from the skill follows this order:

1. Design choice: selected visual style and fit.
2. Dependencies: package and compiler requirements.
3. Preamble code: complete reusable definitions.
4. Usage code: minimal realistic body example.
5. Notes: conflicts, alternatives, and strict-template adjustments.

Main Capabilities

Area	Reference file
Visual style choices	references/visual-choice-menu.md
Recipe routing	references/recipe-index.md
Boxes, callouts, theorem environments	references/boxes-highlights-theorems.md
Tables, figures, floats	references/tables-figures-floats.md
Headings, TOC, page style	references/headings-toc-page-style.md
Math numbering and cross-references	references/math-references-numbering.md
Code listings	references/code-listings.md
Chinese typography	references/chinese-typesetting.md
Source map	references/source-map.md

Example Workflows

Academic paper:

Use $latex-typesetting-advisor to make my paper more polished, but still conservative enough for an academic submission.

Expected response shape:

• Offer restrained styles such as Academic Calm or Chinese Formal Report.
• Prefer booktabs, hyperref, cleveref, and local tcolorbox environments.
• Avoid decorative page-wide effects unless the document is not bound by a strict class.

Teaching notes:

Use $latex-typesetting-advisor to design theorem, definition, note, and warning boxes for lecture notes.

Expected response shape:

• Select a teaching-note style.
• Use tcolorbox with skins and breakable.
• Provide theorem-like boxes and short body examples.
• Mention that journal classes may prefer simpler amsthm formatting.

Code-heavy document:

Use $latex-typesetting-advisor. I need Python code blocks in a paper, but Overleaf shell escape is disabled.

Expected response shape:

• Choose listings, not minted.
• Provide xcolor and listings configuration.
• Mention wrapping, line numbers, and no shell escape requirement.

Chinese report:

使用 $latex-typesetting-advisor，为中文实验报告设计章节标题、提示框、表格和公式引用格式。

Expected response shape:

• Assume ctexart or ctexrep and XeLaTeX unless the user says otherwise.
• Provide Chinese labels for theorem/callout/reference names.
• Keep typography formal and print-friendly.

Installation Details

The repository should live directly under a Codex skills directory:

~/.codex/skills/latex-typesetting-advisor/

Expected structure:

latex-typesetting-advisor/
  SKILL.md
  agents/
    openai.yaml
  references/
  examples/
  docs/
  .github/
  README.md
  README.zh-CN.md
  LICENSE
  SECURITY.md
  CONTRIBUTING.md
  CHANGELOG.md

After installation, invoke it by name:

Use $latex-typesetting-advisor ...

Source And Network Policy

references/source-map.md is an attribution and verification index. The skill should not browse those links during ordinary use.

Open source links only when:

• the user asks for sources, citations, or latest package behavior,
• a package option or compilation requirement may have changed,
• the user is preparing a public template or release and wants traceable references.

If network access is unavailable, the skill continues from bundled references and states that source links are static pointers.

Security Model

This repository contains Markdown, YAML, license text, and configuration text only. It does not include executable scripts, binaries, installers, runtime services, or automatic LaTeX compilation.

Important LaTeX safety notes:

• Do not enable -shell-escape for untrusted .tex projects.
• Use minted only for trusted documents and trusted code snippets.
• Prefer listings in restricted, shared, journal, classroom, or unknown environments.
• Review generated snippets before copying them into production thesis, paper, or template projects.

See SECURITY.md for reporting guidance.

Repository Governance

The repository includes:

• README.md and README.zh-CN.md for bilingual documentation.
• LICENSE for open-source reuse.
• CONTRIBUTING.md for contribution rules.
• SECURITY.md for private security reporting guidance.
• .gitignore and .gitattributes for clean publishing.
• .github/ISSUE_TEMPLATE/ for bug, feature, and documentation issues.
• .github/PULL_REQUEST_TEMPLATE.md for contribution review.
• .github/CODEOWNERS for maintainer review ownership.
• docs/release-checklist.md and docs/publish-to-github.md for release operations.

Validation

Run from the repository root:

python "<skill-creator>/scripts/quick_validate.py" .
git diff --check
git status --short
git ls-files

Expected:

• quick_validate.py reports Skill is valid!.
• git diff --check produces no output.
• git status --short is empty before tagging or publishing.
• git ls-files contains only intended source files.

Publishing To GitHub

Use docs/publish-to-github.md for the complete upload flow.

Short version:

git remote add origin https://github.com/<your-name>/latex-typesetting-advisor.git
git push -u origin main
git tag v0.1.0
git push origin v0.1.0

After publishing, configure secret scanning, push protection, main branch protection, repository topics, and release notes as described in docs/github-settings.md.

License

MIT License. See LICENSE.