product-writing git:20260907.bd497bdA

Immutable. This exact content is served forever at /api/v1/blob/c4a9c27b46127dcd.

---
name: product-writing
description: "Write, edit, or review product interface copy, CLI messages, help text, and technical documentation. Use when explaining product behavior, errors, status, setup, compatibility, or technical results. A compact alternative to ux-writing that preserves accuracy and reader context while leaving structure and phrasing to the task. Ordinary conversation, personal voice writing, and code-only reviews are outside its scope."
license: Apache-2.0
metadata:
  author: scarletkc
  source: https://github.com/scarletkc/agents
  summary: "Write accurate product copy and useful technical docs with a compact alternative to ux-writing."
---

# Product Writing

Help the reader understand what is happening and what they can do next.
This skill is self-contained and can be used in place of `ux-writing`.
Use one of these alternatives for a task; there is no prerequisite review
with the other skill.

## Work from the task

Use only the sections relevant to the requested copy. Preserve the user's
meaning, terminology, audience, and requested format. Follow existing product
conventions where they help readers recognize controls, commands, and states.
A wording task does not itself authorize changes to product behavior or a
reorganization of the documentation.

Ground behavioral claims in supplied facts, the relevant implementation or
specification, or an observed result. When a fact cannot be verified, identify
that uncertainty where it matters and complete the parts that are supported.
Do not invent behavior or a cause to make the text sound complete.

## Interface copy, errors, and help

- **Name the action or state accurately.** Distinguish saving a setting from
  testing a connection, accepting a request from completing a job, and partial
  success from full success. For example, a queued export should not announce
  that a file is ready to download.
- **Make recovery useful.** Identify what failed and the relevant input or
  operation. Include a next step when it is known and actionable. An unknown
  network failure does not establish that credentials are wrong. Put detail
  in the message, an expanded view, or a specific help link as the interface
  allows; an error need not fill a fixed template.
- **Preserve meaningful distinctions.** Keep prerequisites, limits, and
  consequences that affect the reader's decision. Use the product's names for
  controls and commands. Do not shorten away which item an action affects or
  imply that an irreversible action is temporary.

## Status and diagnostic output

- **Describe the state the label promises.** Effective settings account for
  runtime overrides; stored settings should be identified as such. If only
  the API key comes from the environment, label that field rather than the
  entire endpoint as environment-provided.
- **Keep failure visible.** Distinguish unknown or unavailable values from
  empty, missing, or default values. If partial results are supported, identify
  what could not be checked. Follow the project's failure behavior instead of
  introducing a fallback merely to produce a message.
- **Preserve output contracts.** Keep prose and decoration out of JSON, TSV,
  and other machine formats. Use existing diagnostic channels for explanations.
  Keep paths, IDs, and commands complete where users need to copy them, subject
  to the product's redaction rules.
- **Choose useful detail.** A health summary may emphasize problems; an
  inspection view may need complete values. Preserve the context needed for
  either use, and check adjacent labels for duplication or ambiguity.

## Documentation and technical explanations

- **Keep explanations that earn their place.** A short rationale can belong
  beside a setup step. Reports need enough method, source context, assumptions,
  and limitations for readers to assess the findings. Remove production chatter
  and abandoned options that add no useful context; retain relevant tradeoffs
  and requested design history.
- **Avoid competing specifications.** Keep a maintained source for detailed
  contracts and link other pages to it. Summaries and examples beside links
  can make a page usable on its own. Check repeated details for agreement;
  duplication alone is not a reason to delete useful context.
- **Scope changeable facts.** Supported versions, pinned installation commands,
  and compatibility limits may be essential. Check them against the maintained
  source. Date runtime observations in reports; point to a live check when the
  reader needs current state. A merged change alone does not establish deployment.
- **Make the next reference useful.** Link to the section, command, API entry,
  or symbol that answers the reader's question. Keep caveats next to the steps
  they qualify. Preserve working anchors and requested structure; organize by
  the reader's task without imposing a fixed number of sections or purposes.

## Claims and evidence

Match the support to the claim. Performance comparisons need applicable
measurements or a cited result with its scope. Compatibility claims need the
relevant implementation or maintained specification. An editorial recommendation
can explain a concrete benefit, such as naming the failed field so the reader
can locate it; recommending clearer wording does not require a benchmark.

Keep observations, hypotheses, preferences, and recommendations distinct.
Preserve user-provided opinions as opinions. Qualify unsupported claims or
explain the gap rather than invent proof or erase useful uncertainty.

## Review and verification

In a review, identify the wording, its effect on the reader, and a concrete
correction when the evidence supports one. If the copy already works, say so;
optional preferences should not become required rewrites. For an editing task,
make the requested edits and explain consequential choices only as needed.

Check meaning, terminology, formatting, and affected links. When behavior
changes, search for dependent help text, errors, documentation, and bundled
skill descriptions that need the same update. Keep catalog and localization
entries in sync where applicable; avoid turning a small edit into a general audit.

Use the project's relevant checks. When output behavior changes, cover success
and failure: parse machine formats and check channels; for human messages,
assert the relevant information without relying on incidental wrapping or color.