原文内容

Beamer Skill

English | 简体中文

An AI coding assistant skill for creating, compiling, syncing, reviewing, and polishing academic Beamer LaTeX presentations for USTC LaTeX and other Overleaf-compatible platforms.

Maintained by USTC_Jaxon-JP(最闲的下饭菜).

This repository is a concise derivative of Noi1r/beamer-skill, with substantive extensions in workflow design, PDF/Python tooling choices, multi-environment packaging, compilation branching, and platform integration.

Supports Claude Code, OpenAI Codex CLI, Google Antigravity, and VS Code AI extensions (Copilot, Cline, Cursor).

Full lifecycle: create → sync/compile → review → polish → verify.

Recommended Usage

This derivative is primarily recommended for OpenCode. For best results, use an advanced multimodal model such as a GPT-class model; among Chinese domestic model options, Kimi is currently recommended for this workflow.

The suggested setup is to clone this repository locally and install the beamer/ directory as an OpenCode global skill. This setup step can be delegated to an AI coding assistant.

Typical global skill target:

~/.config/opencode/skills/beamer

Example Prompt

The skill is often used with Chinese paper-reading prompts. Example:

使用 beamer-skill 对 "C:\Users\server02\Desktop\2502.15260v2.pdf" 做一个论文讲解性质的 beamer，要求把架构和技术细节讲清楚（幻灯片页数不限制，适当加入论文关键图片，讲解要图文并茂，不过要注意图片比例不要有过界的情况，文字不要过于精简，不是面向汇报的那种幻灯片），观看对象是一个业内有一点知识储备的研究生。

Features

Highlights

• Quality scoring system — automated rubric (start at 100, deduct per issue) with Excellent/Good/Needs Work/Poor thresholds
• No overlays — no \pause, \onslide, \only. Uses multiple slides and color emphasis instead
• Content density guards — upper bounds (7 bullets, 2 equations, 5 symbols per slide) and lower bounds (every slide earns its place)
• Box overflow detection — Beamer suppresses overflow warnings inside blocks; the skill catches them via visual audit
• Motivation before formalism — every concept starts with “Why?” before “What?”
• TikZ precision — mathematical accuracy enforced via \pgfmathsetmacro (no hardcoded approximations)
• Semantic color system — colorblind-safe palette (\pos{}, \con{}, \HL{}) with WCAG AA contrast (≥ 4.5:1)
• Figure extraction — pull figures directly from paper PDFs via pdf-mcp, ready for \includegraphics
• Timing allocation — built-in slide-count heuristics for 5min lightning talks through 90min lectures
• Columns & layout rules — enforced columns[T] patterns with gap/width constraints
• Backup slides — automatic appendix section for anticipated Q&A
• Algorithm & code support — algorithm2e, listings, pgfplots integration with per-slide line limits
• Dual-path compilation — compile locally when a working TeX environment exists; otherwise fall back to USTC LaTeX remote compilation
• XeLaTeX on platform — after push, remind the user to enable XeLaTeX (sometimes shown as xelatex / xlatex mode)

Prerequisites

Core workflow

This skill is designed for:

• local Beamer authoring
• local PDF analysis (papers, figures, tables, structure)
• local XeLaTeX compilation when a working TeX environment is available
• remote XeLaTeX compilation on USTC LaTeX or another Overleaf-compatible platform

A local TeX distribution is optional but preferred for fast feedback. If it is unavailable, the assistant should ask whether to install local TeX dependencies or go straight to the remote platform.

Assumed local environment

The skill assumes common local helper tools are already available when needed. It does not proactively install dependencies before running.

If a local helper tool is missing, the skill should:

1. continue with the best available fallback when possible
2. otherwise report the missing dependency clearly
3. suggest an installation command only after the failure is observed

Git workflow

Recommended setup:

• keep your main development repository as the primary Git remote (origin)
• add the LaTeX platform project as a second remote, e.g. ustc-latex
• push to the platform remote when you want remote compilation

You only need:

• git
• A USTC LaTeX project with Git enabled
• The project Git address copied from the platform, commonly shown as: git clone https://git@latex.ustc.edu.cn/git/****************
• A Git token supplied by the user

Recommended remote setup (replace placeholders with the Git URL copied from the platform):

git remote add ustc-latex https://git@latex.ustc.edu.cn/git/****************
git push ustc-latex HEAD

If the user provides the full git clone ... command copied from USTC LaTeX, extract the URL part before running git remote add.

GitHub is optional, not required. Any primary Git remote is acceptable. Keep the platform as a separate remote. Avoid git push --force / git pull --force; if the remote repository gets out of sync, re-clone instead.

Dependency policy

This skill keeps lazy dependency handling for most helper tools, but compilation has a dedicated branch:

• first check whether a working local TeX environment is available (latexmk, xelatex, or equivalent)
• if local compilation works, use it for fast feedback
• if local compilation tools are missing, ask the user whether to install the missing dependencies or go directly to USTC LaTeX remote compilation
• for non-compilation helper tools, continue using lazy dependency handling and only suggest installation after an actual missing-tool failure

This keeps the workflow lightweight while still preferring local compile feedback when the environment already supports it.

pdf-mcp (Recommended)

Install pdf-mcp (fork with file-based image extraction — avoids base64 token bloat) so Claude Code can read large PDFs (papers, references) and extract figures directly:

pip install git+https://github.com/Noi1r/pdf-mcp.git
claude mcp add pdf-mcp --scope user pdf-mcp

If you use a SOCKS proxy, also install socksio (required by httpx for SOCKS support):

pip install socksio

This enables the create action to analyze research papers and extract-figures to pull figures for slide inclusion.

Installation

Clone the repo first:

