Skill: 16miku/arxiv-paper-writer (version 0.2.0)

--- name: arxiv-paper-writer description: Use this skill whenever the user wants Claude Code to write, scaffold, compile, debug, or review an arXiv-style academic paper, especially survey papers with LaTeX, BibTeX citations, TikZ figures, tables, and PDF output. This skill should trigger for requests like writing a full paper, creating an arXiv paper project, turning a research topic into a LaTeX manuscript, reproducing the Paper-Write-Skill-Test agent-survey workflow, or setting up a Windows/Linux Claude Code paper-writing loop. --- # arxiv-paper-writer This skill guides Claude Code through an end-to-end arXiv-style paper workflow: plan the paper, initialize a LaTeX project, build a BibTeX library, write sections incrementally, create figures/tables, compile, debug, and perform a final quality review. ## Core principle Treat paper writing as an engineering loop, not a one-shot generation task. Work in small verifiable stages: plan, scaffold, cite, write, compile, inspect, repair, and review. ## When starting a paper project 1. Clarify topic, paper type, target length, audience, and whether the user wants a survey, methods paper, benchmark paper, position paper, or tutorial. 2. Create or reuse a paper directory with `main.tex`, `references.bib`, `figures/`, `sections/`, and `output/`. 3. Use `templates/arxiv_survey_main.tex` for a compact starter survey, or `templates/full_survey_main.tex` when the user wants the richer 9-section scaffold proven in the Agent Survey experiment. 4. Read `references/workflow.md` for the full staged process. 5. Read only the reference files needed for the current phase. 6. When the user asks to reproduce the Paper-Write-Skill-Test workflow, use `references/agent_survey_practice.md`, `templates/agent_survey_references.bib`, and `templates/agent_survey_figures_tables.tex` as concrete examples. ## Workflow phases ### Phase 1: Plan Create a concrete paper plan before writing prose. Include title candidates, scope, contribution claims, section outline, target references, expected figures/tables, and verification commands. ### Phase 2: Scaffold Create a compilable LaTeX skeleton first. The first milestone is a PDF that compiles even before the paper is complete. ### Phase 3: Build bibliography Construct `references.bib` before heavy writing. Prefer real, verifiable papers. Use stable BibTeX keys. Avoid invented citations. If uncertain about a reference, mark it for verification rather than fabricating metadata. ### Phase 4: Write sections incrementally Write one or two sections at a time. After each substantial section, compile or at least check citations and LaTeX syntax. Write Abstract last. ### Phase 5: Create figures and tables Prefer TikZ and LaTeX tables for reproducible academic artifacts. Keep figures information-dense and directly connected to claims in the text. ### Phase 6: Compile and debug Use `latexmk` on Linux when available. On Windows MiKTeX, use `pdflatex`, `bibtex`, `pdflatex`, `pdflatex`. Read `.log` files before guessing fixes. ### Phase 7: Final review Check PDF generation, citation completeness, undefined references, figure/table placement, academic tone, contribution clarity, and arXiv compatibility. ## Environment guidance - For Windows MiKTeX and Linux TeX Live basics, read `references/latex_environment.md`. - For fuller Linux cloud setup and verification, read `references/linux_texlive_full.md`. - For BibTeX construction, read `references/bibliography.md`. - For figure and table design, read `references/figures_and_tables.md` and optionally reuse `templates/agent_survey_figures_tables.tex`. - For final review, read `references/quality_review.md`. - For reusable task prompts, read `references/prompt_templates.md`. ## Output style When writing project files, edit the actual `.tex`, `.bib`, and documentation files. Do not merely describe what should be written. When explaining progress to the user, summarize briefly in Chinese and reference exact file paths.

