agentleFS
geemusgeemus/hax-yax/.agents/skills/refine-prose/SKILL.md

refine-prose

Skill4 starsChanged 6 months agoMITView on GitHub

Polishes drafted prose for clarity, conciseness, and consistent voice before it is posted or presented. Apply after drafting any plan, review summary, or written output to catch filler phrases, passive constructions, and inconsistent terminology. Use when the user asks to polish, clean up, improve, edit, or tighten writing — also triggered by "refine this draft", "make this clearer", or "improve my writing". Also composable: other skills invoke it as a late-stage refinement step. TRIGGER when: user asks to polish, edit, or improve prose. DO NOT TRIGGER when: user asks to format or lint code (use language-specific tools instead), or when this skill is already running as a composable step within another skill.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 9 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    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:

    After drafting a plan, proposal, or structured document

    line 26
  2. Distinctive:

    After writing a PR review summary or set of review comments

    line 27
  3. Distinctive:

    Before presenting any intentionally drafted output — a plan, review, proposal, or multi-sentence response — to a user

    line 28
  4. Distinctive:

    Remove words and phrases that add length without meaning.

    line 37
  5. Distinctive:

    Remove redundant restatements: if the same idea appears twice within a paragraph, keep the clearer instance.

    line 62
  6. Distinctive:

    Ensure each sentence has one main idea.

    line 63
  7. Distinctive:

    All items in a bulleted or numbered list must use the same grammatical form.

    line 67
  8. Distinctive:

    If the first item starts with a verb ("Run the tests"), all items must start with a verb.

    line 69
  9. Distinctive:

    If the first item is a noun phrase ("Test coverage"), all items must be noun phrases.

    line 70

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

Refine Prose

Polishes a draft for clarity, conciseness, and consistent voice. Apply after producing any written output — a plan, review summary, comment, or document — before presenting or posting it.

When to apply

  • After drafting a plan, proposal, or structured document
  • After writing a PR review summary or set of review comments
  • Before presenting any intentionally drafted output — a plan, review, proposal, or multi-sentence response — to a user
  • Whenever explicitly invoked via /refine-prose on arbitrary text

Instructions

Work through each check in order. Apply fixes silently — do not narrate the edits. Apply prose rules only to prose — skip code blocks, inline code, tables with technical data, and structured output such as YAML frontmatter. When no changes are needed, return the original text unchanged.

1. Cut filler phrases

Remove words and phrases that add length without meaning. Common culprits:

RemoveReplace with
"in order to""to"
"due to the fact that""because"
"at this point in time""now"
"it is worth noting that"(delete or keep the fact)
"please note that"(delete; just state the fact)
"as mentioned above/below"(delete or use a direct reference)
"basically", "essentially", "literally"(delete unless they carry meaning)
"very", "really", "quite", "rather"(delete or strengthen the noun/verb)

2. Prefer active voice

Rewrite passive constructions as active where the actor is known and the active form is clearer.

  • "The tests were run by CI" → "CI ran the tests"
  • "The config will be updated" → "Update the config" (in instructions)

Passive is acceptable when the actor is unknown, unimportant, or when convention demands it (e.g. "was introduced in v2").

3. Tighten sentences

  • Break sentences longer than ~30 words into two unless the length is necessary for precision.
  • Remove redundant restatements: if the same idea appears twice within a paragraph, keep the clearer instance.
  • Ensure each sentence has one main idea.

4. Enforce parallel structure in lists

All items in a bulleted or numbered list must use the same grammatical form.

  • If the first item starts with a verb ("Run the tests"), all items must start with a verb.
  • If the first item is a noun phrase ("Test coverage"), all items must be noun phrases.

5. Standardize terminology

Within a single document, use one term for each concept consistently. Use whichever term already appears more often; apply the defaults below only when no term has been established yet.

Default preferences:

  • "pull request" in formal prose; "PR" is acceptable in informal or space-constrained contexts
  • Oxford comma in lists of three or more items
  • Sentence case for headings unless the document already uses title case throughout

6. Match formality to context

  • Plans and proposals: formal, third-person where possible, no contractions
  • Review comments: direct and specific; second person ("you") is appropriate; contractions acceptable
  • Instructions: imperative mood, second person implicit ("Run tests", not "You should run tests")

Composability

This skill is designed to be referenced by other skills as a late-stage refinement step. When wired in as a composable step, run it silently and present only the refined output — do not announce that you are running it.

Callers reference it with a line such as:

Apply the refine-prose skill to the draft before presenting.

Examples

Direct invocation on user-supplied text:

/refine-prose
The reason that this is basically very important is due to the fact that the tests were being run by CI on a nightly basis, and it is worth noting that failures were being ignored.

Refined output:

This matters because CI runs the tests nightly and ignores failures.

(Applied: cut filler phrases "basically", "due to the fact that", "it is worth noting that"; rewrote passive "were being run by CI" and "were being ignored" as active.)

Composable invocation (from another skill):

Apply the `refine-prose` skill to the review summary before presenting it. Run it silently — do not announce the refinement step.

When no changes are needed: Input is already clear and concise — return the original text unchanged with no commentary.

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.