Discern

Scientific manuscript review and editing for Codex and Agent Skills-compatible assistants.

Improve the argument, not merely the wording.

Discern helps an agent assess scientific rigor, argument structure, completeness, information density, and academic expression. It provides one skill with seven composable modes, shared review standards, and references loaded as needed. It preserves scientific uncertainty and authorial voice, and accepts that sound text may need no change.

Install in Codex

Discern is a skills-only plugin: one manuscript-review skill, seven modes, and bundled review guidance. It adds no MCP server, external service, hooks, or runtime dependencies. Use a Codex client with plugin marketplace support.

From a local checkout

Register this checkout as a marketplace, using its absolute path:

codex plugin marketplace add /absolute/path/to/Discern

Open the plugin browser in your Codex client, select the Discern marketplace, and install Discern. Restart the desktop client if the new marketplace is not visible, then start a new chat in your manuscript project.

$discern review main.tex, including the available supplement. Report in Chinese.

Registration makes the marketplace discoverable; install and enable the plugin before invoking its skill. The bundled marketplace is named discern-marketplace, and its plugin is named discern.

From a published repository

Register the Discern repository as a marketplace:

codex plugin marketplace add Roy-Kid/Discern

Then install Discern from that marketplace in the plugin browser. Repository marketplace distribution is separate from listing in the public Plugins Directory; this README does not imply an approved public listing. See OpenAI's plugin packaging documentation.

Other Agent Skills hosts

The existing skill can also be installed independently with the Vercel Skills CLI. From this checkout, list it:

npx skills add . --list

Install into a manuscript project using the path to your checkout:

cd /path/to/manuscript-project
npx skills add /path/to/Discern --skill discern --agent claude-code codex

Choose only the agents you use. These commands use project scope. Alternatively, copy the complete skills/discern directory, including references/, into your host's supported skills directory. Choose either plugin installation or direct skill installation for a given Codex setup to avoid duplicate skill entries. Running the Vercel CLI through npx requires Node.js; Discern itself does not.

Quick start

Give Discern the manuscript and a concrete task. Include the bibliography, figures, and supplement when they matter to the review.

$discern review main.tex and supplement.tex; prioritize issues that affect the conclusions.
$discern verify whether references.bib supports the novelty claim in the Introduction.
$discern revise issues R2 and R4 from the review above; preserve uncertainty and citation keys.

Start with review for diagnosis, then request revise for selected findings. Review does not edit manuscript files. Findings include locations, evidence, severity, confidence, and recommendations; coverage explains what could and could not be checked. Reports follow your requested language, while revisions preserve the manuscript's language.

Use

The shared convention is discern <mode> <target> [natural-language constraints]. Invocation syntax depends on the host:

# Claude Code
/discern review main.tex and its supplement

# Codex
$discern review main.tex and its supplement

# Natural language
Use the discern skill to review the argument in this manuscript.

The modes are instructions interpreted by the host, not shell commands or separately installed skills.

Examples below use Codex notation; use /discern in Claude Code or natural language in another host as appropriate:

$discern review main.tex, including the available SI
$discern critique the contribution and reasoning in sections 1 and 4
$discern audit definitions, numerical consistency, and citations in main.tex
$discern verify whether reference [12] supports the causal claim in paragraph 3
$discern revise issues R2 and R4 from the review above, preserving the claim scope
$discern distill repeated background across the Introduction and Discussion
$discern polish sections/results.tex without changing scientific meaning

A general review request defaults to review. Clear editing intent selects the relevant editing mode even without an explicit mode name. Targets may be files, sections, dimensions, pasted text, or issue IDs from a specified report. Discern uses the current conversation and project to locate the manuscript, asking when materially different candidates remain.

Compose operations

$discern review main.tex, then revise the confirmed major issues using available evidence
$discern distill the Discussion, then polish only the changed passages
$discern verify whether the current revision resolves R3 from reviews/my-review.md

Review and verification are read-only with respect to the manuscript. Editing separates diagnosis, repair, and validation within the same authorized task; it does not require another approval round. “Suggest only” limits an editing request to suggestions. Old findings are rechecked against current text before changes are applied.

distill does not target a compression percentage. polish does not silently restructure the paper. Missing data, methods, or references remain unresolved until evidence is available.

Editing judgment

Discern ties a reported defect to a concrete consequence for understanding, assessment, or inference. Optional improvements and verification limits are reported separately. When revising, it distinguishes wording problems from misplaced content, an inappropriate level of explanation, and gaps in reasoning.

