humanities-thesis-skill: an academic writing skill with a deterministic reviewer

A skill that coaches method instead of writing the paper

The repository describes itself as an AI skill for humanities thesis writing, covering topic selection through to publication, with eight academic databases, 21 review rules and anti-hallucination guardrails. The self-description is deliberately narrow about what it does. The README says in one line that it is not helping you write the paper, it is helping you think through how the paper should be written and then checking whether each paragraph you wrote holds up. The core capabilities are grouped in three columns in the README: methodology guidance, a literature toolchain and quality assurance. The methodology side starts with structured questioning, three rounds of it, that move a vague interest towards an arguable question, and then covers topic selection, theory framework, structure design, close reading of sources, historical context and revision diagnosis. There is also a four step workflow for turning scattered notes into a full paper, described as taking stock, extracting leads, restructuring and stitching the gaps. The audience is graduate students and researchers in literature, history, philosophy, sociology and the communication and journalism fields.

Two scripts and a layered reference directory

The repository is small and its layout is the design. At the top there is SKILL.md, the core instructions the agent loads on startup, plus README.md, LICENSE, requirements.txt and a .gitignore that ignores sensitive files such as .env. The references/ directory holds ten documents that are loaded on demand, which is the token saving mechanism: writing-templates.md with positive and negative examples, theory-frameworks.md with a quick reference for 20 theorists and a fallback search strategy, terminology-bilingual.md with more than 350 terminology pairs across 19 disciplines, formatting-guide.md covering fonts, footnotes and references, literature-review.md and literature-analysis.md, a document on integrating scattered notes into a full paper, english-translation.md for translation and submission preparation, text-review.md describing the review dimensions, and platform-guide.md for agent adaptation. The scripts/ directory holds the Python toolchain with search.py as the literature search entry point, review.py as the text review entry point, and a lib/ folder containing schema, http_client, utils, query, score, dedupe, render, citation and review_rules modules, plus a sources/ folder with one module per database.

English literature search across free APIs, Chinese literature by hand

The search side splits databases into two groups, and the reason given is anti-scraping pressure rather than technical difficulty. English literature is searched automatically through free public APIs with no configuration: OpenAlex, Semantic Scholar, CORE and CrossRef, with the README describing OpenAlex as a free alternative to Scopus with hundreds of millions of papers, CORE as a large open access corpus, and CrossRef as DOI metadata lookup. Chinese literature goes the other way. The recommended workflow is that you search yourself on CNKI, the National Centre for Philosophy and Social Sciences Documentation, or Wanfang, export or copy the results as text or Endnote format, and hand them to the assistant for parsing, screening, dismantling and integration. The README is explicit that CNKI and Google Scholar have strong anti-scraping measures and that automatic fetching is unstable, and the sources/ folder marks source_cnki.py, source_ncpssd.py, source_wanfang.py and source_google_scholar.py as experimental. The rest of the pipeline is what makes the search useful: query preprocessing that expands Chinese and English terms, scoring and ranking, and cross-source deduplication.

The review script checks prose with regex, not with a model

This is the part of the project that sets it apart from a prompt collection. The README is explicit that the text evaluation engine is not asking the model to check itself, but doing deterministic verification with regex matching and terminology table comparison. The rule set is 21 rules across six dimensions. The credibility dimension, R1 to R3, covers vague citations, citations with future years as a fabrication signal, and over-assertion. The terminology rule catches the same concept appearing under several translations, which the README illustrates with three different renderings of one term. The format rules cover empty footnotes, missing reference type markers such as [M] and [J], mixed Chinese and English punctuation, and mixed heading numbering styles. The register rules catch colloquial phrasing and inconsistent first person reference. The argumentation rules, L-01 to L-08, cover consecutive assertions without connective reasoning, parallel piling without progression, a citation followed by no analysis, unargued causal premises, concept piling in summary sentences, and strong words without supporting evidence. The structure rules check for a missing abstract, keywords or references, and an introduction without a thesis sentence. The output format is a list with severity, rule id and line number, plus a suggestion, and the counts are summarised as errors, warnings and hints.