path: evals/evals.json
content: {
  "skill_name": "arxiv-paper-writer",
  "evals": [
    {
      "id": 1,
      "prompt": "我想用 Claude Code 写一篇 10-15 页 arXiv 风格的英文综述论文，主题是 LLM-based agents 的发展历程。请创建论文项目结构、LaTeX 主文件、BibTeX 文件，并说明后续写作与编译步骤。",
      "expected_output": "Creates or proposes a complete LaTeX paper project structure, uses an arXiv-compatible template, initializes references.bib, and gives a staged compile/write/debug workflow.",
      "files": []
    },
    {
      "id": 2,
      "prompt": "我的 main.tex 编译失败，日志里有 undefined citation 和 newtxmath/amssymb 的 Bbbk 冲突。请帮我按论文工程闭环定位并修复问题。",
      "expected_output": "Reads or asks for relevant log/source files, identifies undefined citations and Bbbk conflict, applies targeted LaTeX/BibTeX fixes, and recommends rerunning BibTeX/latexmk.",
      "files": []
    },
    {
      "id": 3,
      "prompt": "我已经有一篇初稿 PDF 和 LaTeX 源码，想判断它距离高质量 arXiv survey paper 还差什么。请按学术质量、引用、结构、图表和编译可复现性给我审查清单。",
      "expected_output": "Provides a structured review checklist covering academic contribution, literature coverage, narrative, figures/tables, citations, LaTeX reproducibility, and arXiv readiness.",
      "files": []
    },
    {
      "id": 4,
      "prompt": "请复用 Paper-Write-Skill-Test 中 papers/agent-survey 的成功经验，为一个新的 survey paper 初始化更完整的 9 章节 LaTeX 骨架，并说明应该复用哪些参考文档、BibTeX 示例和 TikZ/表格模板。",
      "expected_output": "Uses the Agent Survey practice reference, recommends templates/full_survey_main.tex, templates/agent_survey_references.bib, templates/agent_survey_figures_tables.tex, and references/linux_texlive_full.md or latex_environment.md as appropriate.",
      "files": []
    }
  ]
}


path: README.md
content: # arxiv-paper-writer

`arxiv-paper-writer` is a Claude Code skill for creating, compiling, debugging, and reviewing arXiv-style academic papers, especially survey papers written in LaTeX with BibTeX citations, TikZ figures, and reproducible PDF output.

This skill was extracted from the successful `papers/agent-survey` experiment in the Paper-Write-Skill-Test project, where Claude Code produced a 15-page AI Agent survey paper with real references, TikZ figures, tables, and a compiled PDF.

## What this skill does

It guides Claude Code through a staged paper engineering loop:

```text
plan → scaffold → bibliography → section writing → figures/tables → compile → debug → review
```

The skill is designed to avoid one-shot paper generation. It instead encourages small verified steps and repeated compile/debug cycles.

## Directory layout

```text
arxiv-paper-writer/
├── SKILL.md
├── README.md
├── templates/
│   ├── arxiv_survey_main.tex
│   ├── full_survey_main.tex
│   ├── references.bib
│   ├── agent_survey_references.bib
│   └── agent_survey_figures_tables.tex
├── references/
├── scripts/
├── assets/
└── evals/
```

## Main capabilities

- Create an arXiv-style LaTeX paper project.
- Build and maintain a BibTeX bibliography.
- Write survey sections incrementally.
- Generate TikZ figures and LaTeX tables.
- Compile with Linux TeX Live or Windows MiKTeX.
- Diagnose common LaTeX and BibTeX errors.
- Review academic quality and arXiv readiness.
- Reuse the proven `papers/agent-survey` workflow through `references/agent_survey_practice.md`, `templates/full_survey_main.tex`, `templates/agent_survey_references.bib`, and `templates/agent_survey_figures_tables.tex`.

## Recommended usage

Example user prompts:

```text
用 Claude Code 帮我写一篇 10-15 页 arXiv 风格的英文综述论文，主题是 LLM agents。
```

```text
请把这个研究主题初始化成一个 LaTeX 论文项目，并创建 main.tex 和 references.bib。
```

```text
我的论文编译失败了，请读取 main.log 并修复 undefined citation 和 LaTeX 宏包冲突。
```

## Reused Agent Survey assets

