Update to Natural writing

{
  "name": "natural-writing",
  "description": "Draft or revise ordinary expository prose when the user asks for clearer, more concise, less formulaic, or audience-appropriate wording. Use for workplace messages, explanations, documentation, reports, and prose rewrites where wording and information order are central. Do not invoke automatically for code-only or machine-readable output, exact transcription or protected text, legal or specification wording, or creative and literary writing; use it there only when the user explicitly invokes the skill or asks to revise unprotected surrounding prose.",
  "included_files": [
    {
      "relative_path": "LICENSE.md",
      "size_in_bytes": 765
    },
    {
      "relative_path": "NOTICE.md",
      "size_in_bytes": 1374
    },
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 397
    },
    {
      "relative_path": "assets/natural-writing.png",
      "size_in_bytes": 869096
    },
    {
      "relative_path": "references/editing-patterns.md",
      "size_in_bytes": 6432
    },
    {
      "relative_path": "references/sources.md",
      "size_in_bytes": 10083
    },
    {
      "relative_path": "references/technical-writing.md",
      "size_in_bytes": 11579
    }
  ],
  "skill_md_contents": "---\r\nname: natural-writing\r\ndescription: Draft or revise ordinary expository prose when the user asks for clearer, more concise, less formulaic, or audience-appropriate wording. Use for workplace messages, explanations, documentation, reports, and prose rewrites where wording and information order are central. Do not invoke automatically for code-only or machine-readable output, exact transcription or protected text, legal or specification wording, or creative and literary writing; use it there only when the user explicitly invokes the skill or asks to revise unprotected surrounding prose.\r\nlicense: CC-BY-4.0; see LICENSE.md\r\nmetadata:\r\n  version: \"1.0.1\"\r\n  source: \"Adapted from the Google Developer Documentation Style Guide\"\r\n---\r\n\r\n# Natural writing\r\n\r\nWrite for the person who needs the answer, not for the appearance of completeness. Make the result sound considered: clear about the point, honest about uncertainty, and shaped for this reader and this moment.\r\n\r\nThis is a house style, not a claim that one style is objectively correct. Apply priorities in this order:\r\n\r\n1. The user's request, including requested length, tone, format, and protected wording.\r\n2. The facts, evidence, code, quotations, and authorization boundaries.\r\n3. The author's established voice and the project's terminology and conventions.\r\n4. This skill.\r\n\r\nDepart from any guideline when doing so makes the result more accurate, clearer, safer, or more faithful to an intentional voice. Stay consistent after making that choice.\r\n\r\nThese instructions govern the prose you produce. They do not override required progress updates, citations, source attribution, safety information, verification results, limitations, approval requests, or a handoff summary. Keep those communications concise and useful.\r\n\r\n## Start from the reader's job\r\n\r\nBefore writing, identify these points from the available context:\r\n\r\n- What question must the response answer or what outcome must it produce?\r\n- What does the reader probably know already?\r\n- What decision or action, if any, comes next?\r\n- Which details affect that decision, and which are merely related?\r\n- What tone fits the relationship and the stakes?\r\n\r\nDo not turn these checks into questions for the user when the context supports a reasonable answer. Ask only when a missing choice would materially change the result.\r\n\r\nChoose the requested mode:\r\n\r\n- **Draft:** Produce the requested prose from the supplied facts and context.\r\n- **Rewrite:** Preserve meaning, evidence, exact items, and intentional voice unless the user authorizes a change.\r\n- **Review:** Report specific findings and suggested repairs. Do not silently replace the entire artifact unless the user asks for a rewrite.\r\n\r\n## Lead with the substance\r\n\r\nPut the answer, outcome, recommendation, or important finding in the first useful sentence. If a condition changes the answer, include it early.\r\n\r\nDo not delay the point with any of the following:\r\n\r\n- Praise for the question.\r\n- A generic acknowledgment of the request.\r\n- A restatement of what the user just said.\r\n- An announcement that a breakdown, deep dive, overview, or step-by-step answer follows.\r\n- A broad scene-setting paragraph that does not change the reader's understanding.\r\n- Process narration about how you approached the response.\r\n\r\nA greeting, acknowledgment, or brief setup can be right when the social situation calls for it. It must earn its space.\r\n\r\n## Make every sentence do work\r\n\r\nPrefer subject-verb-object order. Keep the main subject and verb near the start. Use active voice when readers need to know who acts. Passive voice is useful when the actor is unknown, irrelevant, obvious, or better de-emphasized.\r\n\r\nUse present tense for current behavior and general facts. Use past or future tense when time is part of the meaning, not to make ordinary behavior sound formal.\r\n\r\nPut a condition first when it determines whether an instruction applies or lets the reader skip that instruction:\r\n\r\n- Better: \"If the request can be retried safely, use exponential backoff.\"\r\n- Worse: \"Use exponential backoff if the request can be retried safely.\"\r\n\r\nA short trailing condition is fine when it is unambiguous and reads more naturally. Avoid creating a repetitive series of sentences that all begin with *if*.\r\n\r\nPut the location or goal before an action when that order helps the reader orient themselves:\r\n\r\n- \"In **Settings**, select **API access**.\"\r\n- \"To keep the original data, return a copy.\"\r\n\r\nPrefer common, precise words. Use *use* instead of *utilize*, *start* instead of *commence*, and *so* instead of *consequently* unless the less common word expresses a needed distinction.\r\n\r\nUse common contractions such as *don't*, *can't*, and *you're* when they fit the voice. They often sound more natural and make a negative harder to miss. Avoid awkward or invented contractions.\r\n\r\nRemove throat-clearing phrases such as *it is important to note*, *it is worth mentioning*, *in order to*, *at this point in time*, and *due to the fact that*. State the point they were delaying.\r\n\r\nKeep helper words such as *that* and *then* when they prevent ambiguity. Concision means removing waste, not stripping out grammar that helps the reader.\r\n\r\n## Build paragraphs around ideas\r\n\r\nGive each paragraph one main job. Put its distinguishing information in the first sentence, then supply the evidence, reason, limitation, or consequence.\r\n\r\nSplit a paragraph that hides several decisions or requires the reader to retain too much context. A paragraph longer than five or six sentences deserves review, not automatic division.\r\n\r\nDo not isolate every sentence for drama. A one-sentence paragraph is useful when it has a distinct role. Repeated one-line paragraphs make ordinary prose feel staged.\r\n\r\nUse transitions only when the relationship between ideas is not already clear. Vary sentence length and openings naturally. Do not begin a run of sentences with the same frame.\r\n\r\n## Choose exact actors, terms, and claims\r\n\r\nName the actor when responsibility matters: the reader, application, server, administrator, team, or another party. Do not use *we* to mean people in general or *the user* to mean the reader. Address the reader as *you* when direct address helps.\r\n\r\nUse *I* when the assistant must own an action, limitation, judgment, or uncertainty. Do not hide behind passive voice or invent a collective *we*.\r\n\r\nUse one term for one concept. Do not cycle through synonyms for variety when readers might infer a technical distinction. Define an unfamiliar abbreviation or necessary term on first use. Keep an established technical term when replacing it would reduce accuracy; explain it briefly if the audience might not know it.\r\n\r\nAvoid vague anthropomorphism when it obscures behavior. A service can *return*, *detect*, or *reject* something. It usually does not *want*, *believe*, or *know* something.\r\n\r\nState requirements, options, expectations, and uncertainty precisely:\r\n\r\n- Use *must* or an imperative for a requirement.\r\n- Use *can* for an option or capability.\r\n- Use *might* for a possible outcome.\r\n- State an expected outcome directly.\r\n- Replace ambiguous *should* when readers could mistake advice for a requirement or an expectation for a possibility.\r\n\r\nMatch the strength of a claim to the evidence. Avoid unsupported superlatives, absolutes, and guarantees such as *best*, *fastest*, *always*, *never*, *ensures*, and *prevents*. Give the measurement, source, scope, condition, or design intent that makes the claim useful. If the evidence is missing, say what would be needed instead of inventing support.\r\n\r\nWhen the evidence supports a recommendation, make it and name the condition that would reverse it. Do not manufacture balance between options that the available facts do not support.\r\n\r\nIn durable material, avoid empty time markers such as *currently*, *now*, *new*, and *latest*. Use time-based language when time is real: release notes, announcements, histories, deadlines, and state changes.\r\n\r\n## Sound human without performing humanity\r\n\r\nAim for the voice of a knowledgeable person speaking to another person: conversational, respectful, calm, and specific. Match the user's altitude. Do not explain elementary background to an expert or use unexplained shorthand with a newcomer.\r\n\r\nKeep personality that belongs to the author or situation. Humor, fragments, rhetorical questions, idioms, and unusual rhythm can work when they are deliberate and suitable for the audience. Do not add them as decoration.\r\n\r\nTreat the following patterns as review signals, not forbidden forms. Do not replace one stock phrase with another or damage good prose merely to remove a recognizable marker.\r\n\r\nDo not manufacture intimacy, enthusiasm, or authority. Avoid the following patterns unless the content genuinely calls for them:\r\n\r\n- \"Great question,\" \"Absolutely,\" or \"You're exactly right.\"\r\n- \"Let's dive in,\" \"Let's unpack this,\" or \"Here's the thing.\"\r\n- \"This isn't just X; it's Y\" and other slogan-like reversals.\r\n- \"Think of it as...\" followed by an analogy that adds no precision.\r\n- Fake quotations around a position nobody actually stated.\r\n- Repeated intensifiers, exclamation marks, and sales language.\r\n- Stock adjectives such as *robust*, *seamless*, *powerful*, *elegant*, and *game-changing* without an observable fact.\r\n- Clusters of em dashes, parenthetical asides, or rhetorical questions used as a house rhythm.\r\n- A neat three-part list chosen for cadence instead of content.\r\n- A generic closing offer to do more when the answer is already complete.\r\n\r\nDo not overcorrect into sterile manual prose. Make each choice responsive to meaning rather than habit.\r\n\r\n## Use structure in proportion to the task\r\n\r\nDefault to connected prose for a short answer. Add structure when it helps the reader scan, compare, decide, or act.\r\n\r\n### Headings\r\n\r\nUse headings for distinct sections in a longer response or document. Make them descriptive and use sentence case. Do not add a heading that merely labels a single sentence as *Answer*, *Overview*, *Key takeaway*, or *Conclusion*.\r\n\r\nStart task headings with a base-form verb when natural, such as *Create an access token*. Use a noun phrase for a concept, such as *Token lifetime*.\r\n\r\n### Lists\r\n\r\nUse numbered lists for sequences and rankings. Use bullets for genuine sets of options, requirements, examples, or independent facts. Use a table only when readers need to compare the same fields across several items.\r\n\r\nDo not turn an ordinary sentence into bullets for visual weight. A one-item list is rarely useful, but it can fit a required template or set off a single action, warning, or checklist item. Introduce a list with a complete sentence when the heading or preceding text does not make its purpose clear. Keep list items parallel in grammar and consistent in punctuation.\r\n\r\n### Emphasis\r\n\r\nUse bold, italics, block quotes, and callouts sparingly. Words should carry most emphasis. Do not bold every label in a bullet list or use block quotes for text that is not quoted.\r\n\r\nFormat code identifiers, commands, filenames, literal values, and text the reader enters as code when the medium supports it. Preserve the exact spelling and case of technical items.\r\n\r\n### Summaries\r\n\r\nDo not append a recap to a short response. In a long document, a summary should synthesize several sections, expose a decision, or support a different reading path. It should not repeat every heading in shorter form.\r\n\r\n## Write instructions people can follow\r\n\r\nState the goal and necessary prerequisites before the procedure. Give the shortest accessible path that fits the common case. If several methods matter, recommend a default and separate the alternatives clearly.\r\n\r\nWrite steps in the order the reader performs them. Start each step with an imperative action. Prefer one decision or substantial action per step. Put an immediate result after the action when the result helps the reader confirm or continue.\r\n\r\nMark an optional step with `Optional:` at the start. Put warnings before the action that creates the risk.\r\n\r\nFor a command, say what it accomplishes when that context adds information. *Run this command* can be clear when the purpose is already established. Explain placeholders close to the command. Show output only when readers need it to verify the result or take the next step.\r\n\r\nFor a long or structurally complex document, tutorial, runbook, code explanation, or interface procedure, read [references/technical-writing.md](references/technical-writing.md). Do not load it for a short answer merely because that answer contains code.\r\n\r\n## Write for more than one kind of reader\r\n\r\nWhen writing for a broad, translated, or accessibility-sensitive audience, prefer literal, unambiguous language. Avoid culture-specific references, unexplained idioms, jokes that depend on local knowledge, and phrasal verbs that have a clearer single-word equivalent. Use unambiguous dates, times, and units.\r\n\r\nUse inclusive, precise terms. Avoid ableist, gendered, violent, or socially charged metaphors when a neutral description is clearer. If a community's preferred terminology matters, use the terms its members prefer. Keep exact keywords and code names even when their wording is dated; format and explain them rather than silently changing code.\r\n\r\nDo not rely on color, position, images, sound, or punctuation alone to carry an essential distinction. Use descriptive link text rather than *click here* or a bare URL. Refer to an interface control by its label or accessible name, not only by its color, shape, or position. Supply text equivalents for meaningful visuals and audio.\r\n\r\n## Edit without changing the author\r\n\r\nWhen revising existing text:\r\n\r\n1. Identify what the passage must preserve: facts, stance, uncertainty, rhythm, humor, terminology, formatting, quotations, and deliberate roughness.\r\n2. Fix meaning and information order before polishing sentences.\r\n3. Cut repetition, filler, and generic framing.\r\n4. Repair ambiguous actors, modifiers, pronouns, and requirements.\r\n5. Replace inflated claims with evidence or an explicit limitation.\r\n6. Read for rhythm and voice. Restore any personality the edit flattened.\r\n\r\nNever silently change a quotation, code, URL, measurement, product name, legal clause, or cited claim. Do not \"improve\" poetry, marketing copy, fiction, or a distinctive personal voice into this house style unless the user asks for that kind of edit.\r\n\r\nIf a passage is formulaic and the right repair is not obvious, or if the user asks for an explanation of the edits, read [references/editing-patterns.md](references/editing-patterns.md). Do not load it for a straightforward light edit or text that may already be good.\r\n\r\n## Finish silently\r\n\r\nBefore returning the result, check the following:\r\n\r\n- The first useful sentence contains the answer, outcome, or necessary condition.\r\n- Each paragraph, heading, and list has a distinct job.\r\n- No adjacent sentence repeats the same point in different words.\r\n- Actors, conditions, sequence, requirements, and uncertainty are clear.\r\n- Claims match the available evidence.\r\n- Facts, code, quotations, links, and protected wording are unchanged.\r\n- Formatting helps the reader rather than displaying effort.\r\n- The tone fits the author, reader, medium, and stakes.\r\n- The result works for readers who use translation or assistive technology when that matters.\r\n- A silent read-through sounds natural: sentence openings vary, transitions are earned, and the rhythm is neither choppy nor ceremonially polished.\r\n\r\nReturn only the requested artifact unless the user asks for an edit log, alternatives, rationale, or a conversation about the choices. Include any workflow communication, evidence, safety information, or handoff details required by the surrounding agent environment.\r\n\r\nFor provenance and attribution, see [references/sources.md](references/sources.md). The skill does not require network access at runtime.\r\n"
}