git clone https://github.com/JaxonJP/beamer-skill.git

Claude Code

Copy the skill directory into your Claude Code skills folder:

mkdir -p ~/.claude/skills
cp -r beamer-skill/beamer ~/.claude/skills/

Restart Claude Code. The skill will be automatically detected and triggered when you mention beamer, slides, lecture, tikz, or related keywords.

OpenAI Codex CLI

Copy AGENTS.md and references/ into your project root:

cp beamer-skill/beamer/AGENTS.md your-project/AGENTS.md
cp -r beamer-skill/beamer/references your-project/references

Codex CLI automatically reads AGENTS.md from the working directory. The main file contains core rules and action summaries; detailed workflows are in references/ and referenced as needed.

Google Antigravity

Antigravity is compatible with the SKILL.md format. Copy the skill directory:

mkdir -p ~/.claude/skills
cp -r beamer-skill/beamer ~/.claude/skills/

The same SKILL.md used by Claude Code works with Antigravity without modification.

VS Code — GitHub Copilot

Copy the Copilot instructions file into your project:

mkdir -p your-project/.github
cp beamer-skill/.github/copilot-instructions.md your-project/.github/

Copilot Chat automatically reads .github/copilot-instructions.md and applies the rules during conversations.

VS Code — Cline

Copy the Cline rules file into your project:

mkdir -p your-project/.clinerules
cp beamer-skill/.clinerules/beamer.md your-project/.clinerules/

Cline automatically loads all files in .clinerules/ as custom instructions.

VS Code — Cursor

Copy the Cursor rules file into your project:

mkdir -p your-project/.cursor/rules
cp beamer-skill/.cursor/rules/beamer.mdc your-project/.cursor/rules/

Cursor automatically loads .mdc files from .cursor/rules/. The globs field in the frontmatter ensures the rules activate for .tex, .bib, and .sty files.

Platform Comparison

Usage

Once installed, the skill is triggered automatically when you mention beamer, slides, lecture, tikz, or related keywords.

Default Authoring Workflow

1. Draft slides locally with your AI assistant.
2. Keep figures, bibliography, and sources in the same Git repo.
3. Check whether local TeX compilation is available; if yes, compile locally first.
4. If local TeX is unavailable, ask whether to install local dependencies or use USTC LaTeX remote compilation directly.
5. After the current local Beamer version is written, immediately add ustc-latex as a second remote and push the latest deck to the platform.
6. Provide the platform project Git address when needed, commonly copied as git clone https://git@latex.ustc.edu.cn/git/****************.
7. Open https://latex.ustc.edu.cn to inspect the remote PDF and compile log, and enable XeLaTeX if the platform is not already in xelatex / xlatex mode.

Create a lecture from a paper:

Help me create a beamer presentation based on this paper: /path/to/paper.pdf

Extract figures from a paper:

Extract figures from /path/to/paper.pdf for my slides

Local-first or USTC compile:

Compile my slides: /path/to/slides.tex
# first try local XeLaTeX if available
# otherwise use the USTC LaTeX project address copied from the platform
# e.g. git clone https://git@latex.ustc.edu.cn/git/****************
# after push, enable XeLaTeX / xelatex / xlatex mode on the platform

Full quality check:

Run excellence review on /path/to/slides.tex

Proofread only:

Proofread /path/to/slides.tex

Customization

Default Presenter

The skill defaults to:

\author{USTC_Jaxon-JP(最闲的下饭菜)}
\institute{University of Science and Technology of China}

To change this, either:

• Tell the AI assistant your name/affiliation when creating slides, or
• Edit the preamble section in the corresponding instruction file (SKILL.md, AGENTS.md, or the VS Code config)

Custom Templates

If you have a custom beamer preamble, header file, or theme, simply provide it. The skill will use yours instead of the built-in default.

Examples

The example/ directory contains real-world examples generated entirely by this skill:

Each example includes the source paper (PDF), the generated .tex, and a compiled .pdf artifact. In the default workflow, new decks are authored locally and compiled remotely on USTC LaTeX after Git sync. The figures/ directory contains images extracted from the source papers via extract-figures.

Benchmark: With Skill vs. Without Skill

Automated evaluation comparing Claude Code with the beamer skill against a baseline (no skill). Each test was run by an independent subagent; assertions check objective, verifiable properties of the output.

Test 1 — create: 10-min talk from a cryptography paper

Test 2 — review + validate: proofread an existing slide deck

Summary

The skill guarantees structural compliance (references, backups, semantic colors, formatted reports) that the baseline consistently misses. Token/time overhead is moderate (~30%/~73%) relative to the quality gain.

File Structure

beamer-skill/
├── beamer/
│   ├── SKILL.md                    # Full skill (Claude Code / Antigravity)
│   ├── AGENTS.md                   # Codex CLI main file
│   └── references/                 # Codex CLI detailed rules
│       ├── create-workflow.md      #   Phase 0-5 creation workflow
│       ├── tikz-standards.md       #   TikZ quality standards & patterns
│       └── review-actions.md       #   review/audit/pedagogy/excellence/validate
├── .github/
│   └── copilot-instructions.md     # VS Code Copilot
├── .clinerules/
│   └── beamer.md                   # VS Code Cline
├── .cursor/
│   └── rules/
│       └── beamer.mdc              # VS Code Cursor
├── example/                        # Real-world examples
│   ├── 199.pdf                     # Source paper (zkAgent)
│   ├── zkagent_slides.*            # Generated slides
│   ├── slides.*                    # Crohn's disease fibrosis
│   ├── slides_EP.*                 # Endoscopic papillectomy
│   └── figures/                    # Extracted paper figures
├── README.md
└── LICENSE

License

MIT