New explanations are integrated with existing passages, preserving unique evidence and necessary qualifications. Revision checks assess whether the original problem is resolved and whether the change introduces repetition, misplaced emphasis, stronger claims, or loss of authorial voice. Confirmed editorial decisions and their reasons remain relevant across turns unless superseded; no separate tracking file is required.

Scientific limitations belong in the manuscript when they affect interpretation. The reviewer's lack of access to materials belongs in the review report. Completing an edit does not establish that the underlying analysis has been reproduced or that the whole manuscript is ready for submission.

Review coverage and reports

The Review Index covers ten dimensions:

• Research Framing
• Narrative & Flow
• Redundancy
• Completeness
• Scientific Reasoning
• Methodology & Results
• Figures & Equations
• Citations & Literature
• Academic Writing
• Global Consistency

A full review considers every dimension; focused modes use the relevant subset. The agent maps the argument and checks repeated ideas across sections where the scope calls for it. Necessary restatement and consistent technical vocabulary are preserved. Formulaic prose is assessed for its actual effect, never used to infer AI authorship.

Reports contain Global Assessment, prioritized Localized Issues, and Coverage. Each issue has a report-local ID, precise location and excerpt, evidence and reasoning, severity, confidence, and a minimal recommendation. Severity (critical, major, minor) describes consequence; confidence (high, medium, low) describes evidence strength. Low-confidence suspicions remain pending checks, not supported defects. Duplicate findings are merged and contradictory findings rechecked.

Coverage states what was checked, partially checked, inapplicable, or not checked. Citation identity, metadata correctness, and substantive support are separate checks. A local check does not establish whole-paper correctness.

Reports appear in the conversation unless you ask to save them. When no destination is given for a requested save, Discern uses reviews/discern-<mode>-<date>.md and a suffix to avoid overwriting an existing report. Editing reports connect actual changes to issues and describe validation and unresolved items.

Inputs and host capabilities

LaTeX and Markdown are the primary formats, including linked manuscript files, bibliographies, figures, tables, and supplements. Discern follows relevant LaTeX includes and preserves commands, labels, citation keys, and cross-references when editing.

PDF review depends on the host's extraction and visual tools; captions alone do not establish that a figure was checked. DOCX is best effort through existing host tools, outside the v1 guarantee. No document converter is bundled.

External verification uses available host search and browsing as needed, subject to user constraints, and prioritizes original sources. Without network access or full text, the report identifies the evidence limit. A resolving DOI does not prove that a citation supports a claim. Missing SI limits the review; it does not automatically make the manuscript defective.

Skill instructions and project documentation are in English. Reports follow the user's language; revisions preserve the manuscript's language unless translation is requested. Criteria adapt to the discipline and article type rather than assuming one journal or research design.

The host decides task decomposition, tool use, and whether agents are useful. Discern imposes no subagent counts, roles, execution order, parallelism, or reasoning depth.

Development and validation

The reusable skill is skills/discern; all operational references are bundled within that directory. The root plugin manifest packages that same skill, and the marketplace catalog points to the repository root. Keep one canonical skill rather than copying it into a second plugin tree. Maintain shared rules in one place and link to dimension guidance only when relevant. No generated variants or custom installer are needed.

V1 acceptance consists of skill-format validation, local-link and discovery checks, an isolated installation check, and manual inspection of routing, evidence boundaries, reporting, and editing constraints. The repository does not include a synthetic manuscript suite or a behavioral evaluation framework. Structural checks do not establish scientific review accuracy or equivalent behavior across models and hosts.

For editorial rule revisions, revisit real revision cases: did the finding identify a concrete consequence, did the edit resolve it, and did essential information and earlier decisions survive? Look for unnecessary additions, repeated user corrections, and edits to already adequate text. Report actual behavioral trials separately from inspection of the instructions.

Before publishing

• Confirm the release version and publisher metadata in plugin.json, and choose a license before inviting public reuse. No license file is currently bundled.
• Register the published marketplace from a clean Codex setup, install Discern, and verify that $discern is discoverable in a new chat.
• Try a read-only review and an authorized revision on a disposable manuscript copy; check referenced guidance is available from the installed package.
• Record the client version and actual installation results. JSON and link checks alone do not verify the marketplace UI or model behavior.

Design references

These projects informed the design; Discern does not depend on or copy their implementations:

Rigorous in judgment. Minimal in intervention. Precise in reporting.