The skill now includes selected reusable assets from the completed `papers/agent-survey` experiment:

- `references/agent_survey_practice.md`: condensed practice guide for the proven Claude Code paper-writing loop.
- `references/linux_texlive_full.md`: fuller Linux cloud TeX Live setup and validation guide.
- `references/prompt_templates.md`: reusable prompts for planning, scaffolding, bibliography, section writing, figure/table creation, compile-debug, and final review.
- `templates/full_survey_main.tex`: richer 9-section survey scaffold derived from the final Agent Survey structure.
- `templates/agent_survey_references.bib`: 39-entry example bibliography from the completed paper.
- `templates/agent_survey_figures_tables.tex`: reusable TikZ and table patterns.
- `assets/generate_paper_flowchart.png`: workflow diagram from the Windows Claude Code paper-writing run.
## Validation scripts

Check skill structure:

```bash
uv run python scripts/check_skill_structure.py
```

Check BibTeX:

```bash
uv run python scripts/check_bibtex.py path/to/references.bib
```

Check LaTeX log:

```bash
uv run python scripts/check_latex_log.py path/to/main.log
```

## Repository status

This skill is published as a standalone repository and linked from the parent project as a Git submodule.

- GitHub: `https://github.com/16Miku/arxiv-paper-writer-skill.git`
- ClawHub: `https://clawhub.ai/16miku/arxiv-paper-writer`



path: references/agent_survey_practice.md
content: # Agent Survey Practice Guide

This reference condenses the successful `papers/agent-survey` run into reusable steps for future arXiv-style survey papers.

## Proven outcome

The source experiment produced:

| Item | Result |
|------|--------|
| Topic | Evolution of AI Agents |
| Output | 15-page English PDF |
| References | 39 real BibTeX entries |
| Visuals | 2 TikZ figures + 2 LaTeX tables |
| Structure | Abstract, Keywords, 9 main sections, References |
| Toolchain | Claude Code + LaTeX + BibTeX + TikZ |

## Core workflow

```text
Plan topic and scope
  -> initialize LaTeX project
  -> build real BibTeX library
  -> write section skeleton
  -> draft one or two sections at a time
  -> add TikZ figures and LaTeX tables
  -> compile with pdflatex/bibtex or latexmk
  -> read logs and repair errors
  -> perform final academic and arXiv checks
```

## Recommended project layout

```text
paper-project/
├── main.tex
├── references.bib
├── sections/          # optional; useful for long papers
├── figures/           # external figures only if needed
└── output/            # generated PDF and build outputs
```

For conceptual survey papers, prefer TikZ figures embedded in `main.tex` and LaTeX tables over external images. This keeps the source self-contained and easier to submit to arXiv.

## Windows MiKTeX loop

Enable automatic package installation before long compile loops:

```bash
initexmf --set-config-value="[MPM]AutoInstall=yes"
initexmf --admin --set-config-value="[MPM]AutoInstall=yes"
```

Compile manually when `latexmk` is unavailable:

```bash
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex
```

Read `main.log` after failures. Do not guess LaTeX fixes without checking the exact error.

## Optional Python / uv setup

Python is not required for the basic paper loop when using TikZ and BibTeX directly. Use it only for helper scripts, data plots, or batch metadata processing.

```bash
uv python install 3.11
uv venv .venv
uv pip install requests matplotlib
```

## Literature strategy

For a standard survey, target 35-60 references. Cover:

1. foundational work;
2. representative systems/frameworks;
3. recent surveys;
4. benchmarks and evaluation papers;
5. challenge, safety, and future-direction papers.

Build `references.bib` before heavy prose writing. Use stable keys such as `authorYYYYshorttitle`. Do not invent metadata. If a DOI, venue, or page range is uncertain, mark it outside the BibTeX entry for later verification.

## Proven 9-section survey structure

The agent-survey paper used this reusable structure:

1. Introduction
2. Background and Definitions
3. Early Foundations
4. LLM-Based Agents
5. Agent Frameworks and Toolkits
6. Multi-Agent Systems
7. Applications and Case Studies
8. Challenges and Future Directions
9. Conclusion

