product-writing

Files (2)

• SKILL.md
• evals.json · evals/

SKILL.md (first lines)

# Product Writing

Help the reader understand what is happening and what they can do next.

## 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.
- **Give diagnostic views distinct jobs.** When a dedicated inspection command
  already provides all values and origins, a health summary can focus on
  deviations, failures, and their sources, with a pointer to full details.
  Without that separate view, preserve the values needed to investigate the
  problem. Fifteen normal `field: origin` rows can bury the two overrides that
  matter, but removing the only available configuration view loses information.
  Re-read adjacent labels to catch duplication such as `default (default)`.

## Documentation and technical explanations

- **Give each page one responsibility.** A how-to completes an operation, a
  reference defines a contract, a design record explains choices, and a report
  presents findings and their basis. Put a section on the page that owns its
  reader question. When a page mixes independent tasks, separate them and leave
  a useful pointer at the boundary. An overview's responsibility is orientation:
  summarize the available paths and link to their details instead of becoming
  a second reference manual.
- **Keep README sections focused.** The introduction identifies the product,
  its audience, and its purpose. Positioning explains why someone would choose
  it. Quick-start instructions give the shortest complete path to a useful
  result, including prerequisites, commands, and essential caveats. Full option
  catalogs, architecture explanations, and decision histories belong in their
  respective documents, linked from the relevant section. Do not turn a quick
  start into an architecture tour or a positioning section into a feature dump.
  Keep a compatibility warning beside the step it affects; moving background
  detail must not hide a condition needed to follow the instructions safely.
- **Keep reasons near the decisions they support.** A setup step may need a
  short explanation of why a prerequisite matters. A long history of rejected
  designs usually belongs in a design record linked from the guide, unless
  that history is the page's purpose. Reports need enough method, source context,
  assumptions, and limitations for readers to assess the findings.
- **Separate summaries from competing specifications.** Keep one maintained
  source for a detailed contract. A summary explains what the reader needs now;
  a second complete field table, default list, or precedence rule creates
  another specification to maintain. For example, a README can show a minimal
  configuration and link to the full schema instead of copying all seven fields
  into another table. Detailed repetition may be necessary for independently
  distributed artifacts; check how those copies stay synchronized.
- **Plan how changeable facts stay correct.** Supported versions, pinned install
  commands, and compatibility limits may be necessary. Verify them against the
  maintained source, then check what will keep them aligned on the next change:
  generation, an existing release check, or an explicit maintenance responsibility.
  Avoid adding a second hand-maintained copy of a build ID, migration count, or
  current deployment version just to make a page self-contained. Prefer a
  pointer or generated value when the reader needs the current answer. Preserve
  version constraints that are part of the instructions; do not remove them
  simply because versions change.
- **Distinguish records from live state.** A dated report can record the version
  and status actually observed, with the evidence and limits of that observation.
  A standing operational guide should direct readers to the command or dashboard
  that answers what is running now. A merged change alone does not establish
  deployment, and a successful deployment alone does not establish every health
  or verification claim.
- **Make the next reference useful.** Link to the section, command, API entry,
  or symbol that answers the reader's question. For implementation details,
  `PROTOCOL_VERSION` is a useful pointer; a repository root leaves the reader
  to search again. For normal setup, prefer user-facing instructions. Keep caveats
  next to the steps they qualify and preserve working anchors.

## Comments and standalone artifacts

Read titles, comments, and deliverables as someone who has not seen the working
conversation. Remove abandoned options and temporary scope qualifications that
make sense only in that conversation. An export button title does not need
"without the bulk-download panel" if readers were never offered such a panel.
Keep exclusions when they explain a real contract, compatibility limit, or
tradeoff the reader needs; preserve history in documents requested to record it.

Comments are most useful for reasons the code does not make apparent: ordering
constraints, upstream defects, compatibility workarounds, and invariants a later
edit could break. Explain an alternative when it is one a maintainer would
reasonably reach for. For example, a comment explaining why a lock must be

From scarletkc/agents, Apache-2.0.

More from scarletkc/agents