lunwen-skill turns a code project into a thesis draft with figures

A thesis skill aimed at one very specific kind of student

lunwen-skill is a skill for coding agents, and its scope is narrower than the name suggests. It is aimed at undergraduate computer science students who cannot get a thesis draft started, who do not know how to turn an opening report and a pile of project code into body text, and who are missing the figures: flowcharts, use case diagrams, E-R diagrams, system screenshots and test content.

The workflow it encodes starts from real inputs rather than from imagination. Past sample theses, the opening report or task book, the university template with its formatting rules, and the project source directory. The stated principle is that project facts come first and modules are never invented from nothing, and that the sample thesis teaches both content and style, not only content.

The output is a .docx file with a table of contents, per-chapter word targets, a reference pool with a controlled mix of Chinese and English sources, diagrams, and a filled document rather than a pile of loose notes. It is a first draft meant for further editing, and the design principles in the documentation say as much when they require the agent to show its process and results to the user.

The audience constraint is real. The workflow, the writing rhythm, the reference balance rules and the default language of the interaction are all set for Chinese undergraduate theses, so the skill is not a general academic writing agent that happens to be configurable.

Three ways to install it, and where it has to land

There are two documented install routes for the primary target, Codex, and a third option for other agents.

The first uses the Codex skill-installer script directly from the repository:

python "${HOME}\.codex\skills\.system\skill-installer\scripts\install-skill-from-github.py" --repo Doryoku1223/lunwen-skill --path . --name lunwen

The second is a plain clone into the local skills directory:

git clone https://github.com/Doryoku1223/lunwen-skill.git "${HOME}\.codex\skills\lunwen"

After either route the documentation says to restart Codex so that it discovers the skill.

The third route is for Claude Code, and it is a compatibility layer rather than a different install. The repository ships a .claude/commands/ directory and a .claude/agents/ directory that can be dropped into a project, and there is a .trae/commands/ and .trae/agents/ wrapper for environments such as Trae that read only entry commands and agent definitions. The point of the wrappers is to pass the whole workflow through rather than a single command, which is a reasonable way to handle agents with different extension points.

The nine step workflow the skill is built around

The recommended order is short enough to memorise and specific enough to check against, which is the difference between a workflow and a suggestion.

First, read the project code and documents and freeze the facts of the project into a baseline. Second, analyse a sample paper or template and extract the chapter sizes and the layout styles. Third, generate a word count target per chapter of the thesis. Fourth, write chapter by chapter while keeping the word count under control as you go. Fifth, build the reference pool and check the ratio of Chinese to English entries. Sixth, handle the Mermaid and PlantUML diagrams. Seventh, capture real system screenshots to replace placeholders. Eighth, generate the .docx. Ninth, do the final check.

That order is not arbitrary. Extracting the template before writing is what stops the agent from producing a well-formed document in the wrong house style, and freezing the project facts first is what stops it from inventing a module that never existed.

The recommended first inputs are the school thesis template, past sample theses, the opening report or task book, and the project source directory. The documentation is direct that without these the agent cannot follow the correct sequence of analyse the template first, then confirm the directory style, then generate the .docx.

The tools directory does the mechanical work

The skills a user runs are prose instructions, and the scripts under tools/ are where the repeatable steps actually happen. Most of them take a thesis markdown file and produce structured output.

Word counts per chapter come from:

python tools/count_chapter_words.py thesis.md

A sample paper in PDF form is analysed with:

python tools/analyze_sample_pdf.py sample.pdf

The reference pool is built and checked separately:

python tools/build_reference_pool.py thesis.md

Styles are extracted from a sample .docx and written to a profile file:

python tools/analyze_docx_styles.py sample.docx output/style-profile.json

Screenshots are handled in two steps, first extracting the placeholder labels from the text and then turning them into a plan:

python tools/extract_screenshot_placeholders.py thesis.md --json-out labels.json
python tools/build_image_map.py labels.json output/doc image-map.json

Diagrams are extracted as Mermaid source and rendered one by one:

