Use
No special command is needed: the host selects the skill when a task matches. Name it (“Use lucid-writer to…”) to force it.
Prompts for daily work
Tighten prose:
Tighten this paragraph by ~20%. Preserve scientific meaning, numbers, citations, and caveats.Draft Results:
Turn Figure 3, this model table, and these notes into a concise Results subsection. Do not add literature or causal interpretation.Revise a Discussion:
Restructure this Discussion around the main answer. Separate observation, interpretation, alternatives, limitations, and implications.Review a full manuscript:
Audit the manuscript against the figures, tables, and supplement. Prioritize evidence and argument problems before prose. Do not rewrite yet.Remove generic prose:
Remove generic AI/LLM-sounding prose. Preserve technical terminology, claim strength, uncertainty, numbers, and citations. Do not optimize for AI detectors.More examples are in examples/quick-start.md.
A review ends with a Not checked list: what the review could not see, test or chose to skip, such as figure images or sources that were not supplied.
Always-on mode
In Claude Code, the plugin can apply its prose rules to every reply, not only to writing tasks. It is off by default.
| Command | Effect |
|---|---|
/lucid-writer prose |
plain-prose rules for chat and commit messages. No evidence rules, so not for scientific claims. lite still works for one version |
/lucid-writer full (or on) |
prose plus the evidence ceiling for any finding you state, and a voice for deliverables |
/lucid-writer off |
turn always-on off |
/lucid-writer status |
show the current mode and flag path |
A change applies from the next session start or /clear. Saying “stop lucid-writer” turns it off for the rest of the session only. The mode lives in ~/.claude/.lucid-writer-mode (or under $CLAUDE_CONFIG_DIR). The rulesets are hooks/rules/prose.md and hooks/rules/full.md; together they add about 4,900 characters to each session.
In full mode the evidence ceiling applies everywhere, but the voice applies only to deliverables: manuscripts, abstracts, reports, response letters, text written into .md, .tex, .qmd or .docx files, and text pasted for revision. Chat and commit messages follow the plain-prose rules. The hook loads the first voice it finds: .lucid-writer/voice.md in the project, then ~/.claude/lucid-writer/voice.md, then the plain hooks/rules/voice-default.md. Each is capped at 4,000 characters. The voice sets rhythm and wording only; it cannot add claims or remove hedges.
To draft a voice from your own papers, run voice_profile.py with --out ~/.claude/lucid-writer/voice.md (or a project’s .lucid-writer/voice.md) and --author-position first|sole|other. It fills only measured fields and verbatim samples, and warns when you are not first or sole author.
full adds at most one sentence the source lacks, a design caveat or an open question, marked [AUTHOR CHECK]. Markers stay inline while drafting. Ask for final, clean or submission-ready text and they move to a list after the text.
The hooks need node on PATH and do nothing when it is missing. Always-on works in Claude Code only; Codex has no session hooks, but the skill itself works there.
Learned rules
In Claude Code, the plugin can learn your writing rules. Say “always write X” or run /lucid-writer:learn "<rule>" and it stores one proposed rule. A proposed rule does nothing until you approve it with /lucid-writer:rules approve <id>. /lucid-writer:rules also lists, rejects and retires rules.
- What it learns: style rules (wording, preferred and banned terms, voice) and evidence rules that only tighten, such as “always report confidence intervals”. A rule that loosens a fixed non-negotiable, such as allowing “drives” for correlations or skipping citation markers, is refused.
- Where rules live:
~/.claude/lucid-writer/rules.json(or under$CLAUDE_CONFIG_DIR) and, per project,.lucid-writer/rules.json. A project file loads only after you run/lucid-writer:rules trust, which records its sha256; any edit needs trust again. Until then one notice line replaces its rules. - What the model sees: active rules, one line each, under
## Learned writing rulesat session and subagent start, inproseandfullmode. The block is capped at 2,000 characters; extra rules show as “N rules not shown”. Nothing is injected when always-on is off. - Nudge: when your prompt has a correction word (always, never, don’t, do not, stop, prefer, instead of, from now on) and the last reply wrote or edited a
.md,.tex,.qmd,.docxor.txtfile, the hook adds one line asking Claude to offer/lucid-writer:learnonce. Infullmode a prompt that names a rewrite or quotes 15 or more characters also counts./lucid-writer nudge offturns it off; the flag is~/.claude/.lucid-writer-nudge. - From ratings:
/lucid-writer:learn --from-ratingstakes text pasted from the bench page (calibration and rewrite rows withread=andnote=) and proposes rules from the notes. You choose which to store.
Learning needs the hooks, so it works in Claude Code only; Codex keeps the skill without it.
Review subagents
Three read-only reviewers ship with the skill for high-stakes work. They return findings; the main agent reconciles them and owns every edit.
| Reviewer | Checks | Use it for |
|---|---|---|
| Evidence auditor | claims against analyses, figures, tables, protocols and sources | a substantial draft or claim audit |
| Skeptical reviewer | the central argument, alternatives, scope, inferential gaps, through methodological, domain, applied and statistical lenses | a Discussion, major revision or pre-submission review |
| Manuscript preflight | title, abstract, body, figures, tables and supplement for stale or contradictory content | the step just before release |
Skip them for grammar fixes and ordinary edits: they cost extra tokens and help mainly when a fresh context reduces anchoring, or when many files need review.
draft or revise with lucid-writer
↓
evidence auditor ─────┐
├─ in parallel, read-only
skeptical reviewer ──┘
↓
main agent reconciles and revises
↓
manuscript preflightThe installer places them in ~/.claude/agents/ (lucid-*.md) and ~/.codex/agents/ (lucid_*.toml); the Claude Code plugin loads them on its own. The skill works without them. Platform details are in docs/subagents.md.
Project state
For a long-running manuscript, keep a brief, a claim ledger and a decision log in the project:
python3 skills/lucid-writer/scripts/init_project.py .This creates .lucid-writer/ with brief.md, claims.csv, outline.md, decisions.md and review.md. The brief has a Known weaknesses field: limitations the authors already acknowledge, which reviewers treat as context unless the title or abstract claims more than they permit.
For stable author or team style, copy skills/lucid-writer/assets/voice-profile.md to .lucid-writer/voice.md. Voice never overrides evidence or reporting requirements.
Mechanical checks
The helpers need Python 3.11 or newer and only the standard library. On Linux and HPC systems without python on PATH, call them with python3. On RHEL 8, python3 is 3.6 and fails with SyntaxError: future feature annotations is not defined; call python3.11 instead.
# release and style cues: placeholders, causal verbs, filler
python3 skills/lucid-writer/scripts/lint.py manuscript.md
# claim ledger: header, labels, supported claims with evidence
python3 skills/lucid-writer/scripts/validate_ledger.py .lucid-writer/claims.csvThe linter is not an AI detector and does not judge scientific validity.