FAQ

🌐 English · 中文 · 🏠 Home

FAQ & Troubleshooting

Everything people ask before (and after) they start using the Humanities Writing Companion — a Claude skill for scholars in history, philosophy, literature, cultural studies, art history, religious studies, classics, and adjacent fields where prose is the argument.

New here? Start with Getting Started and The 11 Working Modes.

---

Part 1 · Frequently Asked Questions

Is this a polishing tool?

No — and that distinction is the whole point of the project.

A polishing tool starts at the bottom: grammar, sentence shape, "clarity," a uniform academic register. This skill deliberately inverts that order. It works argument first, format last:

argument → concepts → structure → expression → format

There is a hard rule baked in: do not exert effort at a lower layer while a higher layer is unresolved. If your core concept is a rhetorical label rather than an analytical tool, the skill will not "fix your commas" — it sends you back to the concept. The early feedback you get often won't make your prose look better; it makes you see what you'd rather not. That's by design.

Will it write my paper for me?

No. Its self-description is blunt: it's built not to write for you, but to read for you.

It behaves like a thinking partner, not a ghostwriter. It diagnoses across four layers — Foundation (does the argument hold?), Structure (is it unfolding well?), Paragraph (what is this paragraph doing?), Sentence (is this said right, and does it sound like you?) — and gives you the kind of critique a real humanities scholar would. It can draft new content (that's Mode C), but even then it flags AI-heavy passages and asks you to re-express them in your own voice. The author stays in the driver's seat; the skill is the demanding reader who got there first.

How is it different from plain ChatGPT or Claude with no skill?

A generic chat session has no memory of your project and no opinion about humanities writing. This skill carries, persistently across sessions:

• a style profile (your voice, learned from your real writing samples),
• a reader profile (who you're actually writing for),
• a revision log (every change, with a diff and a reason — like git commits),
• the four-layer critique and a strict top-down rule,
• discipline routing (history gets anachronism checks; philosophy gets modal-scope checks; etc.),
• an AI-trace checklist to catch unexamined patterns,
• and a citation toolchain.

Generic AI pulls toward polishing and averaging. This skill pulls the opposite way: protecting your voice, stress-testing your argument, and rehearsing the hostile reviewer.

How is it different from Paperpal / Grammarly / DeepL Write?

Tool	Their job	Where this skill diverges
Grammarly / DeepL Write	Grammar / translation polishing	It never rewrites for "clarity" at the cost of your voice. "My hand writes my voice" is a core principle, not a toggle.
Paperpal	Academic language polishing (STEM/biomed-leaning)	It's a writing architecture — 11 modes, four-layer critique, discipline routing — not a point polishing tool.
Jenni AI	Real-time autocompletion	It does thought-dialogue, not autocompletion. Real-time prediction skips the cognitive work humanities argument needs.
HyperWrite Devil's Advocate	One-shot counter-arguments	Its Mode D is a full adversarial mode with 1–5 intensity calibration, a methodology-focus sub-mode, and an anti-sycophancy concession threshold.
Thesify (Purpose-Check)	Promise-checking	Mode G is inspired by Purpose-Check but lives inside a broader four-layer workflow.

The short version: most tools are tools you put down when the task is done. This one wants to be infrastructure — the thing you work on top of across a months-long project.

Which citation styles does it support?

You declare your style during onboarding. Built-in awareness covers:

• Chicago / Turabian (most common for history and the humanities)
• MLA (literature and languages)
• APA 7th (education, psychology, some social science)
• GB/T 7714 (the Chinese national standard)
• Journal-specific formats (give it the name or a template)

Not sure which to pick? It will recommend one based on your discipline and target venue. Beyond choosing a style, the scripts/ toolchain does real work: a consistency checker (brackets, commas, connectors, EN/CN name forms, page numbers), a format converter (Chicago/MLA/APA/GB7714), and Crossref-based verification of references.

Does it need an internet connection or make runtime API calls?

The skill itself is plain text with no runtime LLM dependencies — that's a deliberate design commitment, which is why it runs at any Claude entry point (Claude Code, Claude Agent SDK, Claude.ai). SKILL.md can be dropped straight into a system prompt.

Two practical caveats:

• You still need Claude running, obviously — the skill is the instruction layer, not the model.
• One optional script, citation-verify.py, checks references against Crossref, which needs a connection. Everything else — the consistency checker, the cliché scanner, the pending-marker aggregator — is zero-dependency and works offline.

What's the design philosophy, in one paragraph?

The author handed a long essay to an AI for "polishing" and got back something that read more evenly than the original — every sentence balanced, every paragraph opening with "It is worth noting," the whole thing as cool as meeting minutes — and realized the AI hadn't removed typos, it had removed the thinking. The asymmetric judgments, the hesitations, the leaps that force two fields together — gone. So this skill is built on the opposite bet: in the humanities the author's voice carries epistemic weight (it signals which tradition you write from and which moves are yours), argument and prose are inseparable (a slack sentence is an argumentative failure), and the reviewer is real and adversarial (so the paper should meet that adversary before submission, internally). Thought first, format second; engineering rigor in service of humanistic expression; and "my hand writes my voice" as a non-negotiable.

Will it weaken my own thinking?

This is the worry the project takes most seriously, and the design pushes hard against it:

• The top-down rule keeps forcing you back to your argument instead of letting you hide in sentence-polishing.
• Mode F.coach withholds the answer on purpose — it asks you diagnostic questions first, so you build the muscle to see problems yourself. (Stated goal: "a scholar should not need the skill in five years.")
• The anti-sycophancy threshold in Mode D refuses to fold the moment you push back — a fake "you have a point" trains nothing.
• The Code of Conduct is explicit: any proposal that turns the author into a rubber-stamp for AI output will not be accepted.

The reframe the skill offers: the thing to fear is not "AI changed my voice" (every tool changes a writer) but "I accepted AI output without examination." The difference is whether you were present while it changed.

Is it really for all humanities disciplines?

It aims to be, via a three-layer discipline architecture rather than a flat list of slots:

• L1 — six main disciplines: Literature, History, Philosophy, Linguistics, Art studies, Religious studies. Each carries its own methodological concerns (history → anachronism, source handling; philosophy → conceptual derivation, modal scope; literature → close reading vs. interpretation; etc.).
• L2 — subfields that inherit their parent L1's concerns and may add their own (e.g., classical literature adds philological concerns).
• L3 — cross-disciplinary fields with explicit multi-inheritance: cultural studies, classics, intellectual history, history of science, media studies, digital humanities, gender studies, postcolonial studies, environmental humanities.

It also welcomes humanities-adjacent fields with strong humanities-style traditions — e.g., the media-ecology lineage in communication studies (Innis/McLuhan/Postman/Carey), and history/philosophy of education — while being honest that it does not serve their empirical/quantitative wings well.

Honest caveat from the design notes: the skill grew out of one specific project (a history-of-science MA thesis with a philosophical, Chinese-language, art-history-inflected bent), so it may carry that lineage's leanings and may not transplant perfectly into every field yet. Cross-discipline testing is the single most-wanted contribution. If your field isn't listed, there's a fallback: tell it your object of study and primary method, and it infers your closest L1 plus relevant overlays.

What's the relationship to academic-research-skills (ARS)?

They are complementary, not competitors — and there's a clean division of labor.

• ARS handles the empirical research pipeline: literature search, data collection, methodology compliance (PRISMA, RAISE), citation-faithfulness auditing, pipeline orchestration.
• This skill handles the writing itself: voice, argumentative texture, prose development.

The mental model: let ARS handle the pre-writing and post-writing stages; let this skill handle the writing in between. This skill explicitly does not do literature search for you (that path leads to citation hallucination and skips the irreducible work of reading). It also credits ARS directly — Mode D's "concession threshold" anti-sycophancy pattern was inspired by ARS's reviewer module. If you use both in one project, cite both.

Is it free? What license?

It's a free, open-source public good — but read the version note.

• The current license is CC BY-NC 4.0 (Creative Commons Attribution–NonCommercial 4.0): free for non-commercial use, modification, and distribution, with attribution required. Non-commercial covers academic research, teaching, personal projects, open-source derivatives, and internal research workflows.
• License change (v3.0.0, 2026-05-19): the project relicensed from MIT to CC BY-NC 4.0. Versions ≤ v2.1.0 stay under MIT and keep their original commercial rights for those specific versions. From v3.0.0 on, commercial use requires a separate license.
• Commercial use (embedding in a paid product, paid editing/consulting services using the skill, commercial SaaS integration, agency use for paying clients) needs a license from the author: shencong916@gmail.com.

Citing the skill in academic publications is always permitted, regardless of license tier — and encouraged (there's a DOI and a CITATION.cff).

---

Part 2 · Troubleshooting

The skill doesn't seem to "activate" or enter a mode

Claude Code auto-scans ~/.claude/skills/ and ./.claude/skills/ on startup, so first confirm the skill is actually installed there (and, for project-level installs, that you launched Claude from that project). After that, activation is triggered by what you say, not by a command you run.

Try a plain trigger phrase rather than an abstract request:

• English: "paper," "essay," "chapter," "dissertation," "argument," "thesis," "revise," "voice," "review my section," "stuck on writing," "devil's advocate," "reviewer attack," "research question," "literature review," "outline," "AI disclosure." Even "take a look at this paragraph" works.
• Chinese: 论文 · 写作 · 改论文 · 帮我看看这一章 · 我手写我口 · 这个论证有没有问题 · 我写不下去了 · 审稿人会怎么攻击 · 研究问题 · 文献综述 · AI 使用披露 · 帮我看看这段话.

If it still won't engage, say so directly: "Use the humanities writing companion skill to review this chapter." See Getting Started for the install steps.

The output isn't what I expected for a given mode

Usually this means a different mode fired than the one you wanted, or the mode is behaving exactly as designed and the design surprised you. A few common cases:

• You asked for a chapter review but got high-level, uncomfortable foundation critique. That's Mode B working top-down. It won't polish sentences while the argument is broken. If you genuinely only want sentence work, say "I just want Layer 4 / sentence-level help on this paragraph" (Mode A).
• Blind reading (Mode G) feels oddly mechanical and ignores quality. Correct — Mode G deliberately turns off scholarly judgment. It only checks "did you deliver what you promised?" It will not tell you whether a promise was worth making (that's Layer 1) or rewrite anything. For quality, use Mode B.
• Mode J refused to write a paragraph for you. Also by design — Mode J is plan-only; its value is the discipline of not writing. It will offer to switch you to Mode C (drafting) instead.
• You wanted drafting but got Socratic questions. Mode C listens first ("midwife, not architect"). If you want it to just produce a draft, tell it so — but expect it to flag the AI-heavy parts for you to re-voice.

Naming the mode and the layer you want is the fastest fix. See The 11 Working Modes for the full map (A–K).

It's not using my citation style or my reader profile

These live in config files the skill reads at the start of work. If it's ignoring them:

• Citation style: it should have created _writing-config/citation-style.md during onboarding. If you skipped onboarding or the file is missing/empty, the style won't apply. Just tell it: "I'm using Chicago" (or MLA / APA 7th / GB/T 7714 / a journal template), and ask it to write that to the config.
• Reader profile: Devil's Advocate (Mode D) reads _writing-config/reader-profile.md to make its three reviewers concrete (e.g., "Reviewer A plays the technology-neutralist"). If that file is empty, Mode D falls back to a discipline-generic persona and will remind you to fill it in. Fill the "primary reader" section first; you can complete the rest incrementally.
• Discipline routing seems generic: check _writing-config/discipline.md. If it's absent, the skill should ask before giving critique — but if it slipped through, the history/philosophy/etc. specific checks won't load. Re-declare your L1 (+ any L2 subfield and L3 cross-disciplinary fields).

What are the _writing-config/ files, exactly?

They're the skill's persistent memory of your project — small Markdown files it reads at the start of every session so you never have to re-explain your background. The key ones:

File	What it holds	Who reads it
style-profile.md	Your voice, learned from real samples	Everything that produces output
reader-profile.md	Who you're writing for	Mode D (to make reviewers concrete), drafting
citation-style.md	Your chosen citation format + paper-specific conventions	Citation handling, Mode F
discipline.md	Your L1 / L2 / L3 discipline declaration	Every critique (routing)
research-question.md / literature-map.md / outline.md	Mode H / I / J outputs	Downstream planning + drafting

Separately, _meta/ holds the revision log, writing progress, and interaction log (used for cross-session resumption and for Mode K's AI-use disclosure).

Two useful facts: (1) filenames can be English or Chinese — whichever matches your writing language (e.g., style-profile.md or 写作风格档案.md). (2) Mode G deliberately does NOT read _writing-config/ — that's not a bug, it's how blind reading stays "outside your internal view."

How do I switch modes mid-conversation?

Just say so — the skill is built to escalate and de-escalate, and it should tell you which layer it's working at rather than switching silently. Natural switches it understands:

• Paragraph problem turns out to be a structure problem → "let's step back to the whole chapter" (Mode A → Mode B).
• A draft chapter needs rewriting, not revising → switch to conception (Mode F → Mode C).
• Review's done, now do the line edits → (Mode B → Mode A).
• Mid-coaching, you just want the answer → "skip coaching, just give me the revision" (it respects this immediately).

If it ever changes level without telling you, ask "which layer are we working at right now?" — that's part of its expected behavior.

A mode feels too aggressive (e.g., the devil's advocate is brutal)

Devil's Advocate (Mode D) is calibrated 1–5, and you set the dial:

Level	Posture
1 · Gentle reader	Encouraging, a couple of soft concerns. For fragile/early drafts.
2 · Friendly critic	Probing but supportive.
3 · Peer reviewer	Default. Standard scrutiny, all four reviewers, anti-sycophancy on.
4 · Hostile reviewer	Adversarial, attacks every weak point. High-stakes submissions.
5 · Adversarial committee	Presses to fail; concession threshold tightens to 3-of-5. Defense rehearsal only.

If you didn't pick a level, it runs Level 3. To dial down, just say "reduce to level 2 — I'm getting overwhelmed" and it respects the request immediately, no negotiation. At Levels 4–5 it should also check in every 3–4 challenges ("continue, drop down, or take a break?").

One thing it won't do is fold just because you're frustrated. The anti-sycophancy rule means it concedes a challenge only when your rebuttal meets a real standard (citing literature, redefining a concept's scope, giving a counter-example, showing you already handled it, etc.) — because a critique that collapses under emotional pressure can't rehearse a real reviewer. If you want it to actually back off, give it substance or explicitly lower the level. And remember: when you turn on Mode D, you are asking for an unfriendly interlocutor.

---

Still stuck?

• Walk through setup in Getting Started.
• See exactly what each mode does in The 11 Working Modes.
• Found a bug, or your discipline doesn't fit? Issues and discussions are welcome — see the repo's CONTRIBUTING.md. Discipline testing is the single most valuable contribution.