Use `templates/full_survey_main.tex` when a user wants a richer survey scaffold instead of the smaller `templates/arxiv_survey_main.tex` starter.

## Visual artifact pattern

The successful paper used four high-value artifacts:

1. an architecture diagram showing core components;
2. a historical timeline;
3. a framework comparison table;
4. a benchmark comparison table.

Reusable snippets are in `templates/agent_survey_figures_tables.tex`.

## Final checks

Before calling the paper complete:

- PDF exists.
- Bibliography appears.
- No fatal LaTeX errors remain.
- No undefined citations remain.
- No undefined references remain.
- Figures and tables render.
- Abstract matches the final paper and is written last.
- Contribution claims are explicit and defensible.


path: references/bibliography.md
content: # Bibliography Reference

Use this reference when building or reviewing `references.bib`.

## Principles

- Prefer real, verifiable academic references.
- Do not invent titles, authors, venues, arXiv IDs, DOIs, or years.
- If metadata is uncertain, mark the entry for verification in a note outside the BibTeX entry.
- Use stable lowercase keys: `authorYYYYshorttitle`.
- Keep keys readable and consistent.

## Search strategy

For survey papers, split the topic into 5-8 literature clusters. For each cluster, identify:

- foundational works
- recent surveys
- representative systems
- benchmark/evaluation papers
- critique/safety/limitations papers

For the AI-agent-survey pattern, useful clusters were:

- symbolic agents and BDI
- reinforcement learning agents
- large language models
- LLM reasoning and planning
- tool use and memory
- agent frameworks
- multi-agent systems
- evaluation and safety

## Target counts

- Short paper: 15-25 references
- Standard survey: 35-60 references
- Large survey: 60+ references with stronger taxonomy and related-work coverage

## BibTeX entry shape

Article or arXiv paper:

```bibtex
@article{keyYYYYtopic,
  title={Full Title},
  author={Author, First and Second, Author},
  journal={Journal Name or arXiv preprint arXiv:XXXX.XXXXX},
  year={YYYY},
  doi={10.xxxx/example}
}
```

Conference paper:

```bibtex
@inproceedings{keyYYYYtopic,
  title={Full Title},
  author={Author, First and Second, Author},
  booktitle={Conference Name},
  pages={1--12},
  year={YYYY}
}
```

## Citation rules

Use `\citet{key}` when the author is part of the sentence:

```latex
\citet{vaswani2017attention} introduced the Transformer architecture.
```

Use `\citep{key}` when the citation supports a claim:

```latex
Transformers became foundational for modern language models \citep{vaswani2017attention}.
```

Use multiple citations when summarizing a research direction:

```latex
LLM agents combine reasoning, acting, and tool use \citep{yao2023react,shinn2024reflexion}.
```


path: references/figures_and_tables.md
content: # Figures and Tables Reference

Use this reference when creating reproducible paper visuals.

## Principles

- Prefer TikZ and LaTeX tables when the figure is conceptual, architectural, or taxonomic.
- Use external image files only when the paper needs plots, screenshots, or complex visual assets.
- Every figure/table should support a specific claim in the text.
- Keep captions explanatory enough that readers understand the artifact without reading the full section.

## Recommended survey artifacts

For arXiv-style survey papers, create 2-5 high-value artifacts:

1. timeline figure
2. architecture diagram
3. taxonomy table
4. framework/system comparison table
5. benchmark or limitation matrix

## TikZ architecture pattern

```latex
\begin{figure}[t]
\centering
\begin{tikzpicture}[
  node distance=1.5cm,
  box/.style={rectangle,rounded corners,draw=black,thick,align=center,minimum width=2.5cm,minimum height=0.8cm},
  arrow/.style={-{Latex[length=3mm]},thick}
]
\node[box] (input) {Input};
\node[box,right=of input] (reason) {Reasoning};
\node[box,right=of reason] (action) {Action};
\draw[arrow] (input) -- (reason);
\draw[arrow] (reason) -- (action);
\end{tikzpicture}
\caption{A minimal architecture diagram.}
\label{fig:architecture}
\end{figure}
```

