From 99667cd1ddd07bb66454f33317da0a4aed7afdca Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=93=E5=A4=A9=E8=8E=B2?= <91449279+yitianlian@users.noreply.github.com> Date: Sun, 8 Mar 2026 12:43:41 +0800 Subject: [PATCH 1/2] Add paper-writing skill --- .agents/skills/paper-writing/SKILL.md | 71 ++++++++++++++++++ .../paper-writing/references/abstract.md | 56 ++++++++++++++ .../references/architecture-figures.md | 75 +++++++++++++++++++ .../references/arxiv-source-workflow.md | 51 +++++++++++++ .../paper-writing/references/experiments.md | 59 +++++++++++++++ .../paper-writing/references/introduction.md | 53 +++++++++++++ .../skills/paper-writing/references/method.md | 55 ++++++++++++++ .../paper-writing/references/related-work.md | 54 +++++++++++++ .../paper-writing/references/source-index.md | 39 ++++++++++ .../references/tables-and-layout.md | 49 ++++++++++++ .../paper-writing/references/workflow.md | 58 ++++++++++++++ .../scripts/fetch_arxiv_source.py | 69 +++++++++++++++++ AGENTS.md | 4 + 13 files changed, 693 insertions(+) create mode 100644 .agents/skills/paper-writing/SKILL.md create mode 100644 .agents/skills/paper-writing/references/abstract.md create mode 100644 .agents/skills/paper-writing/references/architecture-figures.md create mode 100644 .agents/skills/paper-writing/references/arxiv-source-workflow.md create mode 100644 .agents/skills/paper-writing/references/experiments.md create mode 100644 .agents/skills/paper-writing/references/introduction.md create mode 100644 .agents/skills/paper-writing/references/method.md create mode 100644 .agents/skills/paper-writing/references/related-work.md create mode 100644 .agents/skills/paper-writing/references/source-index.md create mode 100644 .agents/skills/paper-writing/references/tables-and-layout.md create mode 100644 .agents/skills/paper-writing/references/workflow.md create mode 100644 .agents/skills/paper-writing/scripts/fetch_arxiv_source.py diff --git a/.agents/skills/paper-writing/SKILL.md b/.agents/skills/paper-writing/SKILL.md new file mode 100644 index 0000000..c9ab4af --- /dev/null +++ b/.agents/skills/paper-writing/SKILL.md @@ -0,0 +1,71 @@ +--- +name: paper-writing +description: Write CS/AI papers with progressive disclosure. Use when drafting or revising sections such as abstract, introduction, related work, method, figures, experiments, or rebuttal text. Starts from a top-level workflow and loads only the section-specific reference needed. Includes arXiv source-fetch workflow for mining LaTeX organization from exemplar papers. +--- + +# Paper Writing + +## Mission + +Provide a section-aware paper-writing workflow that is: + +1. evidence-first +2. progressively disclosed +3. LaTeX- and structure-friendly +4. optimized for CS and AI papers + +Do not load all writing guidance at once. Start here, then open only the reference file needed for the current section. + +## Default Workflow + +1. identify paper type and draft stage +2. load `references/workflow.md` +3. load only the section file needed right now +4. if related-work style mining is needed, load `references/arxiv-source-workflow.md` +5. use `scripts/fetch_arxiv_source.py` to inspect exemplar paper sources +6. write only what is supported by actual evidence, experiments, and citations + +## Loading Map + +Open these references on demand: + +1. `references/source-index.md` + - external sources and what each one informs +2. `references/workflow.md` + - overall writing order, collaboration rules, and section contracts +3. `references/abstract.md` + - abstract structure and compression rules +4. `references/introduction.md` + - problem framing, gap, contributions, and section logic +5. `references/related-work.md` + - literature grouping, synthesis, comparison writing, and citation density +6. `references/arxiv-source-workflow.md` + - how to download and inspect arXiv LaTeX sources +7. `references/method.md` + - method narrative, notation, pipeline order, and algorithm exposition +8. `references/architecture-figures.md` + - architecture drawing heuristics and code-based tooling +9. `references/experiments.md` + - evaluation logic, ablations, robustness, and error analysis +10. `references/tables-and-layout.md` + - result tables, layout, appendix splitting, and figure-table coordination + +## Writing Rules + +1. Write from claims backward: + - claim + - evidence + - section role + - prose +2. Prefer synthesis over surface summary. +3. One paragraph should usually do one job. +4. Keep novelty claims proportional to the real delta. +5. For figures and tables, prefer code-generated assets that can be regenerated. +6. For related work, inspect representative arXiv source when organization matters. + +## Scripts + +1. `scripts/fetch_arxiv_source.py` + - download and unpack an arXiv source bundle + - list candidate main `.tex` files and section fragments + - useful for `Related Work`, `Method`, and layout mining diff --git a/.agents/skills/paper-writing/references/abstract.md b/.agents/skills/paper-writing/references/abstract.md new file mode 100644 index 0000000..68e08e8 --- /dev/null +++ b/.agents/skills/paper-writing/references/abstract.md @@ -0,0 +1,56 @@ +# Abstract + +## Job + +Compress: + +1. problem +2. gap +3. method +4. evidence +5. implication + +The abstract is not a motivational essay. + +## Default Structure + +Use 4-5 sentences: + +1. exact problem context +2. concrete bottleneck in prior work +3. method and key mechanism +4. strongest result with numbers where possible +5. why the result matters + +## Sentence Rules + +Sentence 1: + +- name the problem directly +- avoid empty openers like "Recent advances..." + +Sentence 2: + +- specify the actual failure mode or gap +- avoid generic "however" claims + +Sentence 3: + +- name the method and 1-2 essential mechanisms +- do not enumerate every module + +Sentence 4: + +- report concrete results +- say what the comparison is against + +Sentence 5: + +- state the takeaway, not sales copy + +## Rewrite Checklist + +1. remove hype words +2. replace adjectives with mechanism or metric +3. cut background better placed in introduction +4. keep tense consistent diff --git a/.agents/skills/paper-writing/references/architecture-figures.md b/.agents/skills/paper-writing/references/architecture-figures.md new file mode 100644 index 0000000..9482daf --- /dev/null +++ b/.agents/skills/paper-writing/references/architecture-figures.md @@ -0,0 +1,75 @@ +# Architecture Figures + +## Job + +Architecture figures should clarify the method faster than prose can. + +## Design Rules + +1. show information flow, not decoration +2. keep the reader's path obvious +3. use 3-6 major blocks, not every implementation detail +4. align names with the method section exactly +5. annotate the paper's novel block or changed path + +## Recommended Figure Workflow + +1. sketch the semantic blocks first +2. decide whether the figure is: + - pipeline + - dataflow + - training loop + - system deployment +3. draft quickly in code +4. only then polish spacing, color, and labels + +## Code-Based Tooling Choices + +### TikZ + +Use when: + +1. the paper is LaTeX-native +2. you need publication-grade vector consistency +3. the diagram is stable enough to justify fine control + +Strengths: + +1. integrates directly into LaTeX +2. precise typography and alignment +3. easy to keep consistent with paper fonts + +### Graphviz + +Use when: + +1. you need fast iteration on graph structure +2. you want automatic layout before manual polishing +3. the figure is mostly nodes and edges + +Strengths: + +1. fast text-based editing +2. automatic layout +3. good for dependency and pipeline drafts + +### Practical Recommendation + +Default pattern: + +1. draft with Graphviz or a simple text diagram if structure is unclear +2. finalize in TikZ when the figure is stable and will appear in the paper + +## Labeling Rules + +1. use noun phrases for blocks +2. use verbs on arrows only when action matters +3. avoid paragraphs inside boxes +4. make repeated flows visually repetitive on purpose + +## Figure Review Checklist + +1. can a reviewer retell the method from the figure +2. is the novelty visually identifiable +3. can the figure survive grayscale or print +4. does the figure introduce names not used in the text diff --git a/.agents/skills/paper-writing/references/arxiv-source-workflow.md b/.agents/skills/paper-writing/references/arxiv-source-workflow.md new file mode 100644 index 0000000..32f3356 --- /dev/null +++ b/.agents/skills/paper-writing/references/arxiv-source-workflow.md @@ -0,0 +1,51 @@ +# arXiv Source Workflow + +## Why Use Source Instead Of PDF Alone + +Source bundles expose: + +1. section splits +2. table files +3. figure code or assets +4. appendix organization +5. macros and naming conventions + +This is especially useful for: + +1. related work organization +2. method subsection design +3. experiment/table layout reuse + +## Default Workflow + +1. pick exemplar papers by section quality, not just citation count +2. download source with `scripts/fetch_arxiv_source.py` +3. inspect candidate main `.tex` and included subfiles +4. read only the relevant source fragments +5. extract organization patterns, not sentences + +## Example + +`ReAct` (`2210.03629`) was verified during skill creation: + +1. arXiv e-print works +2. the source bundle contains split files such as: + - `text/method.tex` + - `table/*.tex` + - figure assets + +That makes it a good reference for section decomposition and table/figure separation. + +## Command + +```bash +python3 .agents/skills/paper-writing/scripts/fetch_arxiv_source.py 2210.03629 +``` + +## What To Look For + +1. does the paper isolate related work or blend it into introduction +2. how many method subsections it uses +3. where tables live +4. whether architecture figures are code-generated or image-based +5. how appendix references are wired diff --git a/.agents/skills/paper-writing/references/experiments.md b/.agents/skills/paper-writing/references/experiments.md new file mode 100644 index 0000000..971eab7 --- /dev/null +++ b/.agents/skills/paper-writing/references/experiments.md @@ -0,0 +1,59 @@ +# Experiments + +## Job + +Experiments should answer whether the paper's claims hold. + +## Default Order + +1. setup and implementation details +2. main results +3. ablations +4. sensitivity or robustness +5. qualitative or error analysis + +## Core Principle + +Every experiment must map to a claim. + +Before writing a subsection, identify: + +1. claim being tested +2. baseline needed +3. metric that decides success or failure + +## Main Results Section + +1. start with the primary benchmark or setting +2. compare against the strongest relevant baselines +3. explain the pattern before diving into every number + +## Ablations + +1. remove or vary one component at a time +2. explain what the ablation isolates +3. do not present ablations as a random checklist + +## Robustness / Sensitivity + +Use when the paper claims: + +1. generalization +2. stability +3. low-resource effectiveness +4. scale behavior + +## Error Analysis + +Use error analysis when: + +1. the method claims interpretability +2. failure modes are central to the paper +3. aggregate metrics hide behavior differences + +## Writing Rules + +1. explain the evaluation logic, not just the metric names +2. separate implementation detail from result interpretation +3. highlight negative or null results when informative +4. say when a baseline is omitted and why diff --git a/.agents/skills/paper-writing/references/introduction.md b/.agents/skills/paper-writing/references/introduction.md new file mode 100644 index 0000000..9c8e267 --- /dev/null +++ b/.agents/skills/paper-writing/references/introduction.md @@ -0,0 +1,53 @@ +# Introduction + +## Job + +The introduction should make a reviewer answer: + +1. what exact problem is being solved +2. why current approaches are insufficient +3. what this paper changes +4. why the evidence should be believed + +## Default Paragraph Order + +1. problem and stakes +2. concrete gap or bottleneck +3. paper idea and intuition +4. evidence preview +5. contribution bullets +6. optional section roadmap + +## Paragraph Rules + +Paragraph 1: + +- define the task and stakes precisely +- avoid field-history narration unless it matters + +Paragraph 2: + +- show where prior approaches break +- use 1-2 crisp examples or failure patterns + +Paragraph 3: + +- present the paper's idea at the right abstraction level +- do not dump full method detail + +Paragraph 4: + +- preview strongest evidence +- name datasets, environments, or metrics when possible + +Contribution bullets: + +- each bullet should be independently defensible +- separate method, evaluation, and systems contributions + +## Common Failure Modes + +1. spending too much space on broad motivation +2. hiding the novelty until late +3. contribution bullets that are just tasks completed +4. promising more than experiments support diff --git a/.agents/skills/paper-writing/references/method.md b/.agents/skills/paper-writing/references/method.md new file mode 100644 index 0000000..d9e76d5 --- /dev/null +++ b/.agents/skills/paper-writing/references/method.md @@ -0,0 +1,55 @@ +# Method + +## Job + +Explain: + +1. what objects the method operates on +2. how the pipeline works +3. why each component exists +4. how the method differs from strong baselines + +## Default Order + +1. setup and notation +2. system or pipeline overview +3. core mechanism +4. training or optimization +5. complexity, implementation, or inference notes if needed + +## Writing Rules + +1. introduce notation only when it earns its keep +2. show the pipeline before diving into equations when the system is complex +3. isolate the key novelty in its own subsection +4. distinguish "what happens" from "why it helps" +5. when using equations, narrate them in words + +## Paragraph Roles + +Overview paragraph: + +- define inputs, outputs, and goal +- locate the paper's main intervention + +Mechanism paragraphs: + +- one component per paragraph or subsection +- state responsibility and interaction with other components + +Algorithm or training paragraph: + +- specify objective, update rule, or search process +- mention approximations and constraints + +## Common Failure Modes + +1. using undefined symbols too early +2. mixing implementation trivia with core method +3. describing modules without their interaction +4. equations with no verbal interpretation + +## When To Also Load + +1. load `architecture-figures.md` if a framework diagram is needed +2. load `arxiv-source-workflow.md` if you want method subsection patterns from exemplars diff --git a/.agents/skills/paper-writing/references/related-work.md b/.agents/skills/paper-writing/references/related-work.md new file mode 100644 index 0000000..9a1b0eb --- /dev/null +++ b/.agents/skills/paper-writing/references/related-work.md @@ -0,0 +1,54 @@ +# Related Work + +## Job + +Related work should position the paper against literatures, not summarize papers one by one. + +## Default Structure + +Organize by idea family or problem formulation, not by publication date. + +Recommended flow: + +1. closest line of work +2. adjacent line of work +3. where this paper differs + +## Writing Rules + +1. Group papers into 2-4 coherent buckets. +2. Start each bucket with the organizing idea. +3. Then mention representative works inside the bucket. +4. End each bucket with the limitation relevant to your paper. +5. Finish the section by saying exactly where your paper sits. + +## Good Bucket Patterns + +1. by supervision type +2. by environment or evaluation setting +3. by modeling assumption +4. by optimization strategy +5. by system architecture + +## Bad Patterns + +1. one paragraph per paper +2. paper list without synthesis +3. praise-heavy comparison without boundary conditions +4. hiding the closest baseline until late + +## Citation Density + +1. cite representatives, not every vaguely related paper +2. include closest baselines explicitly +3. when many papers share one claim, synthesize first and cite at the end of the sentence + +## Source-Mining Workflow + +When style or organization matters: + +1. download arXiv source for 2-4 exemplar papers +2. inspect whether they split related work into buckets or weave it into the introduction +3. reuse only structure patterns, not wording + +Also load `arxiv-source-workflow.md` when doing this. diff --git a/.agents/skills/paper-writing/references/source-index.md b/.agents/skills/paper-writing/references/source-index.md new file mode 100644 index 0000000..1fed292 --- /dev/null +++ b/.agents/skills/paper-writing/references/source-index.md @@ -0,0 +1,39 @@ +# Source Index + +As of `2026-03-08`, the following external sources informed this skill. + +## Paper Writing Structure + +1. Editage on abstract writing + - https://www.editage.com/insights/how-to-write-an-effective-abstract-for-a-scientific-paper + - Used for problem-method-results-implication compression. +2. Paperpal on abstracts + - https://paperpal.com/blog/academic-writing-guides/research-paper/abstracts + - Used to reinforce concise summary-first abstract writing. +3. The University of Manchester on introduction sections + - https://www.manchester.ac.uk/study/masters/blog/how-to-write-a-good-introduction-section/ + - Used for introduction sequencing and reader guidance. +4. Paperpile on related work + - https://paperpile.com/g/related-work/ + - Used for synthesis-over-summary and grouping-by-idea guidance. + +## Figures, Tables, and Tooling + +1. Overleaf on tables + - https://www.overleaf.com/learn/latex/Tables + - Used for table construction and layout notes. +2. Overleaf on TikZ + - https://www.overleaf.com/learn/latex/TikZ_package + - Used for code-based architecture figures inside LaTeX workflows. +3. Graphviz documentation + - https://graphviz.org/documentation/ + - Used for fast iterative diagram drafting before polishing in TikZ. + +## arXiv Source Workflow + +1. arXiv e-print endpoint + - Example verified with `https://arxiv.org/e-print/2210.03629` + - Used to download raw source bundles. +2. ReAct source bundle (`2210.03629`) + - Verified to contain split section files such as `text/method.tex`, `table/*.tex`, and figure assets. + - Used as the motivating example for source-level style mining. diff --git a/.agents/skills/paper-writing/references/tables-and-layout.md b/.agents/skills/paper-writing/references/tables-and-layout.md new file mode 100644 index 0000000..a457f93 --- /dev/null +++ b/.agents/skills/paper-writing/references/tables-and-layout.md @@ -0,0 +1,49 @@ +# Tables And Layout + +## Tables + +## Job + +Tables should make comparisons easy, not merely store numbers. + +## Table Rules + +1. one table should answer one main question +2. order rows by comparison logic, not randomness +3. keep metric direction obvious +4. bolding should signal best or key result consistently +5. move overflow columns to appendix when they dilute the main claim + +## Main-Paper Table Order + +1. primary comparison table +2. ablation table +3. robustness or sensitivity table + +## Caption Rules + +Captions should tell the reader: + +1. what is being compared +2. what setting matters +3. what pattern to notice + +## Layout Rules + +1. put the figure or table near the paragraph that interprets it +2. avoid forcing readers to flip pages for the main claim +3. if a result needs many caveats, consider appendix relocation + +## Appendix Migration Rules + +Move to appendix when content is: + +1. supportive but not decisive +2. too detailed for the paper's main narrative +3. useful mainly for reproducibility + +Keep in main paper when content is: + +1. claim-bearing +2. necessary to compare against baselines +3. critical for reviewer trust diff --git a/.agents/skills/paper-writing/references/workflow.md b/.agents/skills/paper-writing/references/workflow.md new file mode 100644 index 0000000..3ebd529 --- /dev/null +++ b/.agents/skills/paper-writing/references/workflow.md @@ -0,0 +1,58 @@ +# Workflow + +## Recommended Writing Order + +For CS and AI papers, default to: + +1. evidence inventory +2. claim and positioning +3. figure and table backbone +4. method outline +5. experiment outline +6. introduction +7. related work +8. abstract +9. title +10. appendix and polishing + +## Why This Order Works + +1. The story is clearer once figures and experiments exist. +2. Introductions are stronger after method and evidence are stable. +3. Related work is easier once the paper's true positioning is explicit. +4. Abstract should be written after the paper's actual contribution is fixed. + +## Collaboration Rules + +When helping a user write: + +1. ask which section is needed only if unclear +2. do not dump rules for all sections if one section was requested +3. keep one section contract active at a time +4. prefer outline-first when the story is unstable +5. rewrite paragraphs that mix multiple section roles + +## Section Contracts + +1. Abstract: + - compress the whole paper + - no citation survey +2. Introduction: + - frame problem, gap, and contribution + - preview evidence +3. Related Work: + - position the paper against literatures + - do not become an annotated bibliography +4. Method: + - define objects, pipeline, and rationale + - do not hide key design choices +5. Experiments: + - test whether claims hold + - keep evaluation logic explicit + +## Global Quality Gates + +1. each section has a distinct job +2. contributions match actual novelty +3. numeric evidence appears where needed +4. appendix holds overflow, not missing core logic diff --git a/.agents/skills/paper-writing/scripts/fetch_arxiv_source.py b/.agents/skills/paper-writing/scripts/fetch_arxiv_source.py new file mode 100644 index 0000000..51171ce --- /dev/null +++ b/.agents/skills/paper-writing/scripts/fetch_arxiv_source.py @@ -0,0 +1,69 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +import io +import os +import pathlib +import shutil +import tarfile +import tempfile +import urllib.request + + +def download_source(arxiv_id: str, destination: pathlib.Path) -> pathlib.Path: + url = f"https://arxiv.org/e-print/{arxiv_id}" + target = destination / f"{arxiv_id}.tar" + with urllib.request.urlopen(url) as response, target.open("wb") as handle: + shutil.copyfileobj(response, handle) + return target + + +def extract_tar(tar_path: pathlib.Path, destination: pathlib.Path) -> pathlib.Path: + extract_dir = destination / tar_path.stem + extract_dir.mkdir(parents=True, exist_ok=True) + with tarfile.open(tar_path) as archive: + archive.extractall(extract_dir, filter="data") + return extract_dir + + +def list_tex_files(root: pathlib.Path) -> list[pathlib.Path]: + return sorted(path for path in root.rglob("*.tex") if path.is_file()) + + +def score_tex_file(path: pathlib.Path) -> tuple[int, str]: + text = path.read_text(encoding="utf-8", errors="ignore") + score = 0 + for token in ("\\documentclass", "\\begin{document}", "\\input{", "\\include{", "\\section{"): + if token in text: + score += 1 + return score, str(path) + + +def main() -> None: + parser = argparse.ArgumentParser(description="Download and inspect an arXiv source bundle.") + parser.add_argument("arxiv_id", help="arXiv identifier, e.g. 2210.03629") + parser.add_argument("--out", default=".cache/arxiv-sources", help="Output directory") + args = parser.parse_args() + + out_dir = pathlib.Path(args.out).resolve() + out_dir.mkdir(parents=True, exist_ok=True) + + tar_path = download_source(args.arxiv_id, out_dir) + extract_dir = extract_tar(tar_path, out_dir) + tex_files = list_tex_files(extract_dir) + ranked = sorted((score_tex_file(path) for path in tex_files), reverse=True) + + print(f"arxiv_id: {args.arxiv_id}") + print(f"tarball: {tar_path}") + print(f"extracted_to: {extract_dir}") + print("candidate_main_tex:") + for score, path in ranked[:10]: + print(f" score={score} path={path}") + print("all_tex_files:") + for path in tex_files: + print(f" {path}") + + +if __name__ == "__main__": + main() diff --git a/AGENTS.md b/AGENTS.md index 51d42ef..d873bde 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,3 +22,7 @@ This workspace is for AI research and development tasks (reproduction, debugging - `.agents/skills/experiment-execution` - `.agents/skills/deep-research` - `.agents/skills/project-context` +- `.agents/skills/paper-writing` + +## Additional Skills +- `paper-writing`: Progressive-disclosure paper writing skill for CS/AI papers. Use when drafting or revising sections such as abstract, introduction, related work, method, figures, experiments, or rebuttal text. Includes section-specific references plus an arXiv source-fetch workflow for mining LaTeX organization from exemplar papers. From 9ed8916d8343217ee8f98e11651f60f771ab6741 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=93=E5=A4=A9=E8=8E=B2?= <91449279+yitianlian@users.noreply.github.com> Date: Sun, 8 Mar 2026 13:35:05 +0800 Subject: [PATCH 2/2] Fix skill link validation --- .claude/skills/paper-writing | 1 + .claude/skills/research-plan | 1 + 2 files changed, 2 insertions(+) create mode 120000 .claude/skills/paper-writing create mode 120000 .claude/skills/research-plan diff --git a/.claude/skills/paper-writing b/.claude/skills/paper-writing new file mode 120000 index 0000000..23dbe6b --- /dev/null +++ b/.claude/skills/paper-writing @@ -0,0 +1 @@ +../../.agents/skills/paper-writing \ No newline at end of file diff --git a/.claude/skills/research-plan b/.claude/skills/research-plan new file mode 120000 index 0000000..da71ad2 --- /dev/null +++ b/.claude/skills/research-plan @@ -0,0 +1 @@ +../../.agents/skills/research-plan \ No newline at end of file