writing-commenter
Skill4 starsChanged 7 months agoMITView on GitHub
Review research writing by leaving inline comments on logic, notation, narrative flow, positioning, and editorial impact. Use when Codex needs to annotate a paper or draft with reader-facing comments instead of silently rewriting it, especially for argument structure, symbol consistency, and publication-oriented presentation.
In this repository8 other files it gives its agents.
- inline-paper-criticSkill
- literature-searchSkill
- manuscript-reviewSkill
- mathematical-enhancerSkill
- math-ocrSkill
- scientific-presenterSkill
- scientific-simplifierSkill
- tikz-figure-builderSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 7 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Use this skill when the main job is to comment on a manuscript rather than to silently edit it.
- Distinctive: line 14
Read the full manuscript before commenting.
- Distinctive: line 19
Keep strict scope within the chosen mode.
- Distinctive: line 20
Prefer inline comments that point to concrete issues and propose actionable fixes.
- Distinctive: line 24
Keep the comments self-contained and compile-safe when they live inside LaTeX.
- Distinctive: line 29
Prefer fewer, higher-signal comments over annotating every sentence.
- Distinctive: line 32
If the document already uses an inline comment macro, match its style and syntax correctly.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Writing Commenter
When to use this skill
Use this skill when the main job is to comment on a manuscript rather than to silently edit it. It is suited to three distinct review modes: logical-flow review, notation review, and editorial elevation where the author should see the reasoning behind suggested changes.
Workflow
- Read the full manuscript before commenting. Understand the paper's argument, notation, structure, and current maturity level.
- Choose the review mode up front unless the user explicitly asks for a mixed pass:
- logical flow: structure, transitions, narrative coherence, balance of explanation
- notation: symbol consistency, definition order, convention conflicts, graceful renaming
- editorial elevation: title, abstract, framing, audience fit, rhetorical rhythm, figure-caption storytelling
- Keep strict scope within the chosen mode. Do not drift into mathematical correctness, generic line edits, or copyediting unless the user asked for that.
- Prefer inline comments that point to concrete issues and propose actionable fixes. If the document already has an annotation convention, preserve it.
- In logic mode, comment where the reader loses the thread: weak transitions, misplaced paragraphs, unsupported jumps, and broken narrative arc.
- In notation mode, comment where symbols are inconsistent, reused confusingly, or introduced too late, and prefer graceful solutions that minimize document-wide churn.
- In editorial mode, comment where the paper undersells its contribution, flattens important ideas, fails to position itself for likely reviewers, or misuses figures, tables, and captions as mere decoration.
- Keep the comments self-contained and compile-safe when they live inside LaTeX. The document should remain readable and buildable with the comments present.
Quality Bar
- Comments should be specific enough that an author can act on them immediately.
- Prefer fewer, higher-signal comments over annotating every sentence.
- Distinguish local fixes from systemic issues. Do not pretend a document-wide reorganization is a one-line tweak.
- Preserve the author's voice and technical content; the goal is to diagnose and guide, not to overwrite reflexively.
- If the document already uses an inline comment macro, match its style and syntax correctly.
- For a mixed-mode review, still label the issue mentally by mode so the feedback does not blur into generic “make it better” commentary.
For a stricter pass over comment discipline, issue selection, and compile-safe inline annotations, use references/commenting-checklist.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