## Booktabs table pattern

```latex
\begin{table}[t]
\centering
\caption{Comparison of representative systems.}
\label{tab:systems}
\begin{tabularx}{\linewidth}{l l l X}
\toprule
System & Year & Type & Key idea \\
\midrule
System A & 2023 & Framework & Short description. \\
System B & 2024 & Benchmark & Short description. \\
\bottomrule
\end{tabularx}
\end{table}
```


path: references/latex_environment.md
content: # LaTeX Environment Reference

Use this reference when setting up or debugging local/cloud LaTeX compilation.

## Windows: MiKTeX

Recommended commands:

```bash
pdflatex --version
bibtex --version
```

Enable automatic package installation to avoid GUI prompts during Claude Code compile loops:

```bash
initexmf --set-config-value="[MPM]AutoInstall=yes"
initexmf --admin --set-config-value="[MPM]AutoInstall=yes"
```

Compile sequence:

```bash
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex
```

## Linux: TeX Live

Recommended Ubuntu/Debian minimal install:

```bash
sudo apt update
sudo apt install -y \
  texlive-latex-base \
  texlive-latex-recommended \
  texlive-latex-extra \
  texlive-fonts-recommended \
  texlive-fonts-extra \
  texlive-pictures \
  texlive-bibtex-extra \
  latexmk \
  biber
```

Verify packages:

```bash
pdflatex --version
bibtex --version
latexmk --version
kpsewhich tikz.sty
kpsewhich newtxtext.sty
kpsewhich cleveref.sty
```

Preferred compile command:

```bash
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex
```

## Common issues

### Missing `.sty`

If LaTeX reports `File 'xxx.sty' not found`, run:

```bash
kpsewhich xxx.sty
```

Install the package group that contains it, or use full TeX Live if disk space is not constrained.

### `\Bbbk` conflict

If `newtxmath` and `amssymb` conflict, include this after loading `amssymb`:

```latex
\let\Bbbk\relax
```

### Undefined citations

Run BibTeX or use `latexmk`. Check that every `\citep{key}` or `\citet{key}` has a matching BibTeX key.


path: references/linux_texlive_full.md
content: # Linux TeX Live Full Reference

Use this reference when running Claude Code paper writing on Ubuntu, Debian, or a Linux cloud server.

## Goal

Build a minimum viable LaTeX environment that can:

| Capability | Verification |
|------------|--------------|
| Basic LaTeX compile | `pdflatex main.tex` creates a PDF |
| BibTeX citations | `bibtex main` processes `references.bib` |
| TikZ figures | PDF renders TikZ diagrams |
| Automatic multi-pass compile | `latexmk -pdf main.tex` completes |
| Common paper packages | `natbib`, `booktabs`, `hyperref`, `cleveref`, `newtxtext`, `newtxmath` are available |

## Recommended stack

```text
TeX Live
latexmk
BibTeX
TikZ / PGF
Claude Code
```

TeX Live is preferred on Linux because it is command-line friendly, reliable for unattended builds, and avoids GUI package-install prompts.

## System preflight

```bash
uname -a
cat /etc/os-release
which bash
which curl
which git
which make
```

Install base tools if needed:

```bash
sudo apt update
sudo apt install -y curl git make ca-certificates
```

## Minimal Ubuntu / Debian install

```bash
sudo apt update
sudo apt install -y \
  texlive-latex-base \
  texlive-latex-recommended \
  texlive-latex-extra \
  texlive-fonts-recommended \
  texlive-fonts-extra \
  texlive-pictures \
  texlive-bibtex-extra \
  latexmk \
  biber
```

If disk space is not constrained, this is the simplest low-friction option:

```bash
sudo apt install -y texlive-full latexmk biber
```

## Verify installed commands and packages

