-
Notifications
You must be signed in to change notification settings - Fork 0
Contributing
So you're thinking about contributing to the humanities-writing-companion. Welcome — genuinely. This page is the friendly, walk-you-through-it version of the contributor guide. For the canonical, terse-and-authoritative text, see the root CONTRIBUTING.md. Where the two ever disagree, the root file wins.
Most "how to contribute" guides jump straight to forking and pull requests. We're going to start somewhere else, because this project is a little unusual.
This skill is opinionated — and proudly so. It makes three bets, and every module in it is shaped by them:
- Intellectual dialogue over surface polishing. The skill cares whether your argument holds up far more than whether your commas are tidy. It deliberately works on the highest unresolved layer first (argument → concept → structure → expression → format), which means its early feedback often won't make your prose "look" nicer — it'll make you see the problem you'd rather not.
- Engineering rigor over anecdotal heuristics. Version control, revision logs, verification checklists, resumable sessions — the skill borrows real cognitive architecture from software engineering so a long writing project can survive months of interruptions.
- The author's voice over a standardized academic register. "My hand writes my voice." The skill's job is never to launder your prose into smooth, anonymous academic English. It's to keep you in the text — including the asymmetries, hesitations, and odd leaps that make the writing yours.
If you'd like the full reasoning behind these positions, docs/design-philosophy.md lays it all out — it's the design stance your contribution has to fit.
So here's the honest framing: a contribution to this project is as much about fit as about code. A technically clean PR that quietly turns the skill into a general-purpose polisher isn't a good contribution here — it's a fork. That's completely fine! But knowing the difference up front saves everyone time and disappointment.
One more boundary worth knowing: this skill does not handle the empirical research pipeline — literature search, data collection, methodological compliance, and so on. That's the domain of academic-research-skills. This skill is about writing voice, argumentative texture, and prose development in the humanities. Before you propose something, it's worth a quick gut-check: does it live inside that scope?
The skill grew out of one person's real humanities dissertation project. That's its strength — it has a fairly accurate grasp of what humanities authors actually do, instead of guessing in the abstract. But it's also its limitation: its initial shape carries that one project's disciplinary leanings, and it can't possibly know how it behaves in your field until someone from your field actually uses it.
That's where you come in. Generality, in this project's view, should arise from the intersection of many particulars — not from a hollow, abstracted "general framework." Every discipline that tests it, every unexamined phrase someone catches, every file that gets its missing language filled in, moves the skill closer to actually serving the whole humanities. Contributing here isn't busywork on someone else's tool; it's adding your particular to the intersection.
Here's where help actually moves the needle, roughly most-needed first.
You don't need to write any code for this one. The most useful contribution is simply:
- Use the skill for real in your own discipline or writing project.
- Report back which modules work well and which ones just don't fit your field.
- Propose discipline-specific extensions where you hit a wall — e.g. Latin verification for medieval studies, material-culture analysis for art conservation, field-note handling for ethnomusicology.
Honest "this didn't fit my discipline" reports are gold. They're how the design grows up amid more particulars instead of ossifying around its origin project. There are test scenarios grouped by discipline in docs/cross-domain-testing.md, and you can browse what's been mapped so far on the Discipline Guides wiki page.
references/ai-trace-checklist.md is the skill's "defense in depth" against unexamined prose. If you notice new unexamined expression patterns in your own writing — not just AI clichés, but discipline-specific formulae and the inertia that builds up from heavy theory reading — a PR to expand the checklist is very welcome. These are small, high-value additions and a great first contribution.
SKILL.md and the README already exist in both languages (SKILL.md / SKILL.zh.md, README.md / README.zh.md). But the supporting files under references/ (ai-trace-checklist, project-management, target-reader-profile-template) and the comments in scripts/ are still mostly Chinese-only. Translating them into English is a high-value contribution.
A couple of translation principles, because this is subtler than it looks:
- The Chinese cliché list in
ai-trace-checklist.md(e.g. "值得注意的是") needs the equivalent English clichés added (e.g. "It is worth noting," "It should be noted") — not literal translations, but the real filler phrases of English academic prose. - Where the citation quick-reference touches conventions beyond GB/T 7714, handle them according to English academic norms rather than transliterating the Chinese guidance.
The skill currently has 11 working modes (A–K). If you've found a high-frequency writing scenario that none of them covers, you can propose a new mode. But the bar is real — a new mode must clear all three of these:
- It is mechanically distinct from every existing mode (not a rename or restatement of one).
- It has independent input requirements and output format.
- It comes with at least one concrete use case plus its expected effect.
If you can't articulate all three, it's probably an extension of an existing mode rather than a new one. (And because modes interlock, new ones always start with an issue — see Submission process below.)
The skill's citation config assumes the author picks a style during onboarding (APA / Chicago / MLA / GB/T 7714 / journal-specific). If you'd like a particular standard to have deeper built-in support — say, auto-generating a reference list that complies with GB/T 7714's numeric sequential system — that's a welcome proposal.
The scripts/ directory holds a few small tools, and there's room for more. Ideas that fit:
- Paragraph-coherence detection (based on repeated sentence-initial / sentence-final vocabulary).
- Concept-drift detection (how the contextual frequency of a term shifts across chapters).
- Citation-density analysis (citation density per section, flagging anomalous passages).
The one hard rule: new scripts must be zero- or low-dependency — zsh, the Python 3 standard library, or at most one or two common packages — and follow the design principles in scripts/README.md. The skill is meant to run anywhere, so heavy dependency trees are a non-starter.
Curious where all of this is headed? The Roadmap page tracks what's planned and what's open.
This isn't a "these ideas are bad" list. They're all perfectly reasonable things to want — they just pull against the skill's design stance, so proposing them doesn't guarantee a merge. Better to know now than after you've written the PR.
- ❌ Making the skill "general-purpose." A "general polishing mode," or extending it to empirical social science or STEM. The skill is deliberately scoped to the humanities, thought-first, voice-preserving — it doesn't try to please every writing scenario. For an empirical research pipeline, academic-research-skills is the right home.
- ❌ Replacing existing modules with runtime LLM calls. The working modes are described as plain-text prompts on purpose. That's exactly what lets the skill run at any Claude entry point — Agent SDK, Claude Code, Claude.ai — without special plumbing. Baking in runtime model calls would break that portability.
- ❌ "AI smart-polish" features. The whole skill is a rejection of the "AI auto-polishes your draft" narrative. Polishing here is meant to be an author-driven, dialogic process, not a one-click clean-up.
- ❌ Paid / subscription integrations. The skill is an open-source public good, and it stays that way.
If your idea lands here but you genuinely think it belongs, don't just submit it quietly — open a discussion and make the case at the level of design philosophy. That argument is welcome; a silent PR that assumes the stance away is not.
Typos, doc fixes, small additions to the ai-trace-checklist — open a pull request directly with a one-line rationale. No ceremony needed.
New modes, or major revisions to SKILL.md? Please open an issue to discuss before you write the PR.
Here's why this matters and isn't just bureaucracy: SKILL.md and SKILL.zh.md are each around 900 lines, and the sections genuinely interlock. A large PR dropped in cold can easily break the existing design without meaning to. (Concrete example: Mode G, "blind-read checking," deliberately does not read the _writing-config/ files. That's by design — it's what makes the blind read blind — not an oversight to be "fixed.") An issue first lets us catch that kind of interaction before you've sunk hours into a patch.
When you open that issue, it helps enormously to spell out:
- The specific writing-scenario problem you want to solve.
- Which existing module or rule falls short (cite SKILL.md line numbers if you can).
- Which other parts of SKILL.md your change would touch — the interlock check.
- How you'll verify the change. How will you know it's correct?
This one trips people up, so it gets its own heading. Any substantive change to SKILL.md must also change SKILL.zh.md, keeping the two languages consistent. The same goes for README.md / README.zh.md. A PR that touches only one language version will be asked to complete the other before it can merge. The two languages are a matched pair, not an original-plus-translation — please keep them in step.
(Pure translation work, of course, is the exception — that's the point of the 🥉 bilingual-completion track above.)
Not strictly enforced, but it makes review much smoother if you:
- Name which section or module you changed.
- Give one line on why.
- If you touched several coupled spots in SKILL.md, list them.
A good example:
ai-trace-checklist: add "over-conceptualization" as a seventh unexamined pattern
Repeated real-world testing shows that AI tends to elevate everyday phrasing
into jargon ("this shows" -> "this phenomenon shows, at the epistemological
level"). This pattern does not fit any of the existing six categories, but it
appears very frequently.
Three simple principles:
- Scholarly critique is welcome; personal attacks are not. Argue with the idea, not the person.
- Every disciplinary tradition deserves respect. The "my discipline is the only real scholarship" posture isn't welcome here.
- The skill serves the author's thinking. Any proposal that would weaken the author's cognitive agency — say, turning the author into a blind rubber-stamp for AI output — will not be accepted. That's the line.
By contributing, you agree to release your contribution under the CC BY-NC 4.0 license.
Note: As of 2026-05-19, this project moved from MIT to CC BY-NC 4.0. New contributions fall under CC BY-NC 4.0 — meaning your contribution may also be used for non-commercial purposes only. If that gives you pause, please open an issue to talk it through before submitting a PR.
- 📜 The canonical text: root CONTRIBUTING.md
- 🧭 The design stance your contribution must fit: docs/design-philosophy.md
- 🗂️ Discipline Guides — see where each field stands
- 🛣️ Roadmap — what's planned and what's open
humanities-writing-companion · CC BY-NC 4.0 · DOI 10.5281/zenodo.20280773 · by Shen Cong (沈聪)
📘 English
Guides
- Getting Started
- The 11 Working Modes
- Paper End-to-End
- Discipline Guides
- FAQ & Troubleshooting
- Citation & Writing Tools
About the project
📗 中文
指南
关于项目