All skills
softaworks avatar

/writing-clearly-and-concisely

@1c0662a
by softaworkssoftaworks/agent-toolkit2.5k stars
230

Use when writing prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Applies Strunk's timeless rules for clearer, stronger, more professional writing.

Use this Skill: https://skilld.dev/gh/softaworks/agent-toolkit/writing-clearly-and-concisely

This session only. Nothing lands on disk.

elements-of-style04-a-few-matters-of-form.md

≈1.2k tokens on demand. Your agent reads this file only when SKILL.md points to it.

IV. A Few Matters of Form

Headings. Leave a blank line, or its equivalent in space, after the title or heading of a manuscript. On succeeding pages, if using ruled paper, begin on the first line.

Numerals. Do not spell out dates or other serial numbers. Write them in figures or in Roman notation, as may be appropriate.

August 9, 1918 (9 August 1918)

Rule 3

Chapter XII

352nd Infantry

Parentheses. A sentence containing an expression in parenthesis is punctuated, outside of the marks of parenthesis, exactly as if the expression in parenthesis were absent. The expression within is punctuated as if it stood by itself, except that the final stop is omitted unless it is a question mark or an exclamation point.

I went to his house yesterday (my third attempt to see him), but he had left town.

He declares (and why should we doubt his good faith?) that he is now certain of success.

(When a wholly detached expression or sentence is parenthesized, the final stop comes before the last mark of parenthesis.)

Quotations. Formal quotations, cited as documentary evidence, are introduced by a colon and enclosed in quotation marks.

The provision of the Constitution is: “No tax or duty shall be laid on articles exported from any state.”

Quotations grammatically in apposition or the direct objects of verbs are preceded by a comma and enclosed in quotation marks.

I recall the maxim of La Rochefoucauld, “Gratitude is a lively sense of benefits to come.”

Aristotle says, “Art is an imitation of nature.”

Quotations of an entire line, or more, of verse, are begun on a fresh line and centered, but need not be enclosed in quotation marks.

Wordsworth's enthusiasm for the Revolution was at first unbounded:

Bliss was it in that dawn to be alive,

But to be young was very heaven!

Quotations introduced by that are regarded as in indirect discourse and not enclosed in quotation marks.

Keats declares that beauty is truth, truth beauty.

Proverbial expressions and familiar phrases of literary origin require no quotation marks.

These are the times that try men's souls.

He lives far from the madding crowd.

The same is true of colloquialisms and slang.

References. In scholarly work requiring exact references, abbreviate titles that occur frequently, giving the full forms in an alphabetical list at the end. As a general practice, give the references in parenthesis or in footnotes, not in the body of the sentence. Omit the words act, scene, line, book, volume, page, except when referring by only one of them. Punctuate as indicated below.

In the second scene of the third act In III.ii (still better, simply insert III.ii in parenthesis at the proper place in the sentence)

After the killing of Polonius, Hamlet is placed under guard (IV.ii. 14).

2 Samuel i:17–27

Othello II.iii. 264–267, III.iii. 155–161.

Syllabication. If there is room at the end of a line for one or more syllables of a word, but not for the whole word, divide the word, unless this involves cutting off only a single letter, or cutting off only two letters of a long word. No hard and fast rule for all words can be laid down. The principles most frequently applicable are:

(a) Divide the word according to its formation:

know-ledge (not knowl-edge); Shake-speare (not Shakes-peare); de-scribe (not des-cribe); atmo-sphere (not atmos-phere);

(b) Divide “on the vowel:”

edi-ble (not ed-ible); propo-sition; ordi-nary; espe-cial; reli-gious; oppo-nents; regu-lar; classi-fi-ca-tion (three divisions allowable); deco-rative; presi-dent;

(c) Divide between double letters, unless they come at the end of the simple form of the word:

Apen-nines; Cincin-nati; refer-ring; but tell-ing.

(d) Do not divide before final -ed if the e is silent:

treat-ed (but not roam-ed or nam-ed).

The treatment of consonants in combination is best shown from examples:

for-tune; pic-ture; sin-gle; presump-tuous; illus-tration; sub-stan-tial (either division); indus-try; instruc-tion; sug-ges-tion; incen-diary.

The student will do well to examine the syllable-division in a number of pages of any carefully printed book.

Titles. For the titles of literary works, scholarly usage prefers italics with capitalized initials. The usage of editors and publishers varies, some using italics with capitalized initials, others using Roman with capitalized initials and with or without quotation marks. Use italics (indicated in manuscript by underscoring), except in writing for a periodical that follows a different practice. Omit initial A or The from titles when you place the possessive before them.

The Iliad; the Odyssey; As You Like It; To a Skylark; The Newcomes; A Tale of Two Cities; Dickens's Tale of Two Cities.

Source: SKILL.md on GitHub

No alerts16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    The skill is completely safe. It contains documentation and reference materials based on William Strunk Jr.'s 'The Elements of Style' and Wikipedia guidelines to help the AI agent write clearer, more concise prose and avoid generic AI writing patterns.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    1/8 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 1c0662a. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 months ago.

Dormantupdated 9 months ago
  • Documentation
  • writing
  • copyediting
  • prose
  • commit-messages
  • error-messages
  • ui-text
  • clarity
  • strunk

README badge

README badge for softaworks/agent-toolkit/writing-clearly-and-concisely

Applies Strunk's timeless grammar and composition rules to prose written for humans—documentation, commit messages, error messages, UI text. Includes sections on active voice, concrete language, concision, and patterns to avoid in AI-generated writing.

Generated from the current SKILL.md.

When should I use this skill versus general writing advice?
Use this skill when writing prose for humans to read: documentation, commit messages, error messages, UI copy, reports, or any explanation. It applies Strunk's timeless grammar and composition rules plus patterns to avoid in AI-generated text.
Does this skill help with code comments?
Yes. The skill applies to any prose humans will read, including comments. The rules for active voice, concrete language, and omitting needless words improve technical explanations in code.
What if I have limited context and can't load the entire skill?
Load a single section file instead. The skill provides a limited-context strategy: dispatch a subagent with your draft and the relevant section (e.g., `03-elementary-principles-of-composition.md` for most tasks), which costs ~1,000-4,500 tokens instead of loading everything.
Does this skill catch grammar errors or focus on style?
Both. It covers elementary grammar and punctuation rules (commas, possessives, independent clauses) plus composition principles like active voice, concrete language, and word placement. It also flags AI writing patterns like puffery and empty phrases.

Generated from the current SKILL.md. These answers refresh after source changes.