CommunityRedacción y edicióngithub.com

writing

Write and edit technical documents, ADRs, roadmaps, PR descriptions, commit messages, tickets, chat replies, and technical explanations in a direct, evidence-backed voice. Load before drafting or revising human-facing prose.

¿Qué es writing?

writing is a Claude Code agent skill that write and edit technical documents, ADRs, roadmaps, PR descriptions, commit messages, tickets, chat replies, and technical explanations in a direct, evidence-backed voice. Load before drafting or revising human-facing prose.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fsodano/writing-skills/tree/HEAD/skills/writing

Installed? Explore more Redacción y edición skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Writing and editing

Follow these rules whenever drafting or revising text for humans: documents, ADRs, executive summaries, tickets, PR descriptions, commit messages, chat replies, or technical explanations.

The goal of every artifact is to keep cognitive debt (eroded shared mental models across people) and intent debt (missing externalized rationale, goals, and constraints) low.

1. Audience, structure, and prerequisite order

  • Identify the reader first (executive/leadership, QA, engineer, support vendor, learner) and match technical depth to what they know and need to decide. Strip internal CLI flags, token mechanics, variable names, and repo trivia when writing for non-engineers.
  • Write as the author for the people who will read the finished work, not as an assistant narrating the chat. When an approved reference is supplied, follow its useful structure without copying unrelated material.
  • Plan or fix structure before wording. Introduce concepts, components, and option labels in strict prerequisite order—never reference an option letter, component, or rule before establishing what it is (for example, never mention Option C and Option D without accounting for Options A and B).
  • For mixed-audience proposals and ADRs, layer from simplest to most technical:
    1. Non-technical summary first: plain language, zero code, env vars, internal slugs, or option codes, plus one concrete before/after example.
    2. Current system context: only the primitives needed to understand the limitation, in strict dependency order.
    3. Proposed design: organized in conceptual/causal order (state that grouping upfront if it differs from implementation order).
    4. Decision boundaries: alternatives considered and not chosen -> consequences & trade-offs -> explicit dependencies.
  • For any proposal, explain the current problem and its effects before describing the proposed action. Explain what happens in plain language before naming the approach; place unresolved caveats and dependencies where readers need them.
  • For documents with an executive summary, settle the body first and draft the summary last so counts, scope, and conclusions match the finished text.