```bash
pdflatex --version
bibtex --version
latexmk --version
kpsewhich article.cls
kpsewhich tikz.sty
kpsewhich newtxtext.sty
kpsewhich newtxmath.sty
kpsewhich cleveref.sty
kpsewhich natbib.sty
kpsewhich booktabs.sty
```

Expected result: command version output and `.cls` / `.sty` paths. Missing output from `kpsewhich` means the package is unavailable.

## Minimal compile test

Create this structure:

```text
latex-cloud-test/
├── main.tex
├── references.bib
└── output/
```

Compile with:

```bash
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex
```

Or keep generated files in `output/`:

```bash
latexmk -pdf -interaction=nonstopmode -halt-on-error -outdir=output main.tex
```

Clean generated files:

```bash
latexmk -c
```

## Common Linux failures

### Missing `.sty`

Check the package first:

```bash
kpsewhich missing-package.sty
```

Then install the relevant TeX Live package group or switch to `texlive-full` if this keeps recurring.

### Undefined citations

Use a full multi-pass build:

```bash
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex
```

If building manually:

```bash
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex
```

### `newtxmath` / `amssymb` `\Bbbk` conflict

Place this after loading `amssymb`:

```latex
\let\Bbbk\relax
```

### Server has no sudo

Ask the administrator to preinstall TeX Live, or use TinyTeX / official TeX Live installer under the user directory. For skill-generated docs, make the dependency explicit rather than silently assuming `sudo` exists.


path: references/prompt_templates.md
content: # Prompt Templates Reference

Use these prompts to drive Claude Code through the paper-writing loop in small verifiable stages.

## Planning prompt

```text
请为主题「<TOPIC>」设计一篇 10-15 页 arXiv 风格英文综述论文方案。
请给出：标题候选、论文范围、核心贡献、章节结构、每章要回答的问题、目标引用类型、计划图表、编译验证步骤。
不要开始写完整正文。
```

## LaTeX scaffold prompt

```text
请在 <PAPER_DIR> 中初始化一个可编译的 arXiv 风格 LaTeX 论文项目。
使用 templates/arxiv_survey_main.tex 或 templates/full_survey_main.tex 作为起点，创建 main.tex、references.bib、figures/、sections/、output/。
先保证空骨架可以编译，再继续写正文。
```

## Bibliography prompt

```text
请为这篇综述构建 references.bib。
要求：只使用真实可核验论文；覆盖基础论文、近期 survey、代表性系统、benchmark、安全与挑战；BibTeX key 使用 authorYYYYshorttitle；不确定的元数据不要编造，单独列为待核验项。
```

## Section writing prompt

```text
请只写 <SECTION_NAME> 这一节。
要求：
1. 使用学术英文；
2. 引用 references.bib 中已有 key；
3. 不虚构引用；
4. 这一节完成后说明新增了哪些交叉引用、图表或待补文献；
5. 不改动无关章节。
```

## Figure/table prompt

```text
请为 <CLAIM_OR_SECTION> 设计一个信息密度高、可复现的 LaTeX 图表。
优先使用 TikZ 或 booktabs 表格。
图表必须支撑正文中的一个具体论点，caption 要能独立解释图表含义。
```

## Compile-debug prompt

```text
请读取 main.log，先定位 fatal error、undefined citation、undefined reference 或 missing package 的根因。
不要猜测修复。说明错误来源后，只修改必要的 .tex 或 .bib 内容，然后重新给出编译命令。
```

## Final review prompt

```text
请对当前 LaTeX 论文进行最终质量审查。
检查：PDF 是否生成、BibTeX 是否显示、是否还有 undefined citation/reference、图表是否可渲染、章节叙事是否连贯、贡献是否明确、局限是否充分、是否符合 arXiv 源码提交习惯。
输出必须包含：通过项、问题项、建议修复顺序。
```


path: references/quality_review.md
content: # Quality Review Reference

Use this reference before calling a paper complete.

## Compile checks