python tools/extract_mermaid_blocks.py thesis.md tmp/mermaid --manifest tmp/mermaid/manifest.json
python tools/render_mermaid.py tmp/mermaid/diagram-01.mmd tmp/mermaid/diagram-01.png

And the final document is assembled with the style profile and the image map:

python tools/generate_thesis_docx.py thesis.md thesis.docx --style-spec output/style-profile.json --image-map image-map.json

Screenshots come from a browser, and the browser comes from Playwright

The screenshot step is the part of the workflow with an external dependency, and the repository treats it as a separate concern.

The root package.json is a small private package with a version of 0.1.0 and a description that says it holds self-contained browser automation helpers for thesis screenshots. It depends on playwright at ^1.53.0 and defines two scripts, one that installs the browser and one that captures:

  "scripts": {
    "install:browsers": "playwright install chromium",
    "capture:screenshots": "node tools/browser/capture_screenshots.mjs"
  },

The Python side needs three libraries, listed in requirements.txt as pypdf, pdfplumber and python-docx, which map onto reading PDF samples, extracting text from them and manipulating Word documents.

The design choice worth noting is that the browser step is a separate language. The thesis pipeline is Python, the capture helper is a Node script, and the two meet through the image map file rather than through a shared library. That keeps the capture step replaceable, and it also means a user without Node and Playwright installed loses the real screenshots and keeps the placeholders, which is exactly what the limitations section warns about.

The documented limits, and the skills it expects alongside it

The limitations are stated without hedging. Without LibreOffice or Poppler in the environment, page by page rendering checks cannot be done. Without Mermaid rendering capability, the flowcharts may remain as source or placeholders. Browser screenshots and real system capture depend on extra environment support.

That is the shape of this project. The agent instructions are the product, and the scripts are the parts that degrade. A user on a machine with none of those tools still gets a structured draft with a table of contents and prose, and loses exactly the visual polish that the documentation advertises.

The alternative approach is to assemble the same pipeline from generic skills, and the documentation names them. A docx skill for reading, analysing and validating .docx templates and finished documents, a pdf skill for when the school only provides a PDF template, a doc skill for legacy .doc input, a playwright skill for capturing real screenshots, planning-with-files for holding state across a multi-stage job, systematic-debugging for locating the cause of problems such as duplicated table of contents entries or images covering body text, and verification-before-completion to enforce word count, citation, table of contents, image and file existence checks before the agent claims the thesis is finished.

The difference is specificity. Those skills are general purpose, while this one encodes a particular set of undergraduate thesis conventions and a template-first order of operations, and it adds the working scripts that the generic set does not ship.

MIT terms, a 0.1.0 package, and a repository last pushed in April

The project is released under the MIT Licence, with the LICENSE file at the repository root, and the README carries an MIT badge. The structure is a skill repository rather than an application: SKILL.md at the top, then agents/, prompts/, references/, tools/, docs/ and examples/, alongside a package.json, a requirements.txt and an INSTALL.md. The examples directory holds a sample outline in markdown and a sample screenshot plan in JSON.

The version to be aware of is the package.json one, 0.1.0, on a package marked private, so it is not published to a registry and the number describes the repository rather than a distributed release. The repository has no GitHub releases either.

The maintenance picture is the part to keep in view. The last push was on 2026-04-05, which is more than six months before the present date, so this is not a project that is currently receiving updates, and the documentation should be read as describing the state of the code at that point. For a tool whose value is a set of instructions rather than a library API, that matters less than it would for code, but it does mean the referenced companion skills and the Codex skill-installer path may have moved since.

Editorial conclusion

lunwen-skill fits an undergraduate computer science student who has a working project and a deadline, because it automates the parts of thesis writing that are mechanical: matching the house template, sizing each chapter, drawing the diagrams and capturing real screenshots. It does not fit a supervisor who needs original analysis, and it does not fit an environment without LibreOffice, Poppler, a Mermaid renderer or a browser, since each missing piece silently narrows the output. Before running it, provide the school template, a past sample and the source directory, as the documentation insists, and treat the result as a structured first draft that still needs a human read.

Frequently asked questions

Official sources

1. Doryoku1223/lunwen-skill on GitHub
2. Issues
3. License: MIT
4. README