agentleFS
texra-aitexra-ai/texra-scientific-skills/skills/writing-commenter/SKILL.md

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.

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
  1. Distinctive:

    Use this skill when the main job is to comment on a manuscript rather than to silently edit it.

    line 10
  2. Distinctive:

    Read the full manuscript before commenting.

    line 14
  3. Distinctive:

    Keep strict scope within the chosen mode.

    line 19
  4. Distinctive:

    Prefer inline comments that point to concrete issues and propose actionable fixes.

    line 20
  5. Distinctive:

    Keep the comments self-contained and compile-safe when they live inside LaTeX.

    line 24
  6. Distinctive:

    Prefer fewer, higher-signal comments over annotating every sentence.

    line 29
  7. Distinctive:

    If the document already uses an inline comment macro, match its style and syntax correctly.

    line 32

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Read the full manuscript before commenting. Understand the paper's argument, notation, structure, and current maturity level.
  2. 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
  3. Keep strict scope within the chosen mode. Do not drift into mathematical correctness, generic line edits, or copyediting unless the user asked for that.
  4. Prefer inline comments that point to concrete issues and propose actionable fixes. If the document already has an annotation convention, preserve it.
  5. In logic mode, comment where the reader loses the thread: weak transitions, misplaced paragraphs, unsupported jumps, and broken narrative arc.
  6. In notation mode, comment where symbols are inconsistent, reused confusingly, or introduced too late, and prefer graceful solutions that minimize document-wide churn.
  7. 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.
  8. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.