- PDF exists.
- BibTeX bibliography appears.
- No fatal LaTeX errors remain.
- No undefined citations remain.
- No undefined references remain.
- Figures and tables render.
- Hyperlinks and cross-references work.

## Academic checks

- The paper has a clear scope and does not pretend to cover more than it covers.
- Contribution claims are explicit and defensible.
- Related work includes both foundational and recent papers.
- The structure has a coherent narrative, not just a list of summaries.
- Tables and figures add synthesis rather than decoration.
- Limitations and open problems are discussed explicitly.
- The abstract accurately summarizes the final paper and is written last.

## arXiv-style checks

- `\pdfoutput=1` is present.
- The paper can compile from source without hidden local dependencies.
- Figure paths are relative.
- Generated intermediate files are not required for compilation unless intentionally included.
- The bibliography file is included.

## Suggested final commands

Linux:

```bash
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex
```

Windows fallback:

```bash
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex
```

Log scan:

```bash
grep -E "Undefined|undefined|Fatal|Emergency|Error" main.log || true
```


path: references/workflow.md
content: # arXiv Paper Workflow

Use this reference when the user asks to create a new paper project or reproduce the full Claude Code paper-writing loop.

## Stage 1: Define the paper

Clarify:

- paper type: survey, benchmark, methods, position, tutorial, or report
- topic and scope
- intended reader
- target length
- expected contribution claims
- required output: `.tex`, `.bib`, `.pdf`, figures, tables, or documentation

Produce a short plan before writing files.

## Stage 2: Initialize the project

Create this structure unless the user gives a different layout:

```text
paper-project/
├── main.tex
├── references.bib
├── figures/
├── sections/
└── output/
```

Copy `templates/arxiv_survey_main.tex` to `main.tex` and replace placeholders. Copy `templates/references.bib` to `references.bib` as a smoke-test bibliography.

## Stage 3: Build the bibliography

Before writing long sections, build a reference set:

- 15-25 core references for a short paper
- 35-60 references for a survey paper
- stable BibTeX keys such as `vaswani2017attention`
- no invented metadata
- uncertain entries marked for verification

## Stage 4: Write the paper incrementally

Write in this order:

1. title and outline
2. Introduction
3. Background
4. main body sections
5. challenges/future work
6. conclusion
7. abstract last

After each major section, compile or perform static checks.

## Stage 5: Add figures and tables

Prefer reproducible LaTeX-native artifacts:

- TikZ architecture diagram
- TikZ timeline
- `booktabs` comparison table
- benchmark or taxonomy table

Every figure/table should support a claim in the text.

## Stage 6: Compile and repair

Linux preferred command:

```bash
latexmk -pdf -interaction=nonstopmode -halt-on-error main.tex
```

Output directory variant:

```bash
latexmk -pdf -interaction=nonstopmode -halt-on-error -outdir=output main.tex
```

Windows MiKTeX fallback:

```bash
pdflatex main.tex
bibtex main
pdflatex main.tex
pdflatex main.tex
```

If compilation fails, read the `.log` file and fix the source. Do not guess blindly.

## Stage 7: Review

Check:

- PDF exists
- bibliography appears
- no undefined citations
- no undefined references
- figures and tables render
- contribution claims are clear
- related work coverage is credible
- limitations are explicit
- arXiv compatibility is preserved through `\pdfoutput=1`


path: scripts/check_bibtex.py
content: import re
import sys
from pathlib import Path

ENTRY_RE = re.compile(r"@\w+\s*\{\s*([^,]+),", re.MULTILINE)
REQUIRED_FIELDS = ["title", "author", "year"]