Running the two command line tools

The skill can be used in three ways. The simplest is to open SKILL.md, copy it, and paste it into whatever AI platform you use, feeding in the reference files as needed, for instance theory-frameworks.md when choosing a framework or terminology-bilingual.md when checking a term. The second is to install it as a skill in Claude Code or OpenClaw, where the agent reads SKILL.md and loads the functionality. The third is the command line route, which is the one with the scripts.

Clone the repository and install the dependencies first.

git clone https://github.com/ganzhi-black/humanities-thesis-skill
cd humanities-thesis-skill
pip install -r requirements.txt

With the dependencies in place you can search English academic literature through the free APIs and check a draft for quality problems.

python scripts/search.py "trauma narrative Chinese literature"

python scripts/review.py paper.md

The dependencies are the usual document processing stack: beautifulsoup4 and requests for HTML and HTTP work, PyMuPDF for PDF text extraction, pdfplumber as an alternative for tables and text, and python-docx for reading and generating Word documents. The requirements file also lists OCR support as optional, with pytesseract and Pillow commented out and a note that the system needs tesseract-ocr installed. The project badge states Python 3.9 or newer.

Why the anti-hallucination rules come first

The design principles table in the README explains the ordering, and it is a defensible one. SKILL.md is kept short, with the core instructions held under 250 lines and everything else loaded on demand from references/, which is what keeps a skill this size usable across platforms. The rules come before the methodology, and the stated reason is that academic credibility is the floor. The methodology starts from the evidence rather than the theory, with arguments growing from inside the sources instead of picking a theory and then hunting for confirmation. Deterministic verification is preferred over model self-assessment, which is the rationale for the whole review engine. Search and analysis are separated, as described above. And both the theory reference and the terminology table have a fallback chain: if the table does not have it, search for it, and if the search fails, fall back to the pinyin plus an explanation. The README also lists the 21 rules, the 350-plus terminology entries and the eight databases as the project's headline numbers, and notes that the terminology table and theory frameworks keep expanding, currently covering 20 theorists.

What the project will not do, and where it is the wrong tool

The notes section is blunt about the limits. It is a writing aid, not a ghostwriting service: the skill helps you organise your thinking, check problems and search for literature, but the core argument and the original analysis have to come from you. Everything the tool generates still needs human verification, especially bibliographic details such as authors, titles, years and page numbers, and the README recommends checking each one even though the anti-hallucination rules exist. That combination of rules and a warning is the honest position: a regex can flag a vague citation, but it cannot confirm that a real paper exists. The clear wrong-tool cases follow from that. If you need the citation itself to be correct without checking, this is not the tool. If your field is not in the 19 disciplines covered by the terminology table, or your discipline has contested translations that the table resolves differently from your supervisor's preference, the terminology rule will flag correct text. And if you are writing in English rather than Chinese, the English translation reference and the bilingual terminology table are the relevant parts, but the examples, the formatting rules for Chinese footnotes and the register rules are all built around a Chinese-language paper.

Editorial conclusion

Adopt humanities-thesis-skill if you write humanities and social science papers with an AI assistant and want a method guide, a literature search tool and a deterministic pass over your prose that flags vague citations, weak connectives and inconsistent terminology before a supervisor does. Do not adopt it as a paper writing service, since the project states plainly that it assists thinking and checking rather than authoring, and do not rely on its Chinese literature search, since the Chinese platform sources are marked experimental and the recommended workflow is for you to search and export the results yourself. Before you trust the reviewer, read the R1 to R4 rules in SKILL.md, verify the reported citations by hand as the project advises, and confirm the terminology table covers your discipline and your field's preferred translation of contested terms.

Frequently asked questions

Official sources

1. ganzhi-black/humanities-thesis-skill on GitHub
2. Issues
3. License: MIT
4. README