2. Clarity, examples, and isolated-section readability

  • Never assume the reader shares context with the repo, earlier attempts, or line numbers you happen to hold.
  • Pair abstract claims or pattern explanations with a concrete end-to-end example (a real URL, rule, payload, or before/after path). Place the example next to the point it illustrates; do not force a stock opening or an example into every paragraph.
  • Prove constraints by failure mode: When explaining why a rule, filter, or check is necessary, show what breaks if it is omitted (for example, "without filtering before applying the page limit, fetching four records can return zero matches even when the fifth record matches").
  • Never cite an ID, decision code, or internal token alone. Expand it inline, use plain names, and link every ticket, branch, or web URL in Markdown (never wrap a clickable URL in backticks): D07 (keep existing record IDs during import), import error report (not I03), [PROJ-123](https://example.com/issues/PROJ-123) (report rejected import rows).
  • Prefer explicit, unambiguous sentences over compressed shorthand ("When a page fails to migrate, that does not mean it is deprecated"). Name exact actions ("the import rejected rows with missing IDs", not "the import failed"). Use one fixed term per concept throughout.
  • Avoid analogies. Define each technical term fully where it first appears—never punt a term's meaning or mechanism to a later section ("Section 2 explains how", "discarded options are summarized in Section 3"). State what it does in plain words right where it first appears—even in a summary—or omit the term until its section.
  • Controlled redundancy for isolated reading: Readers often jump straight to a summary, a mid-document subsection, a code block, a risk table, or a dependency list. Add a brief inline gloss or 1-sentence reminder whenever a later standalone section relies on a term, symbol, or constraint defined earlier so each section makes sense on its own without scrolling back.

3. Evidence, honesty, and scope

  • Every number must name its linked source, column, filter, or file. Never cite unnamed sources ("the team confirmed", "reviewed and confirmed"). After a figure, state what was decided or what action follows, not just the number.
  • Match verb certainty to reality: use present tense for verified current behavior, "would" or "should" for proposed or conditional outcomes, and "must" for hard requirements.
  • Distinguish current behavior, prototype behavior, proposals, observations, and unknowns explicitly. Never present an unconfirmed recommendation as planned, approved, budgeted, or underway, and surface real unknowns or undecided workflows plainly instead of papering over them.
  • Problem-solution alignment: Only list a problem under "The problem today" as motivation if the proposal actually solves it. If the proposal leaves an existing problem unchanged, move it to risks/trade-offs and state plainly "No mitigation is proposed."
  • Snippet sources and primary docs: State explicitly whether each code or data snippet is current production code, real data, test/fixture data, prototype code, or an illustrative sketch. Link primary external documentation whenever citing platform or vendor behavior and constraints.
  • Never invent taxonomy or product terminology (for example, "companion rules"). Verify external tool/platform claims against primary docs before stating them; flag any conflict with the premise.
  • Write for the moment the reader opens the artifact. Describe only the final/current state—never build-to-build deltas, snapshot dates, "was X, now Y", or contrasts against discarded drafts ("do X instead of Y"). Omit true-but-confusing zero counts ("0 items need review").
  • A table that lists cases must list every case; never follow it with "N more...". Introduce each count group once.

4. Voice and style

  • Write like an engineer at a whiteboard—direct, concrete, and economical. Preserve author-supplied wording when editing; report factual errors separately in a short note rather than silently rewriting their prose.
  • Bans:
    • Slogans, motivational copy, corporate/keynote rhetoric, and paired abstract headings ("Every system tells a story; your journey continues" -> use plain topic names like "System architecture").
    • Rhetorical accumulation ("Not only X, but also Y"), artificial causal connectors on standalone principles ("That is why..."), colons used for dramatic punches, and double negatives ("there is no reason not to" -> "we can").
    • Preventive defensive disclaimers ("X does not mean Y: Z", "we are not promising..."), filler closing sentences ("the application retains full control of its rules and data"), and manufactured questions at the end of sections.
    • Hand-waving shortcuts that hide mechanisms ("simply", "automatically", "seamlessly", "handles the rest", "under the hood") and empty throat-clearing ("In this section we will explore...", "It is worth noting that...").
    • Pretentious or inflated vocabulary where a plain word works—explicitly banned: "provenance" (use "source" or "origin").
  • Proposals & ADRs: Prefer "This document proposes" over "We" when framing options for review, and frame recommendations constructively rather than declaring "we have a gap" in outward-facing client/leadership docs.

5. Artifact-specific rules

Reports, ADRs, roadmaps, and specs

  • Strip unrequested metadata headers (Author:, Standard:, Target Repository:), local file paths readers cannot access, and line numbers that drift on edit.
  • ADRs: Do not add a Status: header (Proposed, Accepted, Rejected)—ADR status is managed by the PR lifecycle (open = proposed, closed = denied, merged = accepted).
  • ADRs as source of truth: An ADR produced by a spike or discovery ticket IS the deliverable and source of truth, superseding raw ticket comments and exploratory notes. Never frame the spike/investigation as a separate upstream document ("from the discovery spike"). Only the spike's ADR and follow-up implementation tickets exist.
  • ADR scope discipline: Keep ADRs focused on architectural decisions, mechanisms, trade-offs, and dependencies. Include short code or data snippets only when they prove a current constraint or clarify a proposed mechanism, and explain every symbol used right beside the snippet. Omit premature implementation clutter (invented file paths, vendor UI click-paths, template syntax, rollout ticket checklists) unless a runbook or implementation plan is requested.
  • Merge genuinely duplicated sections, while keeping brief local reminders so each standalone section can be read in isolation without scrolling back.

PRs, commits, tickets, and chat

  • PRs and commits explain WHY, not HOW. Never include build/test verification dumps (npm run build: 12.20s), tool-call logs, or framework trivia ("uses $state").
  • Tickets & chat: Lead with the decision or action needed. List concrete affected items/examples when the set is small rather than bare counts ("list the 7, not '7 items fail'"). Omit internal working labels ("local rule pending deployment", "attempt1/2"). State open questions cleanly so the recipient knows what to decide.
  • Support / external: Omit internal secrets and credential names. When support needs to identify a resource, use a shareable identifier such as an account ID. Omit personal or org-politics context.
  • Copy-paste friendliness: When sharing URLs someone needs to copy, output them inside a plain fenced codeblock so chat Markdown does not auto-link them.

Technical explanations

  • Structure every explanation as: Direct answer (1–2 plain sentences in prerequisite order) -> Exact quoted rule/code/config (explaining every symbol beside it) -> One concrete end-to-end example (input -> what matches/runs -> output, plus what breaks without a key condition) -> Caveats or edge cases (only if asked or required to avoid a mistake).
  • Never refer to a line number, rule ID, or file without quoting the relevant rule, regex, or snippet inline—do not assume the reader holds the codebase in memory.
  • When a reader says "I don't understand", "simpler", or asks "what does this mean?", drop abstract framing immediately, locate the missing prerequisite, and trace a single real example step by step.
  • Use one fixed term per concept, define unfamiliar jargon where it first appears (and briefly re-ground it inline if a later standalone part of a long explanation relies on it), and use plain ASCII arrows (->), never $\rightarrow$.

6. Formatting, diagrams, and editing discipline

  • Use sentence case for headings (The problem today, not The Problem Today).
  • Use plain ASCII arrows (->), never LaTeX math ($\rightarrow$).
  • In lists whose items already contain "and", join the inner pair with "&" so list boundaries stay clear.
  • Never reintroduce text the author removed. When feedback identifies a recurring problem, inspect the entire artifact and fix clearly matching instances within the requested scope; leave unrelated content alone.
  • Diagrams: Prefer small, focused vertical flowcharts (such as Mermaid flowchart TB with explicit label wrapping) over wide multi-actor sequence diagrams that shrink text and force horizontal scanning. Split "Today" and "Proposed" into separate small diagrams (typically 3–5 nodes each) instead of packing the whole lifecycle into one diagram. Use plain reader-facing labels in nodes, never cryptic abbreviations or unintroduced vendor step names.
  • Verify diagrams in their rendered form, including the relevant themes or screen sizes when practical. If rendering cannot be checked, say so; source inspection alone is not visual validation.

7. Pre-output check

Before saving or sending finished prose, verify:

  1. Audience & scope: Depth matches the reader; non-technical summaries have zero code, env vars, slugs, or option codes; no internal paths, headers, premature implementation clutter, or verification dumps remain.
  2. Formatting: Headings are sentence case; arrows are -> (no $\rightarrow$).
  3. Order & isolated reading: Concepts, options, and identifiers appear in strict prerequisite order and are defined where first used; standalone sections include brief local reminders so they read cleanly in isolation; examples show key mechanisms and failure modes.
  4. Evidence & honesty: Every number names its source and decision; every snippet states whether it is real, test/fixture, prototype, or illustrative; unconfirmed recommendations never read as approved; unsolved problems sit in risks (with "No mitigation is proposed" if unmitigated), never under "The problem today".
  5. Voice & visuals: Zero banned phrases, hand-waving shortcuts, defensive disclaimers, or silently rewritten author wording; diagrams are simple, vertical when practical, and use plain labels.
  6. Cold-reader pass: Re-read as a first-time reader across the whole artifact—actions and consequences connect, no essential explanation is deferred to another section, and intentional removals are respected.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Skills relacionados