---
name: writing
description:
  "Shape prose that is read outside the session: blog posts and articles, changelogs and release
  notes, customer-facing docs, and replies, comments, or posts published under the user's name. Use
  when drafting or revising such text, or when asked to make writing clearer, shorter, or less
  AI-sounding. Not for code or code comments, commit messages, PR bodies (`pr`), delivery plans,
  agent instructions, marketing copy (`copywriting`), or routine chat replies."
argument-hint: "[article | changelog | docs | reply] [artifact or task]"
metadata:
  opencode/slash: "true"
---

# Writing

Shape text for a reader who was not in the session. Route by where the text will appear, match that
audience's register, and stop when the piece works. Owners of the content decide what must be in it;
this skill shapes how it reads.

## Route by destination

| Destination                                          | Read                                                    |
| ---------------------------------------------------- | ------------------------------------------------------- |
| Blog post, article, essay                            | [Public prose](references/public-prose.md)              |
| Search-focused article or SEO revision               | Public prose, then [blog SEO](references/blog-seo.md)   |
| Changelog, release notes, upgrade notes              | [Changelogs](references/changelogs.md)                  |
| README, guide, API reference, runbook for customers  | [Technical documentation](references/technical-docs.md) |
| Review reply, issue comment, post, or DM as the user | [Under the user's name](references/under-your-name.md)  |

Load a second route only for a distinct part of a mixed artifact. Read the project's voice and
positioning notes first when present, including `.agents/product-marketing.md`.

These belong elsewhere, and this skill does not run on them: PR titles and bodies (`pr`), delivery
plans (`delivery`), code comments and JSDoc (`craft`), skills and AGENTS.md (`skill-creator`,
`agent-rules`), marketing copy such as landing pages, CTAs, and headlines (`copywriting`), and
status updates in chat (the global rules).

## Register per audience

- **Public readers:** follow the project's product-marketing canon for voice and claims. Lead with
  what the reader can do; name the product behavior, not its adjectives.
- **Under the user's name:** short, plain, and conversational. Match how the user writes in that
  venue, including casing and punctuation, and keep only what the recipient needs.
- **Durable docs:** describe the current state. History, migration archaeology, and superseded
  designs belong in Git and `.scratchpad`, not in the docs.

Keep internal details out of anything public: codenames, other products or customers, internal
paths, and unreleased plans, unless the user put them there.

## Cut without losing information

When shortening, remove restatement, history, commit or file inventories, routine validation
narration, and filler. Keep examples, lists, qualifiers, limits, and exact identifiers. A list of
real items stays a list; do not fold it into a paragraph.

After any pass that removes more than about a third of the text, report one line naming what went,
so the user can ask for it back:

```text
Dropped: commit list, lockfile hash, test inventory (kept in the delivery report).
```

## Style signals

Treat stylistic patterns as signals to examine, not errors: generic praise, inflated claims, vague
attribution, canned transitions, "not X but Y" constructions, and repeated sentence shapes. Change
one only when the change adds clarity. Typography such as heading case and dashes follows the
project; there is no universal banned-word list. Never invent metrics, sources, experience, or
personality to make text sound human.

## Workflow

1. Identify the destination, the reader, and the requested edit depth.
2. Read the selected route and the content owner's contract when one applies.
3. Draft or edit within scope. Leave clear passages unchanged.
4. Check factual claims, links, code snippets, and rendered structure against current evidence.
5. Return the text, the dropped-content line when it applies, and any unresolved choice.

Drafting grants no permission to publish, post, send, or change product behavior to match the prose;
the workflow that owns those actions still applies.