def main() -> int:
    if len(sys.argv) != 2:
        print("Usage: python check_bibtex.py <references.bib>")
        return 2

    path = Path(sys.argv[1])
    if not path.exists():
        print(f"BibTeX file not found: {path}")
        return 1

    text = path.read_text(encoding="utf-8")
    entries = ENTRY_RE.findall(text)
    if not entries:
        print("No BibTeX entries found")
        return 1

    duplicate_keys = sorted({key for key in entries if entries.count(key) > 1})
    if duplicate_keys:
        print("Duplicate BibTeX keys:")
        for key in duplicate_keys:
            print(f"- {key}")
        return 1

    lower_text = text.lower()
    missing_fields = [field for field in REQUIRED_FIELDS if f"{field}={{" not in lower_text and f"{field} = {{" not in lower_text]
    if missing_fields:
        print(f"Missing common required fields somewhere in file: {missing_fields}")
        return 1

    print(f"BibTeX sanity check ok: {len(entries)} entries")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


path: scripts/check_latex_log.py
content: import re
import sys
from pathlib import Path

ERROR_PATTERNS = [
    re.compile(r"! LaTeX Error:"),
    re.compile(r"! Emergency stop"),
    re.compile(r"Fatal error occurred"),
    re.compile(r"Citation .* undefined", re.IGNORECASE),
    re.compile(r"Reference .* undefined", re.IGNORECASE),
]


def main() -> int:
    if len(sys.argv) != 2:
        print("Usage: python check_latex_log.py <main.log>")
        return 2

    path = Path(sys.argv[1])
    if not path.exists():
        print(f"LaTeX log not found: {path}")
        return 1

    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
    matches = []
    for index, line in enumerate(lines, start=1):
        if any(pattern.search(line) for pattern in ERROR_PATTERNS):
            matches.append((index, line.strip()))

    if matches:
        print("LaTeX log issues found:")
        for index, line in matches[:50]:
            print(f"{index}: {line}")
        return 1

    print("LaTeX log sanity check ok")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


path: scripts/check_skill_structure.py
content: from pathlib import Path

REQUIRED_FILES = [
    "SKILL.md",
    "README.md",
    "templates/arxiv_survey_main.tex",
    "templates/full_survey_main.tex",
    "templates/references.bib",
    "templates/agent_survey_references.bib",
    "templates/agent_survey_figures_tables.tex",
    "references/workflow.md",
    "references/latex_environment.md",
    "references/linux_texlive_full.md",
    "references/bibliography.md",
    "references/figures_and_tables.md",
    "references/quality_review.md",
    "references/agent_survey_practice.md",
    "references/prompt_templates.md",
    "assets/generate_paper_flowchart.png",
    "evals/evals.json",
]


def main() -> int:
    base = Path(__file__).resolve().parents[1]
    missing = [path for path in REQUIRED_FILES if not (base / path).exists()]
    if missing:
        print("Missing required files:")
        for path in missing:
            print(f"- {path}")
        return 1

    skill_md = (base / "SKILL.md").read_text(encoding="utf-8")
    if not skill_md.startswith("---\nname: arxiv-paper-writer\n"):
        print("SKILL.md frontmatter is missing the expected name")
        return 1
    if "description:" not in skill_md:
        print("SKILL.md frontmatter is missing description")
        return 1

    print("arxiv-paper-writer skill structure ok")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())


path: SUBMODULE_NOTES.md
content: # Submodule Notes

This skill directory is designed to become an independent repository later.

## Current phase

During initial development, keep the skill as a normal directory under the parent project:

```text
skills/arxiv-paper-writer/
```

This avoids prematurely creating a nested Git repository before the skill structure stabilizes.

## Future migration path

When ready to publish independently:

1. Create a new empty remote repository, for example `arxiv-paper-writer-skill`.
2. Copy or move `skills/arxiv-paper-writer/` into a clean standalone directory.
3. Initialize Git in that standalone directory.
4. Commit the skill files.
5. Push to the new remote.
6. Remove the normal directory from the parent repository.
7. Add it back as a submodule.

Example commands after the independent repository exists:

```bash
git rm -r skills/arxiv-paper-writer
git submodule add <REMOTE_URL> skills/arxiv-paper-writer
git commit -m "将 arxiv-paper-writer skill 接入为独立 submodule"
```

Do not run these commands until the remote repository exists and the user confirms the migration.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)